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

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

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

Подробнее о DSC можно узнать в разделе Обзор DSC.

Требования к узлу

Для использования модуля win_dsc на узле Windows должна быть установлена PowerShell версии 5.0 или новее. Все поддерживаемые узлы можно обновить до PowerShell v5.

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

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

У модулей DSC и Ansible общая цель — определить и обеспечить состояние ресурса. Поэтому ресурсы, такие как ресурс DSC File и модуль 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 принимает произвольный набор параметров, поэтому его содержимое зависит от управляемого ресурса. Список встроенных ресурсов доступен в разделе ресурсы.

В качестве примера рассмотрим ресурс 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 от параметров win_dsc в Ansible.

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

- 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 == DSC_WebAuthenticationInformation
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 == DSC_WebBindingInformation
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