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

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

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

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

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

Для использования модуля win_dsc, хост Windows должен иметь установленную PowerShell версию 5.0 или выше. Все поддерживаемые хосты могут быть обновлены до 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 не поддерживают режим diff, в то время как некоторые модули Ansible поддерживают
• Пользовательские ресурсы требуют дополнительных шагов по установке перед запуском на хосте, в то время как модули Ansible встроены в Ansible
• В ресурсе DSC есть ошибки, где модуль Ansible работает

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

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

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

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

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

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

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

SourceCredential_username: AdminUser
SourceCredential_password: PasswordForAdminUser

# [CimInstance]AuthenticationInfo == MSFT_xWebAuthenticationInformation
AuthenticationInfo:
  Anonymous: false
  Basic: true
  Digest: false
  Windows: true

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

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

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

# 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'

- 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. Можно установить пользовательские модули для управления другими ресурсами, которые обычно недоступны.

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

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

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

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

Примеры

- 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

- 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 }}'

- 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: false
      Basic: true
      Digest: false
      Windows: true