Ресурс каталога

Редактировать эту страницу в репозитории Chef

Страница всех ресурсов Infra

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

Синтаксис

Блок ресурса каталога объявляет каталог и необходимые разрешения на этом каталоге. Например:

directory '/etc/apache2' do
  owner 'root'
  group 'root'
  mode '0755'
  action :create
end

где:

• '/etc/apache2' определяет каталог
• owner, group, и mode определяют разрешения

Полный синтаксис всех свойств, доступных для ресурса каталога:

directory 'name' do
  group                      String, Integer
  inherits                   true, false
  mode                       String, Integer
  owner                      String, Integer
  path                       String # defaults to 'name' if not specified
  recursive                  true, false
  rights                     Hash
  action                     Symbol # defaults to :create if not specified
end

где:

• directory является ресурсом.
• name — имя блока ресурса; когда свойство path не указано, name также является путем к каталогу от корня
• action определяет шаги, которые Chef Infra Client предпримет для приведения узла в желаемое состояние
• group, inherits, mode, owner, path, recursive, и rights — это свойства этого ресурса с указанным типом Ruby. Подробнее о всех свойствах, которые могут быть использованы с этим ресурсом, см. раздел «Свойства» ниже.

Действия

Ресурс каталога имеет следующие действия:

:create

По умолчанию. Создает каталог. Если каталог уже существует (но не совпадает), обновите этот каталог, чтобы он соответствовал.

:delete

Удаляет каталог.

:nothing

Этот блок ресурса не действует, пока не получит уведомление от другого ресурса о выполнении действия. После уведомления этот блок ресурса либо выполняется немедленно, либо помещается в очередь для выполнения в конце выполнения Chef Infra Client.

Свойства

Ресурс каталога имеет следующие свойства:

group

Тип Ruby: Целое число, строка

Строка или идентификатор, определяющий владельца группы по имени группы или SID, включая полные имена групп, такие как domain\group или group@domain. Если это значение не указано, существующие группы остаются неизменными, а новые назначения групп используют стандартную группу POSIX (если доступна).

inherits

Тип Ruby: true, false | Значение по умолчанию: true

Только Microsoft Windows. Наследует ли файл права из родительского каталога.

mode

Тип Ruby: Целое число, строка

Приведенная строка из 3–5 символов, определяющая восьмеричный режим. Например: '755', '0755', или 00755. Если mode не указано, и если каталог уже существует, используется существующий режим каталога. Если mode не указано, каталог не существует, и указано действие :create, Chef Infra Client предполагает значение маски '0777', а затем применяет маску umask для системы, на которой должен быть создан каталог, к значению mask. Например, если umask в системе — '022', Chef Infra Client использует значение по умолчанию '0755'.

Поведение зависит от платформы.

Системы на основе UNIX и Linux: Приведенная строка из 3–5 символов, определяющая восьмеричный режим, передаваемый в chmod. Например: '755', '0755', или 00755. Если значение указано как строка, оно работает так же, как если бы команда chmod была передана. Если значение указано как целое число, добавьте ноль (0) к значению, чтобы оно интерпретировалось как восьмеричное число. Например, чтобы назначить права чтения, записи и выполнения для всех пользователей, используйте '0777' или '777'; для тех же прав плюс бит «sticky» используйте 01777 или '1777'.

Microsoft Windows: Приведенная строка из 3–5 символов, определяющая восьмеричный режим, который преобразуется в права безопасности Microsoft Windows. Например: '755', '0755', или 00755. Разрешены значения до '0777' (без битов «sticky») и имеют то же значение в Microsoft Windows, что и в UNIX, где 4 равно GENERIC_READ, 2 равно GENERIC_WRITE, и 1 равно GENERIC_EXECUTE. Это свойство не может быть использовано для установки :full_control. Это свойство не имеет эффекта, если не указано, но когда оно и rights указаны оба, эффекты суммируются.

owner

Тип Ruby: Целое число, строка

