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

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

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

Допустим, классу необходим unix-пользователь, в данном примере webUser, домашний каталог которого будет являться document root'ом для веба. Тогда получим следующий скелет site.pp:

class apache {
	user { 'webUser' : ensure => present }
	...
}
node default {
	include apache
}

Все просто. Теперь мы решили добавить в нашу инфраструктуру nginx неважно для каких целей. Главное, что ему тоже нужен пользователь webUser для отдачи контента. Добавляем класс:

class apache {
  user { 'webUser' : ensure => present }
}

class nginx {
   user { 'webUser' : ensure => present }
}
node default {
  include apache
  include nginx
}

Запускаем:

root@puppet:/vagrant# puppet apply ./site.pp --noop
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
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. Решить проблему можно, например, вынеся ресурс пользователя в отдельный класс:

class users {
  user { 'webUser' : ensure => present }
}

class nginx  { include users }
class apache { include users }

node default {
  include apache
  include nginx
}

Запускаем — работает:

root@puppet:/vagrant# puppet apply ./site.pp --noop
Notice: Compiled catalog for puppet.example.com in environment production in 0.07 seconds
Notice: /Stage[main]/users/User[webUser]/ensure: current_value absent, should be present (noop)
Notice: Class[users]: Would have triggered 'refresh' from 1 events
Notice: Stage[main]: Would have triggered 'refresh' from 1 events
Notice: Finished catalog run in 0.02 seconds

Предположим, что нам понадобилось добавить нового пользователя cacheUser, в папке которого мы будем хранить какой-либо кэш. Этим кэшем пользуется как Apache, так и nginx, поэтому мы добавляем соответствующего пользователя в класс users:

class users {
  user { 'webUser':   ensure => present }
  user { 'cacheUser': ensure => present }
}

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

Если к определению ресурса добавить знак @:

 @user { 'webUser': ensure => present }

Ресурс будет считаться виртуальным. Такой ресурс не будет добавляться в каталог агента до тех пор, пока мы явно не определим. Из документации:
A virtual resource declaration specifies a desired state for a resource without adding it to the catalog

Поэтому если исполнить код ниже даже при отсутствии в системе пользователей webUser и cacheUser они добавлены не будут:

class users {
  @user { 'webUser': ensure   => present }
  @user { 'cacheUser': ensure => present }
}
class nginx { include users }
class apache { include users }

node default {
  include apache
  include nginx
}

Проверяем:

root@puppet:/vagrant# puppet apply ./site.pp
Notice: Compiled catalog for puppet.example.com in environment production in 0.07 seconds
Notice: Finished catalog run in 0.02 seconds

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

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

class apache {
	@user { 'webUser' : ensure => present }
}

class nginx { 
	@user { 'webUser' : ensure => present }
}

node default {
	include apache
	include nginx
}

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

Для определения ресурса используется либо spaceship оператор < | | > либо с помощью функция realize. Перепишем наш манифест с использованием как одного так и другого синтаксиса:

class users {
  @user { 'webUser': ensure   => present }
  @user { 'cacheUser': ensure => present }

}
class nginx {
  include users
  realize User['webUser'], User['cacheUser']
}
class apache {
  include users
  User <| title == 'webUser' or title == 'cacheUser' |>
}

node default {
  include apache
  include nginx
}

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

Помимо синтаксической разница в realize и <| |> имеются отличия и в поведение. Если ресурс с указанным названием не существует realize выдаст ошибку:

Error: Failed to realize virtual resources User[nonExistingUser] on node puppet.example.com

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

Кстати, у оператора <| |> есть еще два достаточно хороших применения. Его можно использовать для переопределения состояния ресурса в классе. Например:

class configurations 
{
  file { '/etc/nginx.conf'   : ensure => present } 
  file { '/etc/apache2.conf' : ensure => present }
}
node s1.example.com { 
  include configurations 
}
node s2.example.com { 
  include configurations 
  File <| title == '/etc/apache2.conf' |> { ensure => absent }
}

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


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

Классический пример из документации Puppet:

class ssh {
	  # Declare:
	  @@sshkey { $hostname:
		type => dsa,
		key  => $sshdsakey,
	  }
	  # Collect:
	  Sshkey <<| |>>
}

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

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

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

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

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

Лучше использовать существующие модули, но для демонстрации принципа данный пример подойдет:
#Класс описывающий бэкенд и экспортирующий в базу строку вида "server IP:PORT;"  которая будет затем добавлен в блок upstream в nginx
class nginx::backend($ip = $::ipaddress, $port = 8080) {
  @@concat::fragment { "$::fqdn" :
    content => "server $ip:$port;",
    tag => 'nginx-backend',
    target => '/etc/nginx/conf.d/backend.conf'
  }
}
#Класс описывающий фронтенд, в котором объявлется ресурс concat, который далее склеивает все фрагменты экспортированные в nginx::backend
class nginx::frontend {
  concat { '/etc/nginx/backend.conf' :
    ensure            => present,
    force             => true,
    ensure_newline    => true
  } ~> Class['::nginx::service']

  concat::fragment { 'upstream_header':
    content  => 'upstream backend { ',
    order    => '01',
    target   => '/etc/nginx/backend.conf',
   }

  concat::fragment { 'upstream_footer' :
    content  => '}',
    order    => '03',
    target  => '/etc/nginx/backend.conf'
  }
  #Импортируем все фрагменты
  Concat::Fragment <<| tag == 'nginx-backend' |>>  { target => '/etc/nginx/backend.conf', order => '02' }
}

class nginx::install {
  package { 'nginx' : ensure => present }
}

class nginx::service {
  service { 'nginx' : ensure => running, require => Class['nginx::install'] }
}

class nginx {
  class { 'nginx::install' : } -> class { 'nginx::service': }
}

node 'back1.example.com' {
  class { 'nginx' : }
  class { 'nginx::backend' : port => 8083 }
}

node 'back2.example.com' {
  class { 'nginx' : }
  class { 'nginx::backend' : port => 8084 }
}

node 'front1.example.com' {
  class { 'nginx' : }
  class { 'nginx:::frontend' : }
}


Более подробную информацию о синтаксисе и паттернах использования можно найти по следующим ссылкам: