DSC リソース

Microsoft の Desired State Configuration (DSC) プラットフォームでは、DSC リソースはシステムの設定を管理するための標準化されたインターフェイスを表します。 リソースは、コンポーネントをファイルとして汎用として、または IIS サーバー設定として特定としてモデル化できます。 リソースでは、命令型ではなく宣言型構文が使用されます。 DSC では システムを目的の状態に設定する 方法を指定する代わりに、必要な状態 指定します。 リソースは"方法" を処理します。

リソースは、構成可能なコンポーネント インスタンスを管理します。 たとえば、PSDscResources/Environment リソースは環境変数を管理します。 各環境変数は、リソースの異なるインスタンスです。 すべてのリソースは、リソースのインスタンスを検証および管理する方法を記述するスキーマを定義します。

DSCv3 では、いくつかの種類のリソースがサポートされています。

• リソース マニフェストで定義されたリソースは、コマンド ベースの リソースです。 DSC はマニフェストを使用して、リソースを呼び出す方法と、リソース インスタンスのプロパティを検証する方法を決定します。
• リソース グループ は、リソース インスタンスの配列を受け取って処理する resources プロパティを持つコマンド ベースのリソースです。 リソース グループは、リソースを実行するユーザーの変更など、入れ子になったリソース インスタンスに特別な処理を適用できます。
• リソース プロバイダー は、DSCv3 でコマンド ベース以外のリソースを使用できるようにするリソース グループです。 たとえば、DSC/PowerShellGroup リソース プロバイダーを使用すると、PowerShell モジュールに実装されている DSC リソースを使用できます。

リソースの種類の名前

リソースは、完全修飾型名によって識別されます。 型名は、構成ドキュメント内のリソースを指定するために使用され、dsc resource * コマンドを使用する場合は --resource フラグの値として使用されます。

リソースの完全修飾型名は、次の構文を使用します。

<owner>[.<group>][.<area>]/<name>

すべてのリソースで、owner と nameを定義する必要があります。 group コンポーネントと area コンポーネントを使用すると、リソースを Microsoft.SqlServer/Database や Microsoft.SqlServer.Database/Roleなどの関連する名前空間に編成できます。

型名とその検証方法の詳細については、「DSC リソースの完全修飾型名スキーマリファレンス を参照してください。

リソースのプロパティ

リソースのプロパティは、ユーザーがインスタンスを管理するために宣言できる設定とオプションです。 リソースには、常に少なくとも 1 つのプロパティがあります。 リソースは、スキーマでプロパティを定義します。

既定では、プロパティは省略可能です。 リソースは、現在のタスクまたは目的に関連するプロパティのみを使用して、構成で直接呼び出したり、宣言したりできます。 インスタンスのすべてのプロパティを宣言する必要はありません。 プロパティには、目的の状態の既定値が設定されている場合があります。

ほとんどのプロパティは、基本的な型の 1 つです。

• 文字列プロパティでは、プロパティ値を一連の文字 (machineなど) にする必要があります。
• 整数プロパティでは、プロパティ値を小数部のない数値にする必要があります (例: 5)。
• ブール型のプロパティでは、プロパティ値が true または falseである必要があります。
• 配列プロパティでは、プロパティ値を項目の一覧にする必要があります。 通常、配列プロパティは、終了コード整数のリストやファイル パスの一覧など、値が特定の型である必要があることを指定します。

複合プロパティでは、プロパティ値が定義されたサブプロパティを持つオブジェクトである必要があります。 サブプロパティは基本型でも複合型でもかまいませんが、通常は基本型です。

リソースの一覧表示

DSC を使用して、dsc resource list コマンドを使用して使用可能なリソースを一覧表示できます。 DSC は PATH でコマンド ベースのリソースを検索し、使用可能なリソース プロバイダーを呼び出してリソースを一覧表示します。

既定では、このコマンドは検出されたすべての DSC リソースを返します。

dsc resource list

type                       version tags                        description
----                       ------- ----                        -----------
Test/TestGroup             0.1.0
Microsoft/OSInfo           0.1.0   {os, linux, windows, macos} Returns information about the operating system.
Microsoft.Windows/Registry 0.1.0   {Windows, NT}               Registry configuration provider for the Windows Registry
                                                               This is a test resource.
DSC/PowerShellGroup        0.1.0   {PowerShell}                Resource provider to classic DSC Powershell resources.
DSC/AssertionGroup         0.1.0                               `test` will be invoked for all resources in the supplied configuration.
DSC/ParallelGroup          0.1.0                               All resources in the supplied configuration run concurrently.
                                                               This is a test resource.
