Виртуальные ресурсы в Puppet

от
Прочее   devops

Как мне кажется, основной смысл виртуальных ресурсов становится более понятен уже на конкретных примерах с экспортируемыми ресурсами — когда виртуальные ресурсы помещаются в базу и используется для обмена информацией между агентами, но чтобы понять рекурсию, нужно понять рекурсию, поэтому начнем с локального применения. На примере.

Пример будет немного синтетическим. Мне было сложно придумать достаточно короткий пример, при этом демонстрирующий смысл виртуальных ресурсов. На практике такие примеры с вшитыми именами пользователей встречаются редко. По крайней мере должны.

Имеется сервер с установленным Apache. Установка и настройка производится удобно и модно puppet-классом apache. Для простоты все будем хранить в основном манифесте site.pp. Все появляющиеся проблемы в ходе развития примера актуальны и в случае разнесения кусков логики по модулям.

Допустим, классу необходим unix-пользователь, в данном примере webUser, домашний каталог которого будет являться document root'ом для веба. Тогда получим следующий скелет site.pp:
  1. class apache {
  2.     user { 'webUser' : ensure => present }
  3.     ...
  4. }
  5. node default {
  6.     include apache
  7. }

Все просто. Теперь мы решили добавить в нашу инфраструктуру nginx неважно для каких целей. Главное, что ему тоже нужен пользователь webUser для отдачи контента. Добавляем класс:
  1. class apache {
  2.   user { 'webUser' : ensure => present }
  3. }
  4.  
  5. class nginx {
  6.    user { 'webUser' : ensure => present }
  7. }
  8. node default {
  9.   include apache
  10.   include nginx
  11. }

Запускаем:
  1. root@puppet:/vagrant# puppet apply ./site.pp --noop
  2. Error: Duplicate declaration: User[webUser] is already declared in file /vagrant/site.pp:17; cannot redeclare at /vagrant/site.pp:11 on node puppet.example.com
  3. Error: Duplicate declaration: User[webUser] is already declared in file /vagrant/site.pp:17; cannot redeclare at /vagrant/site.pp:11 on node puppet.example.com

По понятным причинам оно не работает. Получается, что в одной области видимости у нас два ресурса с одинаковым значением namevar. Решить проблему можно, например, вынеся ресурс пользователя в отдельный класс:
  1. class users {
  2.   user { 'webUser' : ensure => present }
  3. }
  4.  
  5. class nginx  { include users }
  6. class apache { include users }
  7.  
  8. node default {
  9.   include apache
  10.   include nginx
  11. }

Запускаем — работает:
  1. root@puppet:/vagrant# puppet apply ./site.pp --noop
  2. Notice: Compiled catalog for puppet.example.com in environment production in 0.07 seconds
  3. Notice: /Stage[main]/users/User[webUser]/ensure: current_value absent, should be present (noop)
  4. Notice: Class[users]: Would have triggered 'refresh' from 1 events
  5. Notice: Stage[main]: Would have triggered 'refresh' from 1 events
  6. Notice: Finished catalog run in 0.02 seconds

Предположим, что нам понадобилось добавить нового пользователя cacheUser, в папке которого мы будем хранить какой-либо кэш. Этим кэшем пользуется как Apache, так и nginx, поэтому мы добавляем соответствующего пользователя в класс users:
  1. class users {
  2.   user { 'webUser':   ensure => present }
  3.   user { 'cacheUser': ensure => present }
  4. }

Далее мы решили добавить php5-fpm и uwsgi, которым нужен webUser, но не нужен cacheUser. В такой ситуации придется выделять cacheUser в отдельный класс, чтобы подключать его отдельно только в классах apache и nginx. Это неудобно. К тому же нет гарантий, что чуть позже не придется выделить еще одного пользователя в отдельный класс. Тут-то на помощь и приходят виртуальные ресурсы.

Если к определению ресурса добавить знак @:
  1. @user { 'webUser': ensure => present }