Строка или идентификатор, определяющий владельца группы по имени пользователя или SID, включая полные имена пользователей, такие как domain\user или user@domain. Если это значение не указано, существующие владельцы остаются неизменными, а новые назначения владельцев используют текущего пользователя (при необходимости).

path

Тип Ruby: Строка | Значение по умолчанию: The resource block's name

Путь к каталогу. Рекомендуется использовать полный путь, но это не всегда необходимо. Значение по умолчанию: name блока ресурса. Подробности см. в разделе «Синтаксис» выше.

recursive

Тип Ruby: true, false | Значение по умолчанию: false

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

rights

Тип Ruby: Целое число, строка

Только Microsoft Windows. Разрешения для пользователей и групп в среде Microsoft Windows. Например: rights <permissions>, <principal>, <options> где <permissions> задаёт права, предоставляемые субъекту, <principal> — имя группы или пользователя, а <options> — словарь с одним (или более) расширенными параметрами прав.

Рекурсивные каталоги

Ресурс remote_directory может использоваться для рекурсивного создания пути за пределами структуры удалённых каталогов, но права этих внешних путей не управляются. Это связано с тем, что атрибут recursive применяет значения атрибутов group, mode, и owner только к самому удалённому каталогу и любым внутренним каталогам, которые копируются ресурсом.

Структура каталогов:

/foo
  /bar
    /baz

Следующий пример демонстрирует способ создания файла в каталоге /baz:

remote_directory '/foo/bar/baz' do
  owner 'root'
  group 'root'
  mode '0755'
  action :create
end

Но в этом примере значения атрибутов group, mode, и owner будут применены только к /baz. Что нормально, если это именно то, что вам нужно. Но в большинстве случаев, когда вся структура каталогов /foo/bar/baz отсутствует, необходимо быть явным в отношении каждого каталога. Например:

%w( /foo /foo/bar /foo/bar/baz ).each do |path|
  remote_directory path do
    owner 'root'
    group 'root'
    mode '0755'
  end
end

Этот подход создаст правильную иерархию—/foo, затем /bar в /foo, а затем /baz в /bar—и также с правильными значениями атрибутов group, mode, и owner.

Безопасность файлов Windows

Свойство rights может использоваться в рецепте для управления списками управления доступом (ACL), которые позволяют предоставлять разрешения нескольким пользователям и группам. Свойство rights можно использовать столько раз, сколько необходимо; Chef Infra Client применит их к файлу или каталогу по мере необходимости. Синтаксис свойства rights следующий:

rights permission, principal, option_type => value

где

permission

Используется для указания прав, предоставляемых principal. Возможные значения: :read, :write, read_execute, :modify, :full_control, или целое число.

Целые числа, используемые для прав, должны соответствовать следующему списку FileSystemRights Enum полей.

These permissions are cumulative. If `:write` is specified, then it
includes `:read`. If `:full_control` is specified, then it includes
both `:write` and `:read`.

(For those who know the Microsoft Windows API: `:read` corresponds
to `GENERIC_READ`; `:write` corresponds to `GENERIC_WRITE`;
`:read_execute` corresponds to `GENERIC_READ` and `GENERIC_EXECUTE`;
`:modify` corresponds to `GENERIC_WRITE`, `GENERIC_READ`,
`GENERIC_EXECUTE`, and `DELETE`; `:full_control` corresponds to
`GENERIC_ALL`, which allows a user to change the owner and other
metadata about a file.)

principal

Используется для указания группы или пользователя. Принципал может быть указан по имени или SID. При использовании имени, это идентично тому, что вводится в поле входа для Microsoft Windows, например, user_name, domain\user_name, или user_name@fully_qualified_domain_name. При использовании SID, вы можете использовать либо стандартное строковое представление SID (S-R-I-S-S), либо одну из констант строк SDDL. Chef Infra Client не нужно знать, является ли принципал пользователем или группой.

option_type

Хэш, содержащий расширенные параметры прав. Например, права на каталог, которые применяются только к первому уровню потомков, могут выглядеть примерно так: rights :write, 'domain\group_name', :one_level_deep => true. Возможные типы опций:

