Azure Desired State Configuration 拡張機能ハンドラーの概要Introduction to the Azure Desired State Configuration extension handler

Azure VM エージェントとそれに関連付けられた拡張機能は、Microsoft Azure インフラストラクチャ サービスの一部です。The Azure VM Agent and associated extensions are part of Microsoft Azure infrastructure services. VM 拡張機能は、VM の機能を拡張し、さまざまな VM の管理操作を簡略化するソフトウェア コンポーネントです。VM extensions are software components that extend VM functionality and simplify various VM management operations.

Azure Desired State Configuration (DSC) 拡張機能の主な用途は、Azure Automation State Configuration (DSC) サービスへの VM のブートストラップです。The primary use case for the Azure Desired State Configuration (DSC) extension is to bootstrap a VM to the Azure Automation State Configuration (DSC) service. このサービスには、VM 構成の継続的な管理や、Azure Monitoring などの他の操作ツールとの統合を含むメリットがあります。The service provides benefits that include ongoing management of the VM configuration and integration with other operational tools, such as Azure Monitoring. この拡張機能を使用して VM をこのサービスに登録することで、複数の Azure のサブスクリプションで機能する柔軟なソリューションが提供されます。Using the extension to register VM's to the service provides a flexible solution that even works across Azure subscriptions.

DSC 拡張機能を Automation DSC サービスから独立して使用することができます。You can use the DSC extension independently of the Automation DSC service. ただし、この場合、構成が VM にプッシュされるだけです。However, this will only push a configuration to the VM. VM 内でローカルに使用する場合を除き、継続的なレポート管理は利用できません。No ongoing reporting is available, other than locally in the VM.

この記事には、Automation のオンボード用の DSC 拡張機能を使用することと、Azure SDK を使用して VM に構成を割り当てるためのツールとして DSC 拡張機能を使用することの両方のシナリオに関する情報が含まれています。This article provides information about both scenarios: using the DSC extension for Automation onboarding, and using the DSC extension as a tool for assigning configurations to VMs by using the Azure SDK.

前提条件Prerequisites

  • ローカル マシン:Azure VM 拡張機能を利用するには、Azure portal または Azure PowerShell SDK のいずれかを使用する必要があります。Local machine: To interact with the Azure VM extension, you must use either the Azure portal or the Azure PowerShell SDK.
  • ゲスト エージェント:DSC 構成で構成する Azure VM は、Windows Management Framework (WMF) 4.0 以降をサポートする OS である必要があります。Guest Agent: The Azure VM that's configured by the DSC configuration must be an OS that supports Windows Management Framework (WMF) 4.0 or later. サポートされている OS バージョンの詳細な一覧については、 DSC 拡張機能のバージョン履歴を参照してください。For the full list of supported OS versions, see the DSC extension version history.

用語と概念Terms and concepts

このガイドでは、読者が次の概念を理解していることを想定しています。This guide assumes familiarity with the following concepts:

  • 構成:DSC 構成ドキュメント。Configuration: A DSC configuration document.
  • ノード:DSC 構成のターゲット。Node: A target for a DSC configuration. このドキュメントでは、ノード は常に Azure VM を指します。In this document, node always refers to an Azure VM.
  • 構成データ:構成に関する環境データが格納されている .psd1 ファイル。Configuration data: A .psd1 file that has environmental data for a configuration.

ArchitectureArchitecture

Azure DSC 拡張機能は、Azure VM エージェント フレームワークを使用して、Azure VM で実行される DSC 構成の配布、適用、およびレポート作成を行います。The Azure DSC extension uses the Azure VM Agent framework to deliver, enact, and report on DSC configurations running on Azure VMs. DSC 拡張機能は、構成ドキュメントと一連のパラメーターを受け取ります。The DSC extension accepts a configuration document and a set of parameters. ファイルが指定されていない場合、既定の構成スクリプトが拡張機能に埋め込まれています。If no file is provided, a default configuration script is embedded with the extension. 既定の構成スクリプトは、ローカル構成マネージャーにメタデータを設定するためにのみ使用されます。The default configuration script is used only to set metadata in Local Configuration Manager.

拡張機能が初めて呼び出されると、次のロジックに従って、あるバージョンの WMF がインストールされます。When the extension is called for the first time, it installs a version of WMF by using the following logic:

  • Azure VM の OS が Windows Server 2016 の場合は、処理は行われません。If the Azure VM OS is Windows Server 2016, no action is taken. Windows Server 2016 では既に PowerShell の最新バージョンがインストールされてるためです。Windows Server 2016 already has the latest version of PowerShell installed.
  • wmfVersion プロパティを指定した場合は、そのバージョンに VM の OS と互換性がない場合を除いて、そのバージョンの WMF がインストールされます。If the wmfVersion property is specified, that version of WMF is installed, unless that version is incompatible with the VM's OS.
  • wmfVersion プロパティを指定しなかった場合は、WMF の適用可能な最新バージョンがインストールされます。If no wmfVersion property is specified, the latest applicable version of WMF is installed.

WMF をインストールするには、再起動が必要です。Installing WMF requires a restart. 再起動後、modulesUrl プロパティで指定された .zip ファイルが拡張機能によってダウンロードされます (指定した場合)。After restarting, the extension downloads the .zip file that's specified in the modulesUrl property, if provided. その場所が Azure Blob ストレージ内の場合は、 sasToken プロパティに SAS トークンを指定して、ファイルにアクセスできます。If this location is in Azure Blob storage, you can specify an SAS token in the sasToken property to access the file. .zip がダウンロードされて展開された後、configurationFunction で定義されている構成関数が実行され、.mof (Managed Object Format) ファイルが生成されます。After the .zip is downloaded and unpacked, the configuration function defined in configurationFunction runs to generate an .mof(Managed Object Format) file. その後、拡張機能によって、生成された .mof ファイルを使用して Start-DscConfiguration -Force が実行されます。The extension then runs Start-DscConfiguration -Force by using the generated .mof file. 拡張機能は、この出力を取得して Azure の状態チャネルに書き込みます。The extension captures output and writes it to the Azure status channel.

既定の構成スクリプトDefault configuration script

Azure DSC 拡張機能には、VM を Azure Automation DSC サービスにオンボードするときに使用することを目的とした既定の構成スクリプトが含まれています。The Azure DSC extension includes a default configuration script that's intended to be used when you onboard a VM to the Azure Automation DSC service. スクリプト パラメーターは、ローカル構成マネージャーの構成可能なプロパティと合致しています。The script parameters are aligned with the configurable properties of Local Configuration Manager. スクリプト パラメーターについては、Azure Resource Manager テンプレートでの Desired State Configuration 拡張機能に関するページの既定の構成スクリプトに関する記事を参照してください。For script parameters, see Default configuration script in Desired State Configuration extension with Azure Resource Manager templates. 完全なスクリプトについては、GitHub の Azure クイックスタート テンプレートに関するページを参照してください。For the full script, see the Azure quickstart template in GitHub.

Azure Automation State Configuration (DSC) サービスに登録するための情報Information for registering with Azure Automation State Configuration (DSC) service

DSC 拡張機能を使用してノードを State Configuration サービスに登録する場合、3 つの値を指定する必要があります。When using the DSC Extension to register a node with the State Configuration service, three values will need to be provided.

  • RegistrationUrl - Azure Automation アカウントの https アドレスRegistrationUrl - the https address of the Azure Automation account
  • RegistrationKey - ノードをサービスに登録するために使用される共有シークレットRegistrationKey - a shared secret used to register nodes with the service
  • NodeConfigurationName - サーバー ロールを構成するためにサービスからプルするノード構成 (MOF) の名前NodeConfigurationName - the name of the Node Configuration (MOF) to pull from the service to configure the server role

この情報は Azure portal で表示できますが、PowerShell を使用することもできます。This information can be seen in the Azure portal or you can use PowerShell.

(Get-AzAutomationRegistrationInfo -ResourceGroupName <resourcegroupname> -AutomationAccountName <accountname>).Endpoint
(Get-AzAutomationRegistrationInfo -ResourceGroupName <resourcegroupname> -AutomationAccountName <accountname>).PrimaryKey

[ノード構成名] から、Azure State Configuration にノード構成が存在することを確認します。For the Node Configuration name, make sure the node configuration exists in Azure State Configuration. 存在しない場合、拡張機能のデプロイはエラーを返します。If it does not, the extension deployment will return a failure. また、構成ではなく、必ず "ノード構成" の名前を使用していることを確認してください。Also make sure you are using the name of the Node Configuration and not the Configuration. 構成は、ノード構成 (MOF ファイル) をコンパイルする ために使用されるスクリプトに定義されています。A Configuration is defined in a script that is used to compile the Node Configuration (MOF file). 名前は常に、Configuration の後にピリオド .localhost または特定のコンピューター名が続いたものになります。The name will always be the Configuration followed by a period . and either localhost or a specific computer name.

