Azure Resource Manager テンプレートを使用した Desired State Configuration 拡張機能

[アーティクル]
12/19/2024

Note

DSC 拡張機能を有効にする前に、マシンの構成という名前の機能によって管理される新しいバージョンの DSC が一般提供されていることに注意してください。マシン構成機能には、Desired State Configuration (DSC) 拡張機能ハンドラーの機能と、お客様からのフィードバックから最も一般的に要求される機能が含まれています。マシンの構成には、Arc 対応サーバーによるハイブリッドマシンのサポートも含まれています。

この記事では、Desired State Configuration (DSC) 拡張機能ハンドラーの Azure Resource Manager テンプレートについて説明します。

Note

スキーマの例に若干の違いがある可能性があります。スキーマの変更は 2016 年 10 月のリリースで発生しました。詳しくは、以前の形式からの更新に関する記事をご覧ください。

VM の Bicep の例

DSC 拡張機能は、既定の拡張機能プロパティを継承します。詳しくは、「VirtualMachineExtension class (VirtualMachineExtension クラス)」をご覧ください。

@description('URI of the configuration package')
param configUri string

@description('first configuration parameter')
param arg1 string

@description('second configuration parameter')
@secure()
param arg2 string

var configName = split(split(configUri, '/')[4], '.')[0]

resource vm 'Microsoft.Compute/virtualMachines@2023-09-01' existing = {
  name: srvName
}

resource configuration_dscext 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: 'configurationname_dscext'
  parent: vm
  location: location
  properties: {
    publisher: 'Microsoft.Powershell'
    type: 'DSC'
    typeHandlerVersion: '2.77'
    autoUpgradeMinorVersion: true
    settings: {
      wmfVersion: 'latest'
      configuration: {
        url: configUri
        script: 'configurationname_dscext.ps1'
        function: 'configurationname_dscext'
      }
      configurationArguments: {
        arg1: arg1
      }
      advancedOptions: {
        rebootNodeIfNeeded: true
      }
    }
    protectedSettings: {
      configurationArguements: {
        arg2: arg2
      }
    }
  }
}

Windows 仮想マシンスケールセット用の Bicep 例

仮想マシンスケールセットノードには、extensionProfile 属性を含むセクションがあります。 [拡張機能] の下に DSC 拡張機能の詳細を追加します。

仮想マシンスケールセットの拡張機能をデプロイするテンプレートの作成に関する最新の詳細については、「Microsoft.Compute virtualMachineScaleSets」ドキュメントを参照してください

DSC 拡張機能は、既定の拡張機能プロパティを継承します。詳しくは、「VirtualMachineScaleSetExtension class (VirtualMachineScaleSetExtension クラス)」をご覧ください。

settings と protectedSettings

すべての設定は、VM の設定テキストファイルに保存されます。 settings の下に記載されているプロパティはパブリックプロパティです。パブリックプロパティは、設定のテキストファイル内で暗号化されません。 protectedSettings の下に記載されたプロパティは証明書で暗号化されるため、VM 上の設定ファイルにプレーンテキストで表示されません。

構成に資格情報が必要な場合は、protectedSettings に資格情報を含めることができます。

"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
               "userName": "UsernameValue1",
               "password": "PasswordValue1"
        }
    }
}

Azure Storage での構成スクリプトの使用例

次の例は、DSC 拡張機能ハンドラーの概要に関する記事から引用したものです。この例では、コマンドレットの代わりに Resource Manager テンプレートを使用して拡張機能をデプロイします。 IisInstall.ps1 の構成を保存し、.zip ファイル (例: iisinstall.zip) 内に配置してから、アクセス可能な URL にファイルをアップロードします。この例では、Azure Blob Storage を使用しますが、.zip ファイルを任意の場所からダウンロードすることもできます。

Resource Manager テンプレートでは、次のコードにより、正しいファイルをダウンロードして適切な PowerShell 関数を実行するように VM に対して指示をします。

"settings": {
    "configuration": {
        "url": "https://demo.blob.core.windows.net/iisinstall.zip",
        "script": "IisInstall.ps1",
        "function": "IISInstall"
    }
},
"protectedSettings": {
    "configurationUrlSasToken": "odLPL/U1p9lvcnp..."
}

以前の形式からの更新

拡張機能の以前の形式の設定 (ModulesUrl、ModuleSource、ModuleVersion、ConfigurationFunction、SasToken、または Properties の各パブリックプロパティを含むもの) は、自動的に拡張機能の現在の形式に対応します。これらは以前と同じように動作します。

次のスキーマは、以前の設定スキーマの例を示したものです。

"settings": {
    "WMFVersion": "latest",
    "ModulesUrl": "https://UrlToZipContainingConfigurationScript.ps1.zip",
    "SasToken": "SAS Token if ModulesUrl points to private Azure Blob Storage",
    "ConfigurationFunction": "ConfigurationScript.ps1\\ConfigurationFunction",
    "Properties": {
        "ParameterToConfigurationFunction1": "Value1",
        "ParameterToConfigurationFunction2": "Value2",
        "ParameterOfTypePSCredential1": {
            "UserName": "UsernameValue1",
            "Password": "PrivateSettingsRef:Key1"
        },
        "ParameterOfTypePSCredential2": {
            "UserName": "UsernameValue2",
            "Password": "PrivateSettingsRef:Key2"
        }
    }
},
"protectedSettings": {
    "Items": {
        "Key1": "PasswordValue1",
        "Key2": "PasswordValue2"
    },
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

以前の形式と現在の形式の対応関係を次に示します。

現在のプロパティ名	対応する以前のスキーマ
settings.wmfVersion	settings.wmfVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	settings.ConfigurationFunction の最初の部分 (\\ の前)
settings.configuration.function	settings.ConfigurationFunction の 2 番目の部分 (\\ の後)
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri (SAS トークンを使用しない)
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.advancedOptions.downloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	protectedSettings.DataBlobUri の SAS トークン

トラブルシューティング

直面する可能性のあるいくつかのエラーとそのエラーの修正方法について説明します。

無効な値

"Privacy.dataCollection is '{0}'. The only possible values are '', 'Enable', and 'Disable' (Privacy.dataCollection は '{0}' です。指定できる値は ''、'Enable'、および 'Disable' のみです)" "WmfVersion is '{0}'. Only possible values are … and 'latest' (WmfVersion は '{0}' です。指定できる値は … および 'latest' のみです)"

問題点: 指定した値が許可されていません。

解決策:無効な値を有効な値に変更してください。

無効な URL

"ConfigurationData.url is '{0}'. This is not a valid URL. (Configuration.url は '{0}' です。これは有効な URL ではありません。)" "DataBlobUri is '{0}'. これは有効な URL ではありません)" "Configuration.url is '{0}'.This is not a valid URL (Configuration.url は '{0}' です。これは有効な URL ではありません)"

問題点: 指定した URL が無効です。

解決策:指定した URL すべてを確認してください。拡張機能がリモートマシンにアクセスできるように、すべての URL が有効な場所に解決されていることを確認します。

無効な ConfigurationArgument の型

"Invalid configurationArguments type {0} (無効な configurationArguments の型 {0})"

問題点:ConfigurationArguments プロパティがハッシュテーブル オブジェクトに解決できません。

解決策:ConfigurationArguments プロパティをハッシュテーブルにしてください。前の例に示されている形式に従います。引用符、コンマ、および中かっこに注意します。

ConfigurationArguments の重複

"Found duplicate arguments '{0}' in both public and protected configurationArguments (パブリックと保護対象の両方の configurationArguments で重複する引数 '{0}' が見つかりました)"

問題点:パブリック設定の ConfigurationArguments と保護された設定の ConfigurationArguments に同じ名前のプロパティが含まれています。

解決策:重複するプロパティのいずれかを削除してください。

不足しているプロパティ

"settings.Configuration.function requires that settings.configuration.url or settings.configuration.module is specified (settings.Configuration.function には、settings.configuration.url または settings.configuration.module の指定が必要です)"

"settings.Configuration.url requires that settings.configuration.script is specified (settings.Configuration.url には settings.configuration.script の指定が必要です)"

"settings.Configuration.script requires that settings.configuration.url is specified (settings.Configuration.script には settings.configuration.url の指定が必要です)"

"settings.Configuration.url requires that settings.configuration.function is specified (settings.Configuration.url には settings.configuration.function の指定が必要です)"

"protectedSettings.ConfigurationUrlSasToken requires that settings.configuration.url is specified (protectedSettings.ConfigurationUrlSasToken には settings.configuration.url の指定が必要です)"

"protectedSettings.ConfigurationDataUrlSasToken requires that settings.configurationData.url is specified (protectedSettings.ConfigurationDataUrlSasToken には settings.configurationData.url の指定が必要です)"

問題点:定義したプロパティには、不足している別のプロパティが必要です。

解決策:

不足しているプロパティを指定します。
不足しているプロパティを必要とするプロパティを削除します。

次のステップ

仮想マシンスケールセットと Azure DSC 拡張機能の使用について知る。
DSC による安全な資格情報管理の詳細を確認する。
Azure DSC 拡張機能ハンドラーの概要を確認する。
PowerShell DSC の詳細については、PowerShell ドキュメントセンターを参照してください。

次の方法で共有

Azure Resource Manager テンプレートを使用した Desired State Configuration 拡張機能

VM の Bicep の例

Windows 仮想マシンスケールセット用の Bicep 例

settings と protectedSettings

Azure Storage での構成スクリプトの使用例

以前の形式からの更新

トラブルシューティング

無効な値

無効な URL

無効な ConfigurationArgument の型

ConfigurationArguments の重複

不足しているプロパティ

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Resource Manager テンプレートを使用した Desired State Configuration 拡張機能

VM の Bicep の例

Windows 仮想マシン スケール セット用の Bicep 例

settings と protectedSettings

Azure Storage での構成スクリプトの使用例

以前の形式からの更新

トラブルシューティング

無効な値

無効な URL

無効な ConfigurationArgument の型

ConfigurationArguments の重複

不足しているプロパティ

次のステップ

フィードバック

その他のリソース

Windows 仮想マシンスケールセット用の Bicep 例