Тип опции	Описание
:applies_to_children	Указывает, как права применяются к потомкам. Возможные значения: true для наследования как подкаталогов, так и файлов; false для ненаследия подкаталогов и файлов; :containers_only для наследования только подкаталогов (а не файлов); :objects_only для рекурсивного наследования файлов (а не подкаталогов).
:applies_to_self	Указывает, применяется ли разрешение к родительскому каталогу. Возможные значения: true для применения к родительскому каталогу или файлу и его потомкам; false для применения только к подкаталогам и файлам.
:one_level_deep	Указывает глубину применения прав. Возможные значения: true для применения только к первому уровню потомков; false для применения ко всем потомкам.

Например:

resource 'x.txt' do
  rights :read, 'S-1-1-0'
  rights :write, 'domain\group'
  rights :full_control, 'group_name_or_user_name'
  rights :full_control, 'user_name', applies_to_children: true
end

или:

rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true

Некоторые другие важные моменты при использовании атрибута rights:

• Остаются только унаследованные права. Все существующие явные права на объект удаляются и заменяются.
• Если права не указаны, ничего не изменится. Chef Infra Client не очищает права на файл или каталог, если права не указаны.
• Изменение унаследованных прав может быть затратным. Microsoft Windows будет рекурсивно распространять права на всех потомков из-за наследования. Это нормальная особенность Microsoft Windows, поэтому подумайте о частоте необходимости такого действия и примите меры для управления таким действием, если производительность является основным соображением.

Используйте свойство deny_rights для запрещения определенных прав определённым пользователям. Порядок не зависит от использования свойства rights. Например, неважно, помещаются ли права для всех перед или после deny_rights :read, ['Julian', 'Lewis'], и Джулиан, и Льюис не смогут прочитать документ. Например:

resource 'x.txt' do
  rights :read, 'Everyone'
  rights :write, 'domain\group'
  rights :full_control, 'group_name_or_user_name'
  rights :full_control, 'user_name', applies_to_children: true
  deny_rights :read, %w(Julian Lewis)
end

или:

deny_rights :full_control, ['Sally']

По умолчанию файл или каталог наследует права из родительского каталога. В большинстве случаев это предпочтительное поведение, но иногда может потребоваться принять меры для более точного управления правами. Свойство inherits можно использовать для того, чтобы явным образом указать Chef Infra Client на применение (или неприменение) унаследованных прав из родительского каталога.

Например, следующий пример указывает права для каталога:

directory 'C:\mordor' do
  rights :read, 'MORDOR\Minions'
  rights :full_control, 'MORDOR\Sauron'
end

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

directory 'C:\mordor\mount_doom' do
  rights :full_control, 'MORDOR\Sauron'
  inherits false # Sauron is the only person who should have any sort of access
end

Если вместо этого использовалось бы разрешение deny_rights, что-то могло бы проскользнуть, если бы все пользователи и группы не были запрещены.

Еще один пример также демонстрирует, как указать права для каталога:

directory 'C:\mordor' do
  rights :read, 'MORDOR\Minions'
  rights :full_control, 'MORDOR\Sauron'
  rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end

но затем не использовать свойство inherits для запрета этих прав в подкаталоге:

directory 'C:\mordor\mount_doom' do
  deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end

Поскольку свойство inherits не указано, Chef Infra Client установит его по умолчанию как true, что гарантирует, что настройки безопасности существующих файлов останутся неизменными.

Общие возможности ресурсов

Ресурсы Chef включают общие свойства, уведомления и защитные механизмы ресурсов.

Общие свойства

Следующие свойства являются общими для всех ресурсов:

compile_time

Тип Ruby: true, false | Значение по умолчанию: false

Управление фазой, в которой ресурс выполняется на узле. Установите в значение true, чтобы запустить во время построения коллекции ресурсов (в compile phase). Установите в значение false, чтобы запустить во время конфигурирования узла Chef Infra Client (в converge phase).

ignore_failure

Тип Ruby: true, false, :quiet | Значение по умолчанию: false