Resource Manager テンプレートの DSC 拡張機能DSC extension in Resource Manager templates

ほとんどのシナリオでは、DSC 拡張機能を使用する場合に Resource Manager デプロイ テンプレートを利用します。In most scenarios, Resource Manager deployment templates are the expected way to work with the DSC extension. Resource Manager デプロイ テンプレートに DSC 拡張機能を含める方法の詳細と例については、Azure Resource Manager テンプレートを使用した Desired State Configuration 拡張機能に関するページを参照してください。For more information and for examples of how to include the DSC extension in Resource Manager deployment templates, see Desired State Configuration extension with Azure Resource Manager templates.

DSC 拡張機能用 PowerShell コマンドレットDSC extension PowerShell cmdlets

対話型のトラブルシューティングや情報収集のシナリオには、DSC 拡張機能を管理するために使用される PowerShell コマンドレットが最適です。The PowerShell cmdlets that are used to manage the DSC extension are best used in interactive troubleshooting and information-gathering scenarios. このコマンドレットを使用すると、DSC 拡張機能のデプロイをパッケージ化、発行、監視できます。You can use the cmdlets to package, publish, and monitor DSC extension deployments. DSC 拡張機能用のコマンドレットは、既定の構成スクリプトで動作するようにはまだ更新されていません。Cmdlets for the DSC extension aren't yet updated to work with the default configuration script.

Publish-AzVMDscConfiguration コマンドレットは構成ファイルを取り込み、構成ファイルをスキャンして依存 DSC リソースを探し、.zip ファイルを作成します。The Publish-AzVMDscConfiguration cmdlet takes in a configuration file, scans it for dependent DSC resources, and then creates a .zip file. .zip ファイルには、構成と、構成を適用するために必要な DSC リソースが含まれています。The .zip file contains the configuration and DSC resources that are needed to enact the configuration. コマンドレットは -OutputArchivePath パラメーターを使用してローカルでパッケージを作成することもできます。The cmdlet can also create the package locally by using the -OutputArchivePath parameter. それ以外の場合は、コマンドレットは Blob Storage に .zip ファイルを発行し、SAS トークンを使用して保護します。Otherwise, the cmdlet publishes the .zip file to blob storage, and then secures it with an SAS token.

このコマンドレットによって作成された .ps1 構成スクリプトは、アーカイブ フォルダーのルートの .zip ファイル内にあります。The .ps1 configuration script that the cmdlet creates is in the .zip file at the root of the archive folder. モジュール フォルダーは、リソースのアーカイブ フォルダーに配置されます。The module folder is placed in the archive folder in resources.

Set-AzVMDscExtension コマンドレットは、PowerShell DSC 拡張機能が必要とする設定を VM 構成オブジェクトに挿入します。The Set-AzVMDscExtension cmdlet injects the settings that the PowerShell DSC extension requires into a VM configuration object.

Get-AzVMDscExtension コマンドレットは、特定の VM の DSC 拡張機能の状態を取得します。The Get-AzVMDscExtension cmdlet retrieves the DSC extension status of a specific VM.

Get-AzVMDscExtensionStatus コマンドレットは、DSC 拡張機能ハンドラーによって適用された DSC 構成の状態を取得します。The Get-AzVMDscExtensionStatus cmdlet retrieves the status of the DSC configuration that's enacted by the DSC extension handler. この処理は、単一の VM または VM のグループに対して実行できます。This action can be performed on a single VM or on a group of VMs.

Remove-AzVMDscExtension コマンドレットは、特定の VM から拡張機能ハンドラーを削除します。The Remove-AzVMDscExtension cmdlet removes the extension handler from a specific VM. このコマンドレットによって、構成の削除、WMF のアンインストール、または VM に適用されている設定の変更が 行われることはありませんThis cmdlet does not remove the configuration, uninstall WMF, or change the applied settings on the VM. 拡張機能ハンドラーが削除されるだけです。It only removes the extension handler.

