Ресурс dsc_script

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

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

Windows PowerShell — это командная оболочка и язык сценариев, ориентированные на задачи, разработанные компанией Microsoft. Windows PowerShell использует документоориентированный подход к управлению машинами под управлением Microsoft Windows, аналогичный подходу, используемому для управления машинами под управлением Unix и Linux. Windows PowerShell — это платформа, не зависящая от инструментов, которая поддерживает использование Chef для управления конфигурациями.

Desired State Configuration (DSC) — это функция Windows PowerShell, которая предоставляет набор расширений языка, командлетов и ресурсов, которые можно использовать для декларативного конфигурирования программного обеспечения. DSC похож на Chef, поскольку оба инструмента являются идемпотентными, используют похожие подходы к концепции ресурсов, описывают конфигурацию системы, а затем выполняют шаги, необходимые для выполнения этой конфигурации. Наиболее важное различие между Chef и DSC заключается в том, что Chef использует Ruby, а DSC предоставляется в виде данных конфигурации изнутри Windows PowerShell.

Многие ресурсы DSC сопоставимы со встроенными ресурсами Chef Infra. Например, как DSC, так и Chef имеют ресурсы file, package и service. Ресурс dsc_script наиболее полезен для тех ресурсов DSC, которые не имеют прямого сравнения с ресурсом в Chef, таких как ресурс Archive, пользовательский ресурс DSC, существующий сценарий DSC, выполняющий важную задачу, и так далее. Используйте ресурс dsc_script для внедрения кода, определяющего конфигурацию DSC, непосредственно в рецепт Chef Infra.

Синтаксис

Блок ресурсов dsc_script внедряет код, определяющий конфигурацию DSC, непосредственно в рецепт Chef:

dsc_script 'get-dsc-resource-kit' do
  code <<-EOH
    Archive reskit
    {
      ensure = 'Present'
      path = "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip"
      destination = "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules"
    }
  EOH
end

где:

• ресурс remote_file сначала используется для загрузки файла DSCResourceKit620082014.zip.

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

dsc_script 'name' do
  code                       String
  command                    String
  configuration_data         String
  configuration_data_script  String
  configuration_name         String
  cwd                        String
  environment                Hash
  flags                      Hash
  imports                    Array
  timeout                    Integer
  action                     Symbol # defaults to :run if not specified
end

где:

• dsc_script — это ресурс.
• name — это имя, присвоенное блоку ресурсов.
• action определяет, какие шаги предпримет клиент Chef Infra для приведения узла в желаемое состояние.
• code, command, configuration_data, configuration_data_script, configuration_name, cwd, environment, flags, imports и timeout — это свойства этого ресурса, с указанным типом Ruby. См. раздел «Свойства» ниже для получения дополнительной информации о всех свойствах, которые могут использоваться с этим ресурсом.

Действия

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

:nothing

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

:run

Значение по умолчанию. Используется для запуска конфигурации DSC, определенной в этом ресурсе.

Свойства

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

code

Тип Ruby: String

Код для скрипта конфигурации DSC. Это свойство не может использоваться совместно со свойством command.

command

Тип Ruby: String

Путь к допустимому файлу данных Windows PowerShell, содержащему скрипт конфигурации DSC. Этот файл данных должен быть способен запускаться независимо от Chef и должен генерировать допустимую конфигурацию DSC. Это свойство не может использоваться совместно со свойством code.

configuration_data

Тип Ruby: String

Данные конфигурации для скрипта DSC. Данные конфигурации должны быть допустимым файлом данных Windows PowerShell. Это свойство не может использоваться совместно со свойством configuration_data_script.

configuration_data_script

Тип Ruby: String

Путь к допустимому файлу данных Windows PowerShell, который также содержит узел с именем localhost. Это свойство не может использоваться совместно со свойством configuration_data.

configuration_name

Тип Ruby: String

Имя допустимого командлета Windows PowerShell. Имя может содержать только буквы (a-z, A-Z), цифры (0-9) и символ подчеркивания (_), и должно начинаться с буквы. Имя не может быть пустым или null. Это свойство не может использоваться совместно со свойством code.

cwd

Тип Ruby: String

Текущий рабочий каталог.

environment

Тип Ruby: Hash

Хэш переменных среды в формате ({'ENV_VARIABLE' => 'VALUE'}). (Эти переменные должны существовать для успешного выполнения команды.)

flags

Тип Ruby: Hash

Передача параметров в скрипт DSC, указанный свойством command. Параметры определяются как пары «ключ-значение», где значение каждого ключа — это передаваемый параметр. Это свойство не может использоваться в одном рецепте со свойством code. Например: flags ({ :EditorChoice => 'emacs', :EditorFlags => '--maximized' }).

imports

Тип Ruby: Array

Предупреждение

Это свойство ОБЯЗАТЕЛЬНО использовать с атрибутом code.

Используется для импорта ресурсов DSC из модуля.

Для импорта всех ресурсов из модуля укажите только имя модуля:

imports 'module_name'

Для импорта определенных ресурсов укажите имя модуля, а затем укажите имя каждого ресурса в этом модуле для импорта:

imports 'module_name', 'resource_name_a', 'resource_name_b', ...

Например, для импорта всех ресурсов из модуля с именем cRDPEnabled:

imports 'cRDPEnabled'

Для импорта только ресурса PSHOrg_cRDPEnabled:

imports 'cRDPEnabled', 'PSHOrg_cRDPEnabled'

timeout

Тип Ruby: Integer