DSC/Group                  0.1.0                               All resources in the supplied configuration is treated as a group.

リソースの種類の名前、説明、タグで結果をフィルター処理できます。 詳細については、「dsc リソース の一覧 を参照してください。

リソースの呼び出し

dsc resource * コマンドを使用してリソースを直接呼び出し、の取得、テスト、Setの 3 つの DSC 操作1 つのインスタンスを管理できます。

操作を取得する

すべてのリソースは、リソース インスタンスの実際の状態を取得する Get 操作を実装します。 dsc resource get コマンドを使用して操作を呼び出します。

たとえば、Microsoft.Windows/Registry リソースを使用して、レジストリ キー値の実際の状態を取得できます。

'{
    "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
    "valueName": "SystemRoot"
}' | dsc resource get --resource Microsoft.Windows/Registry

actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

テスト操作

一部のリソースでは、Test 操作が実装されています。 テスト 操作を実装していないリソースの場合、DSCv3 は合成テストを使用してインスタンスの状態を検証できます。 合成テストは、インスタンスのプロパティの必要な値と実際の値の厳密な大文字と小文字を区別しない比較です。 高度な検証要件または複雑な検証要件を持つリソースのみが、Test 操作自体を実装する必要があります。

dsc resource test コマンドを使用して操作を呼び出します。 DSC は、次を含むデータを返します。

• インスタンスの目的の状態。
• インスタンスの実際の状態。
• インスタンスが目的の状態であるかどうかを示します。
• 目的の状態ではないプロパティの一覧。

たとえば、特定のレジストリ キーが存在するかどうかをテストできます。

'{
    "keyPath": "HKCU\\key\\that\\does\\not\\exist",
}' | dsc resource test --resource Microsoft.Windows/Registry

desiredState:
  keyPath: HKCU\key\that\does\not\exist
actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: ''
  _inDesiredState: false
inDesiredState: false
differingProperties:
- keyPath

操作の設定

ほとんどのリソースでは、Set 操作が実装され、インスタンスに必要な状態が適用されます。 DSCv3 と共に使用する場合、Set 操作はべき等 。つまり、インスタンスが目的の状態でない場合にのみリソースが操作を呼び出します。 操作はべき等であるため、繰り返し呼び出すことは、1 回呼び出すのと同じです。 べき等モデルを使用すると、副作用によってコードが不必要に実行されるのを防ぐことができます。

Set 操作を実装していないリソースは、アサーション リソース。 アサーション リソースを使用してインスタンスの状態を取得および検証できますが、それらを使用して目的の状態を強制することはできません。

dsc resource set コマンドを使用して操作を呼び出します。 DSC は、次を含むデータを返します。

• 操作前のインスタンスの状態。
• 操作後のインスタンスの状態。
• 操作が変更されたプロパティの一覧。

たとえば、存在しないキーの目的の状態を設定することで、レジストリ キーを作成できます。

'{
    "keyPath":   "HKCU\\example\\key",
    "valueName": "Example",
    "valueData": { "String": "This is an example." }
}' | dsc resource set --resource Microsoft.Windows/Registry

beforeState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: ''
afterState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKCU\example\key
  valueName: Example
  valueData:
    String: This is an example.
changedProperties:
- keyPath
- valueName
- valueData

リソース インスタンスの宣言

DSC 構成ドキュメントを使用すると、一度に複数のリソースまたはリソース インスタンスを管理できます。 構成ドキュメントでは、リソース インスタンスのコレクションとその目的の状態が宣言されています。 これにより、コンプライアンスのセキュリティ ベースラインの定義や Web ファームの設定など、さまざまなリソースとインスタンスを一緒に作成することで、複雑な目的の状態をモデル化できます。

リソース インスタンス宣言には、常に次のものが含まれます。

• name - ドキュメント内で一意のインスタンスの、人間が判読できる短い名前。 この名前はログ記録に使用され、ドキュメント内のインスタンスの目的を文書化するのに役立ちます。
• type - インスタンスの管理に DSC が使用するリソースを識別するためのリソースの完全修飾型名。
• properties - インスタンスの目的の状態。 DSC は、リソースのインスタンス スキーマに対して値を検証します。

この構成ドキュメント スニペットの例では、Microsoft.Windows/Registry リソースのインスタンスを宣言します。

$schema: https://schemas.microsoft.com/dsc/2023/08/configuration.schema.json
resources:
  - name: example key value
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.

関連項目

• コマンド ベースの DSC リソース の構造を使用して、選択した言語でのリソースの作成について学習します。
• 構成ドキュメント、構成ドキュメントでリソースを使用する方法について説明します。
• 'dsc resource' コマンド のコマンド ライン リファレンス