Конфигурация Желаемого Состояния

• Что такое Конфигурация Желаемого Состояния?
• Требования к хосту
• Зачем использовать DSC?
• Как использовать DSC?
  • Типы свойств
    • PSCredential
    • Тип CimInstance
    • Массивы
  • Запуск от имени другого пользователя
• Пользовательские ресурсы DSC
  • Поиск пользовательских ресурсов DSC
  • Установка пользовательского ресурса
• Примеры
  • Извлечение файла zip
  • Создание директории
  • Взаимодействие с Azure
  • Настройка веб-сайта IIS

Что такое Конфигурация Желаемого Состояния?

Конфигурация Желаемого Состояния, или DSC, — это инструмент, встроенный в PowerShell, который можно использовать для определения конфигурации хоста Windows с помощью кода. Общая цель DSC такая же, как у Ansible, просто она выполняется по-другому. Начиная с Ansible 2.4, был добавлен модуль win_dsc, который можно использовать для использования существующих ресурсов DSC при взаимодействии с хостом Windows.

Дополнительную информацию о DSC можно найти на странице Обзор DSC.

Требования к хосту

Для использования модуля win_dsc, хост Windows должен иметь установленный PowerShell версии 5.0 или выше. Все поддерживаемые хосты, за исключением Windows Server 2008 (без R2), могут быть обновлены до PowerShell v5.

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

Зачем использовать DSC?

DSC и модули Ansible преследуют общую цель — определить и обеспечить состояние ресурса. Благодаря этому, такие ресурсы, как ресурс файла DSC File resource и win_file Ansible, могут быть использованы для достижения одинакового результата. Выбор между ними зависит от конкретной ситуации.

Причины использования модуля Ansible вместо ресурса DSC:

• Хост не поддерживает PowerShell v5.0 или его нельзя легко обновить
• Ресурс DSC не предлагает функцию, присутствующую в модуле Ansible. Например, win_regedit может управлять типом свойства REG_NONE, в то время как ресурс DSC Registry не может
• Ресурсы DSC имеют ограниченную поддержку режима проверки, в то время как некоторые модули Ansible имеют лучшие средства проверки
• Ресурсы DSC не поддерживают режим сравнения, в то время как некоторые модули Ansible поддерживают
• Пользовательские ресурсы требуют дополнительных шагов установки, которые должны быть выполнены на хосте предварительно, в то время как модули Ansible являются встроенными в Ansible
• В ресурсе DSC есть ошибки, которых нет в модуле Ansible

Причины использования ресурса DSC вместо модуля Ansible:

• Модуль Ansible не поддерживает функцию, присутствующую в ресурсе DSC
• Нет доступного модуля Ansible
• В существующем модуле Ansible есть ошибки

В конечном итоге, не важно, выполняется ли задача с помощью DSC или модуля Ansible; важно, чтобы задача выполнялась правильно, а плейбуки оставались читабельными. Если у вас больше опыта работы с DSC по сравнению с Ansible и оно справляется с задачей, используйте DSC.

Как использовать DSC?

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

В качестве примера использования ресурса Registry, вот определение DSC, как описано Microsoft:

Registry [string] #ResourceName
{
    Key = [string]
    ValueName = [string]
    [ Ensure = [string] { Enable | Disable }  ]
    [ Force =  [bool]   ]
    [ Hex = [bool] ]
    [ DependsOn = [string[]] ]
    [ ValueData = [string[]] ]
    [ ValueType = [string] { Binary | Dword | ExpandString | MultiString | Qword | String }  ]
}

При определении задачи resource_name должно быть установлено на используемый ресурс DSC — в данном случае resource_name должно быть установлено на Registry. module_version может ссылаться на определенную версию установленного ресурса DSC; если поле пустое, оно будет по умолчанию установлено на последнюю версию. Остальные параметры используются для определения ресурса, такие как Key и ValueName. Несмотря на то, что параметры задачи не чувствительны к регистру, рекомендуется сохранять исходный регистр, так как это облегчает различение параметров ресурса DSC от параметров Ansible win_dsc.

Вот как выглядит версия задачи Ansible для вышеуказанного ресурса реестра DSC:

- name: use win_dsc module with the Registry DSC resource
  win_dsc:
    resource_name: Registry
    Ensure: Present
    Key: HKEY_LOCAL_MACHINE\SOFTWARE\ExampleKey
    ValueName: TestValue
    ValueData: TestData

