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

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

Страница справочника ресурсов

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

Синтаксис

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

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

где:

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

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

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. Подробную информацию обо всех свойствах этого ресурса см. в разделе «Свойства» ниже.

Действия

Ресурс directory имеет следующие действия:

:create

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

:delete

Удалить каталог.

:nothing

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

Свойства

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

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'; для тех же прав плюс бит сохранения используйте 01777 или '1777'.

Microsoft Windows: Цитированная строка из 3-5 символов, определяющая восьмеричный режим, который преобразуется в права для безопасности Microsoft Windows. Например: '755', '0755', или 00755. Разрешены значения до '0777' (без битов сохранения), и они означают то же самое в 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

Рекурсивно создать родительские каталоги и удалить каталоги, подкаталоги и файлы рекурсивно. Свойства owner, group, и mode применяются только к листу каталога.

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.

Эти разрешения являются кумулятивными. Если указано :write, то это включает в себя :read. Если указано :full_control, то это включает в себя как :write, так и :read.

(Для тех, кто знаком с API Microsoft Windows: :read соответствует GENERIC_READ; :write соответствует GENERIC_WRITE; :read_execute соответствует GENERIC_READ и GENERIC_EXECUTE; :modify соответствует GENERIC_WRITE, GENERIC_READ, GENERIC_EXECUTE, и DELETE; :full_control соответствует GENERIC_ALL, что позволяет пользователю изменять владельца и другую метаданные файла.)

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 InfraClient.

Уведомления

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 действие, и :timer для этого действия.

Обратите внимание, что 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

Управление файлами dot

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

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

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

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