Resource Manager DSC 拡張機能コマンドレットに関する重要な情報:Important information about Resource Manager DSC extension cmdlets:

  • Azure Resource Manager コマンドレットは動機的です。Azure Resource Manager cmdlets are synchronous.
  • ResourceGroupNameVMNameArchiveStorageAccountNameVersion、および Location パラメーターはすべて必須です。The ResourceGroupName, VMName, ArchiveStorageAccountName, Version, and Location parameters are all required.
  • ArchiveResourceGroupName は省略可能なパラメーターです。ArchiveResourceGroupName is an optional parameter. このパラメーターを指定できるのは、VM が作成されたリソース グループとは別のリソース グループにストレージ アカウントが属している場合です。You can specify this parameter when your storage account belongs to a different resource group than the one where the VM is created.
  • AutoUpdate スイッチを使用すると、最新バージョンが利用可能になったときに、拡張機能ハンドラーが自動的に更新されるようにできます。Use the AutoUpdate switch to automatically update the extension handler to the latest version when it's available. WMF の新しいバージョンがリリースされると、このパラメーターによって VM で再起動が生じる可能性があります。This parameter has the potential to cause restarts on the VM when a new version of WMF is released.

コマンドレットの概要Get started with cmdlets

Azure DSC 拡張機能は DSC 構成ドキュメントを使用して、デプロイ時に Azure VM を直接構成することができます。The Azure DSC extension can use DSC configuration documents to directly configure Azure VMs during deployment. この手順ではノードが Automation に登録されません。This step doesn't register the node to Automation. ノードは一元管理 されませんThe node is not centrally managed.

単純な構成の例を次に示します。The following example shows a simple example of a configuration. 構成を iisInstall.ps1 としてローカルに保存します。Save the configuration locally as iisInstall.ps1.

configuration IISInstall
{
    node "localhost"
    {
        WindowsFeature IIS
        {
            Ensure = "Present"
            Name = "Web-Server"
        }
    }
}

次のコマンドは、指定した VM に iisInstall.ps1 スクリプトを配置します。The following commands place the iisInstall.ps1 script on the specified VM. さらにコマンドは構成を実行し、状態を報告します。The commands also execute the configuration, and then report back on status.

$resourceGroup = 'dscVmDemo'
$vmName = 'myVM'
$storageName = 'demostorage'
#Publish the configuration script to user storage
Publish-AzVMDscConfiguration -ConfigurationPath .\iisInstall.ps1 -ResourceGroupName $resourceGroup -StorageAccountName $storageName -force
#Set the VM to run the DSC configuration
Set-AzVMDscExtension -Version '2.76' -ResourceGroupName $resourceGroup -VMName $vmName -ArchiveStorageAccountName $storageName -ArchiveBlobName 'iisInstall.ps1.zip' -AutoUpdate -ConfigurationName 'IISInstall'

Azure CLI でのデプロイAzure CLI deployment

Azure CLI を使用して、DSC 拡張機能を既存の仮想マシンにデプロイすることができます。The Azure CLI can be used to deploy the DSC extension to an existing virtual machine.

Windows を実行する仮想マシンの場合:For a virtual machine running Windows:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name Microsoft.Powershell.DSC \
  --publisher Microsoft.Powershell \
  --version 2.77 --protected-settings '{}' \
  --settings '{}'

Linux を実行する仮想マシンの場合:For a virtual machine running Linux:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name DSCForLinux \
  --publisher Microsoft.OSTCExtensions \
  --version 2.7 --protected-settings '{}' \
  --settings '{}'

Azure ポータルの機能Azure portal functionality

ポータルで DSC を設定するには、以下を実行します。To set up DSC in the portal:

  1. VM に移動します。Go to a VM.
  2. [設定][拡張機能] を選択します。Under Settings, select Extensions.
  3. 作成される新しいページで、 [+ 追加] を選択し、 [PowerShell Desired State Configuration] を選びます。In the new page that's created, select + Add, and then select PowerShell Desired State Configuration.
  4. 拡張機能の情報ページの下部にある [作成] をクリックします。Click Create at the bottom of the extension information page.

