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

この記事では、Desired State Configuration (DSC) 拡張機能ハンドラーの Azure Resource Manager テンプレートについて説明します。 多くの例では、Azure Automation を使用してオンボードするために、RegistrationURL (String として指定) と RegistrationKey (PSCredential として指定) を使用しています。 それらの値の取得に関する詳細については、「DSC メタ構成を使用してハイブリッド マシンを登録する」を参照してください。

Windows VM のテンプレートの例

以下のスニペットは、テンプレートの Resource セクションに含まれます。 DSC 拡張機能は、既定の拡張機能プロパティを継承します。 詳しくは、「VirtualMachineExtension class (VirtualMachineExtension クラス)」をご覧ください。

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/Microsoft.Powershell.DSC')]",
  "apiVersion": "2018-06-01",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', parameters('VMName'))]"
  ],
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "protectedSettings": {
      "Items": {
        "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
      }
    },
    "settings": {
      "Properties": [
        {
          "Name": "RegistrationKey",
          "Value": {
            "UserName": "PLACEHOLDER_DONOTUSE",
            "Password": "PrivateSettingsRef:registrationKeyPrivate"
          },
          "TypeName": "System.Management.Automation.PSCredential"
        },
        {
          "Name": "RegistrationUrl",
          "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
          "TypeName": "System.String"
        },
        {
          "Name": "NodeConfigurationName",
          "Value": "[parameters('nodeConfigurationName')]",
          "TypeName": "System.String"
        }
      ]
    }
  }
}

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

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

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

"extensionProfile": {
    "extensions": [
      {
        "name": "Microsoft.Powershell.DSC",
        "properties": {
          "publisher": "Microsoft.Powershell",
          "type": "DSC",
          "typeHandlerVersion": "2.77",
          "autoUpgradeMinorVersion": true,
          "protectedSettings": {
            "Items": {
              "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
            }
          },
          "settings": {
            "Properties": [
              {
                "Name": "RegistrationKey",
                "Value": {
                  "UserName": "PLACEHOLDER_DONOTUSE",
                  "Password": "PrivateSettingsRef:registrationKeyPrivate"
                },
                "TypeName": "System.Management.Automation.PSCredential"
              },
              {
                "Name": "RegistrationUrl",
                "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
                "TypeName": "System.String"
              },
              {
                "Name": "NodeConfigurationName",
                "Value": "[parameters('nodeConfigurationName')]",
                "TypeName": "System.String"
              }
            ]
          }
        }
      }
    ]
  }

設定情報の詳細

次のスキーマは、Resource Manager テンプレートの Azure DSC 拡張機能の settings セクションで使用します。

既定の構成スクリプトで使用可能な引数の一覧については、「既定の構成スクリプト」をご覧ください。

"settings": {
    "wmfVersion": "latest",
    "configuration": {
        "url": "http://validURLToConfigLocation",
        "script": "ConfigurationScript.ps1",
        "function": "ConfigurationFunction"
    },
    "configurationArguments": {
        "argument1": "Value1",
        "argument2": "Value2"
    },
    "configurationData": {
        "url": "https://foo.psd1"
    },
    "privacy": {
        "dataCollection": "enable"
    },
    "advancedOptions": {
        "downloadMappings": {
            "customWmfLocation": "http://myWMFlocation"
        }
    }
},
"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
            "userName": "UsernameValue1",
            "password": "PasswordValue1"
        },
        "parameterOfTypePSCredential2": {
            "userName": "UsernameValue2",
            "password": "PasswordValue2"
        }
    },
    "configurationUrlSasToken": "?g!bber1sht0k3n",
    "configurationDataUrlSasToken": "?dataAcC355T0k3N"
}

詳細

既定の構成スクリプト

次の値について詳しくは、ローカル構成マネージャーの基本設定に関するページをご覧ください。 DSC 拡張機能の既定の構成スクリプトは、次の表に記載されている LCM プロパティの構成にのみ使用できます。

settings と protectedSettings

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

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

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

構成スクリプトの例

次の例は、DSC 拡張機能の既定の動作を示したものです (LCM にメタデータの設定を提供し、Automation DSC サービスに登録します)。 構成引数は必須です。 構成引数は、LCM のメタデータを設定するために既定の構成スクリプトに渡されます。

"settings": {
    "configurationArguments": {
        "RegistrationUrl" : "[parameters('registrationUrl1')]",
        "NodeConfigurationName" : "nodeConfigurationNameValue1"
    }
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "registrationKey"
        }
    }
}

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..."
}

参照されている Azure Automation 登録の値の使用例

次の例では、Azure Automation アカウントのプロパティを参照し、listkeys メソッドを使用して主キー (0) を取得することで、RegistrationUrl と RegistrationKey を取得します。 この例では、パラメーター automationAccountName および NodeConfigName がテンプレートに指定されています。

"settings": {
    "RegistrationUrl" : "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
    "NodeConfigurationName" : "[parameters('NodeConfigName')]"
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-01-15').Keys[0].value]"
        }
    }
}

以前の形式からの更新

拡張機能の以前の形式の設定 (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"
}

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

トラブルシューティング

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

無効な値

"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 が有効な場所に解決されていることを確認します。

無効な RegistrationKey の型

"Invalid type for parameter RegistrationKey of type PSCredential. (型 PSCredential のパラメーター RegistrationKey の無効な型。)"

問題点:protectedSettings.configurationArguments の RegistrationKey の値は、PSCredential 以外の型としては指定できません。

解決策:RegistrationKey の protectedSettings.configurationArguments エントリを、次の形式を使用して PSCredential 型に変更してください。

"configurationArguments": {
    "RegistrationKey": {
        "userName": "NOT_USED",
        "Password": "RegistrationKey"
    }
}

無効な 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 ドキュメント センターを参照してください。