Desired State Configuration

Desired State Configuration とは

Desired State Configuration (DSC) は、PowerShell に同梱されているツールで、 コードを使用して Windows ホストのセットアップを定義するのに使用されます。DSC の全般的な目的は Ansible と同じになりますが、 実行方法が異なります。Ansible 2.4 以降では、 win_dsc モジュールが追加され、 Windows ホストと対話するときに既存の DSC リソースを活用するために使用できます。

DSC の詳細は「DSC Overview」を参照してください。

ホスト要件

win_dsc モジュールを使用するには、 Windows ホストに PowerShell v5.0 以降がインストールされている必要があります。Windows Server 2008 (R2以外) を除く、 サポートされているすべてのホストは、PowerShell v5 にアップグレードできます。

PowerShell の要件が満たされると、 DSC の使用は win_dsc モジュールでタスクを作成するのと同じくらい簡単です。

DSC を使用する理由

DSC および Ansible モジュールには、 リソースの状態を定義して保証するという共通の目標があります。このため、 DSC の ファイルリソース や、 Ansible の win_file などのリソースを使用して、同じ結果を得ることができます。どちらを使用するかは、 シナリオによって異なります。

DSC リソースで Ansible モジュールを使用する理由:

• ホストが PowerShell v5.0 をサポートしていない、または簡単にアップグレードできない。
• DSC リソースが、Ansible モジュールに存在する機能を提供していない。たとえば、 win_regedit は、REG_NONE プロパティータイプを管理できますが、 DSC の Registry リソースは管理できません。
• DSC リソースはチェックモードのサポートに制限があるが、 一部の Ansible モジュールはより優れたチェックを備えている。
• DSC リソースでは差分モードがサポートされないが、一部の Ansible モジュールではサポートされる。
• Ansible モジュールは Ansible に組み込まれているが、カスタムリソースでは、 事前にホストで追加のインストール手順を実行する必要がある。
• Ansible モジュールが機能する DSC リソースにバグがある。

Ansible モジュールで DSC リソースを使用する理由:

• Ansible モジュールは、DSC リソースに存在する機能をサポートしていない。
• 利用可能な Ansible モジュールがない。
• 既存の Ansible モジュールにバグがある。

結局のところ、タスクが DSC および Ansible モジュールのどちらで実行されるかは重要でありません。 重要なのは、タスクが正しく実行され、 Playbooks が理解しやすいかどうかです。Ansible よりも DSC の方を長く使用していて、それで問題が解決する場合は、 そのタスクに DSC を使用すると良いでしょう。

DSC の使用方法

win_dsc モジュールは、管理しているリソースに応じて変更できるように、 自由形式のオプションを採用しています。組み込みリソースの一覧は、 「resources」を参照してください。

たとえば Registry リソースを使用した場合は、 以下は、Microsoft 社が提供している DSC 定義です。

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 オプションを区別しやすくなるため、大文字と小文字をそのまま維持することが推奨されます。

上記の DSC レジストリーリソースの Ansible タスクバージョンは、以下のようになります。

- 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 モジュールは DSC 定義を使用して、 Ansible からの入力オプションを自動的に検証します。つまり、オプション名が正しくない場合、必須オプションが設定されていない場合、 または値が有効な選択肢ではない場合は、 Ansible が失敗します。詳細レベル 3 以上 (-vvv) で Ansible を実行する場合、戻り値には、 指定された 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 の Playbook は、 実行中に、定義されたオプションを正しいタイプに変換しようとします。 [string] や [bool] のように単純な場合は、操作も簡単になりますが、 [PSCredential] やアレイ ([string[]] など) のような複雑なものには、 特定のルールが必要です。

PSCredential

[PSCredential] オブジェクトは、安全な方法で認証情報を保存するために使用されますが、 Ansible はこれを JSON 経由でシリアル化する方法がありません。DSC PSCredential プロパティーを設定するには、 そのパラメーターの定義に、 ユーザー名とパスワードにそれぞれ _username と _password が接尾辞として付けられた 2 つのエントリーが必要です。 例:

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

SourceCredential_username: AdminUser
SourceCredential_password: PasswordForAdminUser

Note

2.8 より古いバージョンの Ansible では、Ansible のタスク定義で no_log: yes を設定して、 使用される認証情報が、 ログファイルやコンソール出力に保存されないようにする必要があります。

[PSCredential] は、DSC リソースの MOF 定義の EmbeddedInstance("MSFT_Credential") で定義されています。

CimInstance タイプ