Время ожидания (в секундах) до истечения времени ожидания команды.

Вспомогательный элемент ps_credential

Используйте вспомогательный элемент ps_credential для внедрения объекта PSCredential — набора учетных данных безопасности, таких как имя пользователя или пароль — в скрипт, что позволяет запускать этот скрипт с использованием учетных данных безопасности.

Например, предполагая, что CertificateID настроен в локальном диспетчере конфигураций, создается объект SeaPower1@3 и внедряется в скрипт seapower-user:

dsc_script 'seapower-user' do
  code <<-EOH
    User AlbertAtom
    {
      UserName = 'AlbertAtom'
      Password = #{ps_credential('SeaPower1@3')}
    }
  EOH
  configuration_data <<-EOH
    @{
      AllNodes = @(
        @{
          NodeName = "localhost";
          CertificateID = 'A8D1234559F349F7EF19104678908F701D4167'
        }
      )
    }
  EOH
end

Общие функции ресурса

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

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

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

compile_time

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

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

ignore_failure

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

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

retries

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

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

retry_delay

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

Задержка повтора (в секундах).

sensitive

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

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

Уведомления

notifies

Тип Ruby: Symbol, '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.

Примеры

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

Прямое указание кода DSC

Данные DSC могут быть указаны непосредственно в рецепте:

dsc_script 'emacs' do
  code <<-EOH
  Environment 'texteditor'
  {
    Name = 'EDITOR'
    Value = 'c:\\emacs\\bin\\emacs.exe'
  }
  EOH
end

Указание кода DSC с помощью файла данных Windows PowerShell

Используйте свойство command для указания пути к файлу данных Windows PowerShell. Например, следующий сценарий Windows PowerShell определяет DefaultEditor:

Configuration 'DefaultEditor'
{
  Environment 'texteditor'
    {
      Name = 'EDITOR'
      Value = 'c:\emacs\bin\emacs.exe'
    }
}

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

dsc_script 'DefaultEditor' do
  command 'c:\dsc_scripts\emacs.ps1'
end

Передача параметров в конфигурации DSC

Если сценарий DSC содержит конфигурационные данные, принимающие параметры, эти параметры могут быть переданы с помощью свойства flags. Например, следующий сценарий Windows PowerShell принимает параметры для EditorChoice и EditorFlags настроек:

$choices = @{'emacs' = 'c:\emacs\bin\emacs';'vi' = 'c:\vim\vim.exe';'powershell' = 'powershell_ise.exe'}
  Configuration 'DefaultEditor'
    {
      [CmdletBinding()]
      param
        (
          $EditorChoice,
          $EditorFlags = ''
        )
      Environment 'TextEditor'
      {
        Name = 'EDITOR'
        Value =  "$($choices[$EditorChoice]) $EditorFlags"
      }
    }

Используйте следующий рецепт для задания этих параметров:

dsc_script 'DefaultEditor' do
  flags ({ :EditorChoice => 'emacs', :EditorFlags => '--maximized' })
  command 'c:\dsc_scripts\editors.ps1'
end

Использование пользовательских конфигурационных данных

Конфигурационные данные в сценариях DSC могут быть настраиваемы из рецепта. Например, сценарии обычно настраиваются для установки поведения для типов данных учетных данных Windows PowerShell. Конфигурационные данные могут быть указаны тремя способами:

• Использование атрибута configuration_data
• Использование атрибута configuration_data_script
• Указание пути к валидному файлу данных Windows PowerShell

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

dsc_script 'BackupUser' do
  configuration_data <<-EOH
    @{
     AllNodes = @(
          @{
          NodeName = "localhost";
          PSDscAllowPlainTextPassword = $true
          })
     }
  EOH
  code <<-EOH
    $user = 'backup'
    $password = ConvertTo-SecureString -String "YourPass$(random)" -AsPlainText -Force
    $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $user, $password

   User $user
     {
       UserName = $user
       Password = $cred
       Description = 'Backup operator'
       Ensure = "Present"
       Disabled = $false
       PasswordNeverExpires = $true
       PasswordChangeRequired = $false
     }
   EOH
end

Следующий пример показывает, как указать пользовательские конфигурационные данные с помощью свойства configuration_name. Например, следующий сценарий Windows PowerShell определяет конфигурацию vi:

Configuration 'emacs'
  {
    Environment 'TextEditor'
    {
      Name = 'EDITOR'
      Value = 'c:\emacs\bin\emacs.exe'
    }
}

Configuration 'vi'
{
    Environment 'TextEditor'
    {
      Name = 'EDITOR'
      Value = 'c:\vim\bin\vim.exe'
    }
}

Используйте следующий рецепт для указания этой конфигурации:

dsc_script 'EDITOR' do
  configuration_name 'vi'
  command 'C:\dsc_scripts\editors.ps1'
end

Использование DSC с другими ресурсами Chef

Ресурс dsc_script может использоваться с другими ресурсами. Следующий пример показывает, как загрузить файл с помощью ресурса remote_file, а затем распаковать его с помощью ресурса DSC Archive:

remote_file "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip" do
  source 'http://gallery.technet.microsoft.com/DSC-Resource-Kit-All-c449312d/file/124481/1/DSC%20Resource%20Kit%20Wave%206%2008282014.zip'
end

dsc_script 'get-dsc-resource-kit' do
  code <<-EOH
    Archive reskit
    {
      ensure = 'Present'
      path = "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip"
      destination = "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules"
    }
  EOH
end