Ресурс будет считаться виртуальным. Такой ресурс не будет добавляться в каталог агента до тех пор, пока мы явно не определим. Из документации:
A virtual resource declaration specifies a desired state for a resource without adding it to the catalog
Поэтому если исполнить код ниже даже при отсутствии в системе пользователей webUser и cacheUser они добавлены не будут:
  1. class users {
  2.   @user { 'webUser': ensure   => present }
  3.   @user { 'cacheUser': ensure => present }
  4. }
  5. class nginx { include users }
  6. class apache { include users }
  7.  
  8. node default {
  9.   include apache
  10.   include nginx
  11. }

Проверяем:
  1. root@puppet:/vagrant# puppet apply ./site.pp
  2. Notice: Compiled catalog for puppet.example.com in environment production in 0.07 seconds
  3. Notice: Finished catalog run in 0.02 seconds

Пользователи, как и ожидалось, не добавились.

Но следует быть внимательным. Несмотря на то, что виртуальный ресурс не добавляется в каталог, это не значит, что следующий код будет работать:
  1. class apache {
  2.     @user { 'webUser' : ensure => present }
  3. }
  4.  
  5. class nginx {
  6.     @user { 'webUser' : ensure => present }
  7. }
  8.  
  9. node default {
  10.     include apache
  11.     include nginx
  12. }

Он по-прежнему будет выдавать ошибку компиляции. Это происходит потому, что сначала парсер puppet итерируется по всем ресурсам, добавляя в каталог даже витруальные. На этом этапе этапе и возникает ошибка из-за дублирования имен. Следующий этап — обработка реализации виртуальных типов: коллектор ищет в каталоге места, в которых виртуальные ресурсы определяются и найденные помечает как не виртуальные. И лишь в самом конце происходит очиска каталога от виртуальных ресурсов, которые не были бы реализованы.

Для определения ресурса используется либо spaceship оператор < | | > либо с помощью функция realize. Перепишем наш манифест с использованием как одного так и другого синтаксиса:
  1. class users {
  2.   @user { 'webUser': ensure   => present }
  3.   @user { 'cacheUser': ensure => present }
  4.  
  5. }
  6. class nginx {
  7.   include users
  8.   realize User['webUser'], User['cacheUser']
  9. }
  10. class apache {
  11.   include users
  12.   User <| title == 'webUser' or title == 'cacheUser' |>
  13. }
  14.  
  15. node default {
  16.   include apache
  17.   include nginx
  18. }

В функцию realize можно передавать сразу несколько ресурсов, а в операторе <| |> можно указывать несколько условий, по которым делается поиск ресурсов для определения.

Помимо синтаксической разница в realize и <| |> имеются отличия и в поведение. Если ресурс с указанным названием не существует realize выдаст ошибку:
  1. Error: Failed to realize virtual resources User[nonExistingUser] on node puppet.example.com

Оператор <| |> в таком случае ошибку не выдает, потому что он является своего рода надстройкой над функцией realize. Ко всем найденым ресурсам по заданному в его теле поисковому запросу применяется функция realize. Соотвественно, если не нашлось ресурса по заданным критериям ошибки не возникает, так как не вызывается функция realize.

Кстати, у оператора <| |> есть еще два достаточно хороших применения. Его можно использовать для переопределения состояния ресурса в классе. Например:
  1. class configurations
  2. {
  3.   file { '/etc/nginx.conf'   : ensure => present }
  4.   file { '/etc/apache2.conf' : ensure => present }
  5. }
  6. node s1.example.com {
  7.   include configurations
  8. }
  9. node s2.example.com {
  10.   include configurations
  11.   File <| title == '/etc/apache2.conf' |> { ensure => absent }
  12. }

Исключит файл /etc/apache2.conf для ноды s2.example.com.
Также его можно использовать с операторами ~> и ->. Таким образом, мы можем уведомить все сервисы о каких-либо изменениях, либо потребовать перед установкой любого пакета добавить все yum репозитории:
  1. Yumrepo <| |> -> Package <| |>

Как мне кажется, основным преимуществом виртуальных ресурсов является то, что их можно экспортировать и делать доступными для других агентов. Чтобы экспортировать виртуальный ресурс необходим добавить еще один знак @ перед его описанием.