[CimInstance] オブジェクトは、 DSC が使用するディクショナリーオブジェクトを格納するために使用されます。YAML で [CimInstance] を受け取る値を定義することは、 YAML でディクショナリーを定義することと同じです。 たとえば、Ansibleで [CimInstance] 値を定義する場合は、以下のようにします。

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

上記の例では、 CIM インスタンスは、クラス MSFT_xWebAuthenticationInformation の表現になります。 このクラスは、Anonymous、Basic、 Digest、および Windows の 4 つのブール変数を受け入れます。[CimInstance] で使用するキーは、 それが表すクラスによって異なります。リソースのドキュメントを読んで、 使用できるキーと各キー値のタイプを確認してください。module_version は、 <resource name>.schema.mof にあります。

HashTable タイプ

[HashTable] オブジェクトはディクショナリーでもありますが、定義できる、 または定義する必要がある厳密なキーのセットはありません。[CimInstance] のように、 YAML の通常のディクショナリーの値のように定義します。[HashTable]] は、 DSC リソース MOF 定義の EmbeddedInstance("MSFT_KeyValuePair") で定義されています。

アレイ

[string[]] や [UInt32[]] のような単純なアレイはリストとして定義されます または、コンマで区切られた文字列として、その型にキャストされます。値は DSC エンジンに渡される前に、 win_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 クラスの値を 2 つ持つアレイです。 [CimInstance[]] を定義するときは、 必ずリソースのドキュメントを参照して、定義で使用するキーを確認してください。

DateTime

[DateTime] オブジェクトは、ISO 8601 の日時形式で、 日付と時刻を表す DateTime文字列です。文字列が、 Windows ホストに適切にシリアル化されるようにするには、 [DateTime] フィールドの値を YAML で引用する必要があります。たとえば、Ansibleで [DateTime] 値を定義する場合は、 以下のようにします。

# 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 日付時刻の 2019 年 2 月 22 日午後 1 時 57 分 31 秒と 2311892 ミリ秒と同じです。

別のユーザーとして実行

デフォルトでは、DSC は各リソースを SYSTEM アカウントとして実行し、 Ansible がモジュールの実行に使用するアカウントではありません。つまり、 HKEY_CURRENT_USER レジストリーハイブなど、 ユーザープロファイルに基づいて動的に読み込まれるリソースは、SYSTEM プロファイルの下に読み込まれます。PsDscRunAsCredential パラメーターは、 すべての DSC リソースが、 DSC エンジンを別のアカウントで強制的に実行するように設定できるパラメーターです。PsDscRunAsCredential には、 PSCredential のタイプがあるため、 _username 接尾辞および _password 接尾辞で定義されます。

たとえば、レジストリーリソースタイプを使用して、 Ansible ユーザーの HKEY_CURRENT_USER ハイブにアクセスするタスクを定義する方法は次のとおりです。

- 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 ホストにインストールする方法に関するドキュメントを確認できます。

Find-DscResource コマンドレットを使用して、カスタムリソースを検索することもできます。例:

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

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

Note

x で始まる、 Microsoft 社によって開発された DSC リソースは、リソースが実験的であり、サポート対象ではないことを意味します。

カスタムリソースのインストール

DSC リソースをホストにインストールする方法は 3 つあります。

• Install-Module コマンドレットを手動で使用
• Ansibleモジュール win_psmodule を使用
• モジュールを手動で保存して別のホストにコピー

以下の例は、 win_psmodule を使用して xWebAdministration リソースをインストールする例になります。

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

インストールすると、 resource_name オプションを使用してそれを参照することで、win_dsc モジュールがリソースを使用できるようになります。

上記の最初の2つの方法は、ホストがインターネットにアクセスできる場合にのみ機能します。 ホストがインターネットにアクセスできない場合、 モジュールはまずインターネットにアクセスできる別のホストに上記の方法を使用してインストールし、 次にコピーする必要があります。モジュールをローカルファイルパスに保存するには、 次の PowerShell コマンドレットを実行します。

Save-Module -Name xWebAdministration -Path C:temp

これにより、C:\temp に xWebAdministration という名前のフォルダーが作成され、 任意のホストにコピーできます。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 Web サイトのセットアップ

- 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

See also

Playbook について

Playbook の概要

ベストプラクティス

ベストプラクティスのアドバイス

Windows モジュールリスト

Windows 固有のモジュールリスト (すべて PowerShell に実装)

ユーザーメーリングリスト

ご質問はございますか。 Google Group をご覧ください。

irc.freenode.net

IRC チャットチャンネル #ansible