Ресурс dsc_script

Изменить эту страницу в репозитории Chef

Все страницы ресурсов Infra

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 Client предпримет для приведения узла в желаемое состояние.
• code, command, configuration_data, configuration_data_script, configuration_name, cwd, environment, flags, imports, и timeout — это свойства данного ресурса с указанным типом Ruby. См. раздел «Свойства» ниже для получения дополнительной информации обо всех свойствах, которые могут использоваться с этим ресурсом.

Действия

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

:nothing

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

:run

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

Свойства

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

code

Тип Ruby: Строка

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

command

Тип Ruby: Строка

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

configuration_data

Тип Ruby: Строка

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

configuration_data_script

Тип Ruby: Строка

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

configuration_name

Тип Ruby: Строка

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

cwd

Тип Ruby: Строка

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

environment

Тип Ruby: Хэш

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

flags

Тип Ruby: Хэш

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

imports

Тип Ruby: Массив

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

Это свойство ОБЯЗАТЕЛЬНО должно использоваться с атрибутом 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: Целое число

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

Справка 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 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 действия и :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