このポータルでは次の入力を収集します。The portal collects the following input:

  • [Configuration Modules or Script](構成モジュールまたはスクリプト) :このフィールドは必須です (フォームは 既定の構成スクリプト用に更新されていません)。Configuration Modules or Script: This field is mandatory (the form has not been updated for the default configuration script). 構成モジュールおよびスクリプトは、構成スクリプトを含む .ps1 ファイルまたは .ps1 構成スクリプトがルートにある .zip ファイルが必要です。Configuration modules and scripts require a .ps1 file that has a configuration script or a .zip file with a .ps1 configuration script at the root. .zip ファイルを使用する場合は、すべての依存リソースを .zip 内のモジュール フォルダーに含める必要があります。If you use a .zip file, all dependent resources must be included in module folders in the .zip. Azure PowerShell SDK に含まれているコマンドレット Publish-AzureVMDscConfiguration -OutputArchivePath を使用して、.zip ファイルを作成することができます。You can create the .zip file by using the Publish-AzureVMDscConfiguration -OutputArchivePath cmdlet that's included in the Azure PowerShell SDK. .zip ファイルはユーザーの Blob Storage にアップロードされ、SAS トークンによってセキュリティで保護されます。The .zip file is uploaded to your user blob storage and secured by an SAS token.

  • [Module-qualified Name of Configuration](モジュールで修飾された構成の名前) :.ps1 ファイルに複数の構成関数を含めることができます。Module-qualified Name of Configuration: You can include multiple configuration functions in a .ps1 file. .ps1 構成スクリプトの名前に続けて \ と構成関数の名前を入力します。Enter the name of the configuration .ps1 script followed by \ and the name of the configuration function. たとえば、.ps1 スクリプトの名前が configuration.ps1 であり、構成が IisInstall であれば、configuration.ps1\IisInstall と入力します。For example, if your .ps1 script has the name configuration.ps1 and the configuration is IisInstall, enter configuration.ps1\IisInstall.

  • [Configuration Arguments](構成の引数) :構成関数が引数を受け取る場合は、argumentName1=value1,argumentName2=value2 という形式でここに入力します。Configuration Arguments: If the configuration function takes arguments, enter them here in the format argumentName1=value1,argumentName2=value2. この形式は、PowerShell コマンドレットまたは Resource Manager テンプレートで構成引数を受け取る方法とは異なる形式であることに注意してください。This format is a different format in which configuration arguments are accepted in PowerShell cmdlets or Resource Manager templates.

  • [Configuration Data PSD1 File](構成データの PSD1 ファイル) :構成に .psd1 の構成データ ファイルが必要な場合、このフィールドを使用してデータ ファイルを選択し、ユーザーの BLOB ストレージにアップロードします。Configuration Data PSD1 File: If your configuration requires a configuration data file in .psd1, use this field to select the data file and upload it to your user blob storage. 構成データ ファイルは、Blob Storage 内の SAS トークンによってセキュリティで保護されます。The configuration data file is secured by an SAS token in blob storage.

  • [WMF Version](WMF のバージョン) :VM にインストールする Windows Management Framework (WMF) のバージョンを指定します。WMF Version: Specifies the version of Windows Management Framework (WMF) that should be installed on your VM. このプロパティを latest に設定すると、WMF の最新バージョンがインストールされます。Setting this property to latest installs the most recent version of WMF. 現在、このプロパティに設定できる値は、4.0、5.0、5.1、latest のみです。Currently, the only possible values for this property are 4.0, 5.0, 5.1, and latest. これらの設定できる値は更新される可能性があります。These possible values are subject to updates. 既定値は latest です。The default value is latest.

  • [Data Collection](データ収集) :拡張機能でテレメトリを収集するかどうかを決定します。Data Collection: Determines if the extension will collect telemetry. 詳しくは、「Azure DSC extension data collection (Azure DSC 拡張機能のデータ収集)」をご覧ください。For more information, see Azure DSC extension data collection.

  • バージョン:インストールする DSC 拡張機能のバージョンを指定します。Version: Specifies the version of the DSC extension to install. バージョンの詳細については、DSC 拡張機能のバージョン履歴に関するページを参照してください。For information about versions, see DSC extension version history.

  • [自動アップグレードのマイナー バージョン] :このフィールドは、コマンドレットの AutoUpdate スイッチにマップされ、インストール時に拡張機能を最新バージョンに自動的に更新できます。Auto Upgrade Minor Version: This field maps to the AutoUpdate switch in the cmdlets and enables the extension to automatically update to the latest version during installation. [はい] の場合、利用可能な最新バージョンを使用するように拡張機能ハンドラーに指示します。 [いいえ] の場合は、指定された バージョン が強制的にインストールされます。Yes will instruct the extension handler to use the latest available version and No will force the Version specified to be installed. [はい][いいえ] のいずれも選択しないことは、 [いいえ] を選択することと同じです。Selecting neither Yes nor No is the same as selecting No.

ログLogs

拡張機能のログは、次の場所に格納されます。C:\WindowsAzure\Logs\Plugins\Microsoft.Powershell.DSC\<version number>Logs for the extension are stored in the following location: C:\WindowsAzure\Logs\Plugins\Microsoft.Powershell.DSC\<version number>

次のステップNext steps