Типы свойств

У каждого свойства ресурса DSC есть соответствующий тип. Ansible попытается преобразовать определенные параметры в правильный тип во время выполнения. Для простых типов, таких как [string] и [bool], это просто, но для сложных типов, таких как [PSCredential] или массивы (например, [string[]]), требуются определенные правила.

PSCredential

Объект [PSCredential] используется для безопасного хранения учетных данных, но у Ansible нет способа сериализовать его через JSON. Для установки свойства PSCredential DSC, в определении параметра должны быть два значения, оканчивающиеся на _username и _password для имени пользователя и пароля соответственно. Например:

PsDscRunAsCredential_username: '{{ansible_user}}'
PsDscRunAsCredential_password: '{{ansible_password}}'

SourceCredential_username: AdminUser
SourceCredential_password: PasswordForAdminUser

Тип CimInstance

Объект [CimInstance] используется DSC для хранения объекта словаря на основе пользовательского класса, определенного этим ресурсом. Определение значения, которое принимает [CimInstance] в YAML, аналогично определению словаря в YAML. Например, для определения значения [CimInstance] в Ansible:

# [CimInstance]AuthenticationInfo == MSFT_xWebAuthenticationInformation
AuthenticationInfo:
  Anonymous: no
  Basic: yes
  Digest: no
  Windows: yes

В приведенном выше примере экземпляр CIM представляет класс MSFT_xWebAuthenticationInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>``_. This class accepts four boolean variables, ``Anonymous, Basic, Digest, и Windows. Ключи для использования в [CimInstance] зависят от представляемого класса. Пожалуйста, ознакомьтесь с документацией к ресурсу, чтобы узнать, какие ключи можно использовать и какие типы имеют значения каждого ключа. Определение класса обычно находится в <resource name>.schema.mof.

Массивы

Массивы простых типов, такие как [string[]] или [UInt32[]], определяются как список или как строка через запятую, которая затем преобразуется в их тип. Рекомендуется использовать список, поскольку значения не анализируются вручную модулем win_dsc перед передачей в движок DSC. Например, для определения массива простого типа в Ansible:

# [string[]]
ValueData: entry1, entry2, entry3
ValueData:
- entry1
- entry2
- entry3

# [UInt32[]]
ReturnCode: 0,3010
ReturnCode:
- 0
- 3010

Массивы сложных типов, такие как [CimInstance[]] (массив словарей), можно определить так, как показано в этом примере:

# [CimInstance[]]BindingInfo == MSFT_xWebBindingInformation
BindingInfo:
- Protocol: https
  Port: 443
  CertificateStoreName: My
  CertificateThumbprint: C676A89018C4D5902353545343634F35E6B3A659
  HostName: DSCTest
  IPAddress: '*'
  SSLFlags: 1
- Protocol: http
  Port: 80
  IPAddress: '*'

В приведенном выше примере — массив со значениями класса MSFT_xWebBindingInformation <https://github.com/PowerShell/xWebAdministration/blob/dev/DSCResources/MSFT_xWebsite/MSFT_xWebsite.schema.mof>``_. When defining a ``[CimInstance[]], обязательно ознакомьтесь с документацией ресурса, чтобы узнать, какие ключи следует использовать в определении.

Запуск от имени другого пользователя