Классический пример из документации Puppet:
  1. class ssh {
  2.       # Declare:
  3.       @@sshkey { $hostname:
  4.         type => dsa,
  5.         key  => $sshdsakey,
  6.       }
  7.       # Collect:
  8.       Sshkey <<| |>>
  9. }

В данном примере мы определили виртуальный ресурс sshkey. Оператор-коллектор <<| |>> содержит пустое тело, поэтому выгружает все экспортированные объекты класса Sshkey. Таким образом, любой агент, в манифесте которого подключается класс ssh, экспортирует свой публичный ключ (@@sshkey), а затем импортирует к себе все ключи, добавленные другими агентами (Sshkey <<| |>>).

Экспортируемые ресурсы хранятся в PuppetDB — БД от PuppetLabs. После подключение PuppetDB каждый скопилированный pupet master'ом каталог кладется в базу PuppetDB, которая в свою очередь предоставляет поисковый интерфейс для поиска по каталогам.

Указывая @@, мы помечаем ресурс как экспортируемый и информируем puppet, что ресурс необходимо добавить в каталог и поставить ему метку exported. Когда puppet master видит оператор <<| |>>, он делает поисковый запрос к PuppetDB и добавляет все найденные экспортированные ресурсы, подходящие под критерий поиска.

Важно, что экспортированные ресурсы находятся в глобальной области видимости, поэтому их названия должны быть уникальными.

У этого функционала огромный потенциал и мне достаточно часто приходится им пользоваться. Автоматизация добавления серверов в мониторинг или nginx бэкендов.

Лучше использовать существующие модули, но для демонстрации принципа данный пример подойдет:
  1. #Класс описывающий бэкенд и экспортирующий в базу строку вида "server IP:PORT;"  которая будет затем добавлен в блок upstream в nginx
  2. class nginx::backend($ip = $::ipaddress, $port = 8080) {
  3.   @@concat::fragment { "$::fqdn" :
  4.     content => "server $ip:$port;",
  5.     tag => 'nginx-backend',
  6.     target => '/etc/nginx/conf.d/backend.conf'
  7.   }
  8. }
  9. #Класс описывающий фронтенд, в котором объявлется ресурс concat, который далее склеивает все фрагменты экспортированные в nginx::backend
  10. class nginx::frontend {
  11.   concat { '/etc/nginx/backend.conf' :
  12.     ensure            => present,
  13.     force             => true,
  14.     ensure_newline    => true
  15.   } ~> Class['::nginx::service']
  16.  
  17.   concat::fragment { 'upstream_header':
  18.     content  => 'upstream backend { ',
  19.     order    => '01',
  20.     target   => '/etc/nginx/backend.conf',
  21.    }
  22.  
  23.   concat::fragment { 'upstream_footer' :
  24.     content  => '}',
  25.     order    => '03',
  26.     target  => '/etc/nginx/backend.conf'
  27.   }
  28.   #Импортируем все фрагменты
  29.   Concat::Fragment <<| tag == 'nginx-backend' |>>  { target => '/etc/nginx/backend.conf', order => '02' }
  30. }
  31.  
  32. class nginx::install {
  33.   package { 'nginx' : ensure => present }
  34. }
  35.  
  36. class nginx::service {
  37.   service { 'nginx' : ensure => running, require => Class['nginx::install'] }
  38. }
  39.  
  40. class nginx {
  41.   class { 'nginx::install' : } -> class { 'nginx::service': }
  42. }
  43.  
  44. node 'back1.example.com' {
  45.   class { 'nginx' : }
  46.   class { 'nginx::backend' : port => 8083 }
  47. }
  48.  
  49. node 'back2.example.com' {
  50.   class { 'nginx' : }
  51.   class { 'nginx::backend' : port => 8084 }
  52. }
  53.  
  54. node 'front1.example.com' {
  55.   class { 'nginx' : }
  56.   class { 'nginx:::frontend' : }
  57. }

Более подробную информацию о синтаксисе и паттернах использования можно найти по следующим ссылкам:
     docs.puppetlabs.com/puppet/latest/reference/lang_virtual.html
     docs.puppetlabs.com/puppet/latest/reference/lang_exported.html
     docs.puppetlabs.com/puppet/2.7/reference/lang_collectors.html
+8   8   0
1090