Продолжить выполнение рецепта, если ресурс завершился ошибкой по любой причине. :quiet не отобразит полный стек исключений, и рецепт продолжит выполнение в случае ошибки ресурса.

retries

Тип Ruby: Целое число | Значение по умолчанию: 0

Количество попыток перехватить исключения и повторить ресурс.

retry_delay

Тип Ruby: Целое число | Значение по умолчанию: 2

Задержка в секундах между попытками повтора.

sensitive

Тип Ruby: true, false | Значение по умолчанию: false

Обеспечить, чтобы конфиденциальные данные ресурсов не регистрировались Chef Infra Client.

Уведомления

notifies

Тип Ruby: Символ, 'Chef::Resource[String]'

Ресурс может уведомить другой ресурс о выполнении действия при изменении его состояния. Укажите 'resource[name]', действие, которое должен выполнить :action, а затем :timer для этого действия. Один ресурс может уведомить несколько ресурсов; используйте notifies оператор для каждого уведомляемого ресурса.

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

Таймер указывает момент запуска уведомления во время выполнения Chef Infra Client. Доступны следующие таймеры:

:before

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

:delayed

По умолчанию. Указывает, что уведомление должно быть помещено в очередь и выполнено в конце выполнения Chef Infra Client.

:immediate, :immediately

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

Синтаксис для notifies:

notifies :action, 'resource[name]', :timer

subscribes

Тип Ruby: Символ, 'Chef::Resource[String]'

Ресурс может прослушивать другой ресурс и выполнять действие, если состояние прослушиваемого ресурса изменится. Укажите 'resource[name]', действие, которое должно быть выполнено, а затем :action для этого действия.

Обратите внимание, что subscribes не применяет указанное действие к ресурсу, который он прослушивает - например:

file '/etc/nginx/ssl/example.crt' do
  mode '0600'
  owner 'root'
end

service 'nginx' do
  subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end

В этом случае свойство subscribes перезагружает службу nginx всякий раз, когда файл сертификата, расположенный в /etc/nginx/ssl/example.crt, обновляется. subscribes не вносит никаких изменений в сам файл сертификата, а просто прослушивает изменения файла и выполняет действие :reload для своего ресурса (в этом примере nginx) при обнаружении изменений.

Если другой ресурс не существует, подписка не вызовет ошибки. Противопоставьте это более строгим правилам notifies, которые вызовут ошибку, если другой ресурс не существует.

Таймер указывает момент запуска уведомления во время выполнения Chef Infra Client. Доступны следующие таймеры:

:before

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

:delayed

По умолчанию. Указывает, что уведомление должно быть помещено в очередь и выполнено в конце выполнения Chef Infra Client.

:immediate, :immediately

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

Синтаксис для subscribes:

subscribes :action, 'resource[name]', :timer

Защитные механизмы

Свойство защитного механизма может использоваться для оценки состояния узла во время фазы выполнения Chef Infra Client. В зависимости от результатов этой оценки, свойство защитного механизма используется, чтобы указать Chef Infra Client, следует ли ему продолжить выполнение ресурса. Свойство защитного механизма принимает либо строковое значение, либо значение блока Ruby:

• Строка выполняется как команда оболочки. Если команда возвращает 0, защитный механизм применяется. Если команда возвращает любое другое значение, то свойство защитного механизма не применяется. Строковые защитные механизмы в powershell_script выполняют команды Windows PowerShell и могут возвращать true в дополнение к 0.
• Блок выполняется как код Ruby, который должен вернуть либо true, либо false. Если блок возвращает true, свойство защитного механизма применяется. Если блок возвращает false, свойство защитного механизма не применяется.

Свойство защитного механизма полезно для обеспечения идемпотентности ресурса, позволяя этому ресурсу проверять желаемое состояние по мере выполнения, а затем, если желаемое состояние присутствует, Chef Infra Client ничего не делает.

Следующие свойства могут использоваться для определения защитного механизма, который оценивается во время фазы выполнения Chef Infra Client:

not_if

Предотвратить выполнение ресурса, когда условие возвращает true.

only_if

