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

• Что такое Конфигурация Желаемого Состояния?
• Требования к хосту
• Зачем использовать DSC?

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

  • Типы свойств

    • PSCredential
    • Тип CimInstance
    • Тип HashTable
    • Массивы
    • DateTime
  • Запуск от имени другого пользователя

• Пользовательские ресурсы 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 и Ansible win_file могут быть использованы для достижения той же цели. Решение о том, какой из них использовать, зависит от конкретной ситуации.

Причины использования модуля 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

Начиная с Ansible 2.8, модуль win_dsc автоматически проверяет входные параметры Ansible с определением DSC. Это означает, что Ansible завершится ошибкой, если имя параметра некорректно, обязательный параметр не задан или значение не является допустимым выбором. При запуске Ansible с уровнем подробности 3 или выше (-vvv) возвращаемое значение будет содержать возможные варианты вызова на основе указанного resource_name. Вот пример выходных данных вызова для вышеупомянутой задачи Registry.

changed: [2016] => {
    "changed": true,
    "invocation": {
        "module_args": {
            "DependsOn": null,
            "Ensure": "Present",
            "Force": null,
            "Hex": null,
            "Key": "HKEY_LOCAL_MACHINE\\SOFTWARE\\ExampleKey",
            "PsDscRunAsCredential_password": null,
            "PsDscRunAsCredential_username": null,
            "ValueData": [
                "TestData"
            ],
            "ValueName": "TestValue",
            "ValueType": null,
            "module_version": "latest",
            "resource_name": "Registry"
        }
    },
    "module_version": "1.1",
    "reboot_required": false,
    "verbose_set": [
        "Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = ResourceSet,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.",
        "An LCM method call arrived from computer SERVER2016 with user sid S-1-5-21-3088887838-4058132883-1884671576-1105.",
        "[SERVER2016]: LCM:  [ Start  Set      ]  [[Registry]DirectResourceAccess]",
        "[SERVER2016]:                            [[Registry]DirectResourceAccess] (SET) Create registry key 'HKLM:\\SOFTWARE\\ExampleKey'",
        "[SERVER2016]:                            [[Registry]DirectResourceAccess] (SET) Set registry key value 'HKLM:\\SOFTWARE\\ExampleKey\\TestValue' to 'TestData' of type 'String'",
        "[SERVER2016]: LCM:  [ End    Set      ]  [[Registry]DirectResourceAccess]  in 0.1930 seconds.",
        "[SERVER2016]: LCM:  [ End    Set      ]    in  0.2720 seconds.",
        "Operation 'Invoke CimMethod' complete.",
        "Time taken for configuration job to complete is 0.402 seconds"
    ],
    "verbose_test": [
        "Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = ResourceTest,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.",
        "An LCM method call arrived from computer SERVER2016 with user sid S-1-5-21-3088887838-4058132883-1884671576-1105.",
        "[SERVER2016]: LCM:  [ Start  Test     ]  [[Registry]DirectResourceAccess]",
        "[SERVER2016]:                            [[Registry]DirectResourceAccess] Registry key 'HKLM:\\SOFTWARE\\ExampleKey' does not exist",
        "[SERVER2016]: LCM:  [ End    Test     ]  [[Registry]DirectResourceAccess] False in 0.2510 seconds.",
        "[SERVER2016]: LCM:  [ End    Set      ]    in  0.3310 seconds.",
        "Operation 'Invoke CimMethod' complete.",
        "Time taken for configuration job to complete is 0.475 seconds"
    ]
}

Ключ invocation.module_args отображает фактические установленные значения, а также другие возможные значения, которые не были установлены. К сожалению, это не отобразит значение по умолчанию для свойства DSC, а только то, что было установлено задачей Ansible. Любой параметр *_password будет замаскирован в выходных данных по соображениям безопасности, если есть другие конфиденциальные параметры модуля, установите no_log: True в задаче, чтобы остановить ведение журнала всех выходных данных задачи.

Типы свойств

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

PSCredential

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

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

SourceCredential_username: AdminUser
SourceCredential_password: PasswordForAdminUser

Объект [PSCredential] определён с EmbeddedInstance("MSFT_Credential") в определении MOF ресурса DSC.

Тип CimInstance

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

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

В приведенном выше примере CIM-экземпляр представляет класс MSFT_xWebAuthenticationInformation. Этот класс принимает четыре булевых переменных: Anonymous, Basic, Digest, и Windows. Ключи, используемые в [CimInstance], зависят от представляемого класса. Пожалуйста, ознакомьтесь с документацией ресурса, чтобы определить используемые ключи и типы каждого значения ключа. Определение класса, как правило, находится в <resource name>.schema.mof.

Тип HashTable

Объект [HashTable] также является словарем, но не имеет строгого набора ключей, которые нужно/нужно определить. Как и [CimInstance], определите его как обычное значение словаря в YAML. Объект [HashTable]] определён с EmbeddedInstance("MSFT_KeyValuePair") в определении MOF ресурса DSC.

Массивы

Массивы простых типов, такие как [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. При определении [CimInstance[]], обязательно обратитесь к документации ресурса, чтобы узнать, какие ключи использовать в определении.

DateTime

Объект [DateTime] — это строка DateTime, представляющая дату и время в формате ISO 8601. Значение для поля [DateTime] в YAML должно быть заключено в кавычки, чтобы гарантировать правильную сериализацию строки в хост Windows. Вот пример того, как определить значение [DateTime] в Ansible:

# As UTC-0 (No timezone)
DateTime: '2019-02-22T13:57:31.2311892+00:00'

# As UTC+4
DateTime: '2019-02-22T17:57:31.2311892+04:00'

# As UTC-4
DateTime: '2019-02-22T09:57:31.2311892-04:00'

Все вышеперечисленные значения эквивалентны дате и времени UTC 22 февраля 2019 года в 13:57:31.2311892.

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

По умолчанию 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: yes

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

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

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

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

Для поиска пользовательских ресурсов также можно использовать cmdlet 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 на хост:

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

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

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

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

Вышеупомянутые два метода работают только в том случае, если хост имеет доступ к интернету. Если у хоста нет доступа к интернету, модуль необходимо сначала установить с помощью вышеупомянутых методов на другом хосте с доступом к интернету, а затем скопировать его. Для сохранения модуля в локальный путь можно запустить следующий cmdlet 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: yes
    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
  loop:
  - 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