По умолчанию DSC запускает каждый ресурс от имени учетной записи SYSTEM, а не от имени учетной записи, используемой Ansible для запуска модуля. Это означает, что ресурсы, которые динамически загружаются на основе профиля пользователя, такие как ветвь реестра HKEY_CURRENT_USER , будут загружаться в профиле SYSTEM. Параметр PsDscRunAsCredential` — это параметр, который можно установить для каждого ресурса DSC, чтобы заставить движок DSC запускаться от имени другой учетной записи. Так как PsDscRunAsCredential имеет тип PSCredential, он определяется с суффиксами _username и _password.

В качестве примера с ресурсом реестра, вот как определить задачу для доступа к ветви реестра HKEY_CURRENT_USER пользователя Ansible:

- name: use win_dsc with PsDscRunAsCredential to run as a different user
  win_dsc:
    resource_name: Registry
    Ensure: Present
    Key: HKEY_CURRENT_USER\ExampleKey
    ValueName: TestValue
    ValueData: TestData
    PsDscRunAsCredential_username: '{{ansible_user}}'
    PsDscRunAsCredential_password: '{{ansible_password}}'
  no_log: true

Пользовательские ресурсы DSC

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

Поиск пользовательских ресурсов DSC

Вы можете использовать PSGallery для поиска пользовательских ресурсов, а также документации по их установке на хосте Windows.

Также можно использовать командлет Find-DscResource для поиска пользовательских ресурсов. Например:

# find all DSC resources in the configured repositories
Find-DscResource

# find all DSC resources that relate to SQL
Find-DscResource -ModuleName "*sql*"

Установка пользовательского ресурса

Существует три способа установки ресурса DSC на хост:

• Вручную с помощью командлета Install-Module
• С помощью модуля Ansible win_psmodule
• Сохранение модуля вручную и копирование его на другой хост

Вот пример установки ресурсов xWebAdministration с помощью win_psmodule:

- name: install xWebAdministration DSC resource
  win_psmodule:
    name: xWebAdministration
    state: present

После установки модуль win_dsc сможет использовать ресурс, ссылаясь на него с помощью параметра resource_name.

Два первых метода работают только тогда, когда у хоста есть доступ к интернету. Если доступ к интернету отсутствует, модуль сначала необходимо установить на другом хосте с доступом в интернет, а затем скопировать. Чтобы сохранить модуль в локальный путь, можно выполнить следующий командлет PowerShell:

Save-Module -Name xWebAdministration -Path C:\temp

Это создаст папку xWebAdministration в C:\temp, которую можно скопировать на любой хост. Чтобы PowerShell видел этот автономный ресурс, его необходимо скопировать в директорию, заданную переменной среды PSModulePath. В большинстве случаев путь C:\Program Files\WindowsPowerShell\Module устанавливается через эту переменную, но модуль win_path может быть использован для добавления других путей.

Примеры

Извлечение файла zip

- name: extract a zip file
  win_dsc:
    resource_name: Archive
    Destination: c:\temp\output
    Path: C:\temp\zip.zip
    Ensure: Present

Создание директории

- name: create file with some text
  win_dsc:
    resource_name: File
    DestinationPath: C:\temp\file
    Contents: |
        Hello
        World
    Ensure: Present
    Type: File

- name: create directory that is hidden is set with the System attribute
  win_dsc:
    resource_name: File
    DestinationPath: C:\temp\hidden-directory
    Attributes: Hidden,System
    Ensure: Present
    Type: Directory

Взаимодействие с Azure

- name: install xAzure DSC resources
  win_psmodule:
    name: xAzure
    state: present

- name: create virtual machine in Azure
  win_dsc:
    resource_name: xAzureVM
    ImageName: a699494373c04fc0bc8f2bb1389d6106__Windows-Server-2012-R2-201409.01-en.us-127GB.vhd
    Name: DSCHOST01
    ServiceName: ServiceName
    StorageAccountName: StorageAccountName
    InstanceSize: Medium
    Windows: True
    Ensure: Present
    Credential_username: '{{ansible_user}}'
    Credential_password: '{{ansible_password}}'

Настройка веб-сайта IIS

- name: install xWebAdministration module
  win_psmodule:
    name: xWebAdministration
    state: present

- name: install IIS features that are required
  win_dsc:
    resource_name: WindowsFeature
    Name: '{{item}}'
    Ensure: Present
  with_items:
  - Web-Server
  - Web-Asp-Net45

- name: setup web content
  win_dsc:
    resource_name: File
    DestinationPath: C:\inetpub\IISSite\index.html
    Type: File
    Contents: |
      <html>
      <head><title>IIS Site</title></head>
      <body>This is the body</body>
      </html>
    Ensure: present

- name: create new website
  win_dsc:
    resource_name: xWebsite
    Name: NewIISSite
    State: Started
    PhysicalPath: C:\inetpub\IISSite\index.html
    BindingInfo:
    - Protocol: https
      Port: 8443
      CertificateStoreName: My
      CertificateThumbprint: C676A89018C4D5902353545343634F35E6B3A659
      HostName: DSCTest
      IPAddress: '*'
      SSLFlags: 1
    - Protocol: http
      Port: 8080
      IPAddress: '*'
    AuthenticationInfo:
      Anonymous: no
      Basic: yes
      Digest: no
      Windows: yes