Разрешить выполнение ресурса только в том случае, если условие возвращает true.

Примеры

Следующие примеры демонстрируют различные подходы к использованию ресурса directory в рецептах:

Создание каталога

directory '/tmp/something' do
  owner 'root'
  group 'root'
  mode '0755'
  action :create
end

Создание каталога в Microsoft Windows

directory "C:\\tmp\\something" do
  rights :full_control, "DOMAIN\\User"
  inherits false
  action :create
end

или:

directory 'C:\tmp\something' do
  rights :full_control, 'DOMAIN\User'
  inherits false
  action :create
end

Рекурсивное создание каталога

%w{dir1 dir2 dir3}.each do |dir|
  directory "/tmp/mydirs/#{dir}" do
    mode '0755'
    owner 'root'
    group 'root'
    action :create
    recursive true
  end
end

Удаление каталога

directory '/tmp/something' do
  recursive true
  action :delete
end

Установка разрешений каталога с использованием переменной

Следующий пример демонстрирует, как можно установить разрешения на чтение/запись/исполнение с использованием переменной с именем user_home, а затем для владельцев и групп на любом соответствующем узле:

user_home = "/#{node[:matching_node][:user]}"

directory user_home do
  owner 'node[:matching_node][:user]'
  group 'node[:matching_node][:group]'
  mode '0755'
  action :create
end

где matching_node представляет тип узла. Например, если переменная user_home задаёт значение {node[:nginx]...}, рецепт может выглядеть следующим образом:

user_home = "/#{node[:nginx][:user]}"

directory user_home do
  owner 'node[:nginx][:user]'
  group 'node[:nginx][:group]'
  mode '0755'
  action :create
end

Установка разрешений каталога для определенного типа узла

Следующий пример показывает, как можно установить разрешения для каталога /certificates на любом узле, на котором работает Nginx. В этом примере разрешения устанавливаются для свойств owner и group как root, а затем разрешения на чтение и запись предоставляются пользователю root.

directory "#{node[:nginx][:dir]}/shared/certificates" do
  owner 'root'
  group 'root'
  mode '0755'
  recursive true
end

Перезагрузка конфигурации

Следующий пример показывает, как перезагрузить конфигурацию chef-клиента с использованием ресурса remote_file для:

• использования оператора if для проверки, являются ли плагины на узле последними версиями
• определения расположения, в котором хранятся плагины Ohai
• использования свойства notifies и ресурса ruby_block для запуска обновления (при необходимости) и перезагрузки файла client.rb.

directory 'node[:ohai][:plugin_path]' do
  owner 'chef'
  recursive true
end

ruby_block 'reload_config' do
  block do
    Chef::Config.from_file('/etc/chef/client.rb')
  end
  action :nothing
end

if node[:ohai].key?(:plugins)
  node[:ohai][:plugins].each do |plugin|
    remote_file node[:ohai][:plugin_path] +"/#{plugin}" do
      source plugin
      owner 'chef'
      notifies :run, 'ruby_block[reload_config]', :immediately
    end
  end
end

Управление файлами с префиксом точки

Следующий пример показывает использование ресурсов directory и cookbook_file для управления файлами с префиксом точки. Файлы с префиксом точки определяются структурой данных JSON, подобной:

"files": {
  ".zshrc": {
    "mode": '0755',
    "source": "dot-zshrc"
    },
  ".bashrc": {
    "mode": '0755',
    "source": "dot-bashrc"
     },
  ".bash_profile": {
    "mode": '0755',
    "source": "dot-bash_profile"
    },
  }

а затем следующие ресурсы управляют файлами с префиксом точки:

if u.has_key?('files')
  u['files'].each do |filename, file_data|

  directory "#{home_dir}/#{File.dirname(filename)}" do
    recursive true
    mode '0755'
  end if file_data['subdir']

  cookbook_file "#{home_dir}/#{filename}" do
    source "#{u['id']}/#{file_data['source']}"
    owner 'u['id']'
    group 'group_id'
    mode 'file_data['mode']'
    ignore_failure true
    backup 0
  end
end