在 Azure Automation State Configuration 中编译 DSC 配置Compile DSC configurations in Azure Automation State Configuration

可通过以下方法在 Azure Automation State Configuration 中编译 Desired State Configuration (DSC) 配置:You can compile Desired State Configuration (DSC) configurations in Azure Automation State Configuration in the following ways:

  • Azure State Configuration 编译服务Azure State Configuration compilation service

    • 使用交互式用户界面的入门方法Beginner method with interactive user interface
    • 轻松跟踪作业状态Easily track job state
  • Windows PowerShellWindows PowerShell

    • 从本地工作站或生成服务上的 Windows PowerShell 调用Call from Windows PowerShell on local workstation or build service
    • 与开发测试管道集成Integrate with development test pipeline
    • 提供复杂的参数值Provide complex parameter values
    • 大规模使用节点和非节点数据Work with node and non-node data at scale
    • 性能显著提高Significant performance improvement

还可以将 Azure 资源管理器模板与 Azure Desired State Configuration (DSC) 扩展结合使用,将配置推送到 Azure VM。You can also use Azure Resource Manager templates with Azure Desired State Configuration (DSC) extension to push configurations to your Azure VMs. 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. 有关使用 Azure 资源管理器模板的编译详细信息,请参阅 Desired State Configuration 扩展与 Azure 资源管理器模板For compilation details using Azure Resource Manager templates, see Desired State Configuration extension with Azure Resource Manager templates.

在 Azure State Configuration 中编译 DSC 配置Compile a DSC configuration in Azure State Configuration

门户Portal

  1. 在“自动化帐户”中,单击“State Configuration (DSC)”。In your Automation account, click State configuration (DSC).
  2. 单击“配置”选项卡,然后单击要编译的配置名称。Click on the Configurations tab, then click on the configuration name to compile.
  3. 单击“编译”。Click Compile.
  4. 如果该配置没有参数,系统会提示你确认是否要进行编译。If the configuration has no parameters, you're prompted to confirm if you want to compile it. 如果该配置有参数,则会打开“编译配置”边栏选项卡让用户提供参数值。If the configuration has parameters, the Compile Configuration blade opens so that you can provide parameter values.
  5. 将打开“编译作业”页,以便你跟踪编译作业状态。The Compilation Job page is opened so that you can track compilation job status. 还可以使用此页跟踪放置在 Azure Automation State Configuration 拉取服务器上的节点配置(MOF 配置文档)。You can also use this page to track the node configurations (MOF configuration documents) placed on the Azure Automation State Configuration pull server.

Azure PowerShellAzure PowerShell

可以在 Windows PowerShell 中使用 Start-AzAutomationDscCompilationJob 开始编译。You can use Start-AzAutomationDscCompilationJob to start compiling with Windows PowerShell. 以下示例代码将启动名为 SampleConfig 的 DSC 配置编译。The following sample code begins compilation of a DSC configuration called SampleConfig.

Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'SampleConfig'

Start-AzAutomationDscCompilationJob 返回可用于跟踪作业状态的编译作业对象。Start-AzAutomationDscCompilationJob returns a compilation job object that you can use to track job status. 然后,可以将此编译作业对象与 Get-AzAutomationDscCompilationJob 一起使用来确定编译作业的状态,与 Get-AzAutomationDscCompilationJobOutput 一起使用来查看其流(输出)。You can then use this compilation job object with Get-AzAutomationDscCompilationJob to determine the status of the compilation job, and Get-AzAutomationDscCompilationJobOutput to view its streams (output). 以下示例将启动 SampleConfig 配置的编译,并在编译完成后显示其流。The following sample starts compilation of the SampleConfig configuration, waits until it has completed, and then displays its streams.

$CompilationJob = Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'SampleConfig'

while($null -eq $CompilationJob.EndTime -and $null -eq $CompilationJob.Exception)
{
    $CompilationJob = $CompilationJob | Get-AzAutomationDscCompilationJob
    Start-Sleep -Seconds 3
}

$CompilationJob | Get-AzAutomationDscCompilationJobOutput –Stream Any

声明基本参数Declare basic parameters

DSC 配置中的参数声明(包括参数类型和属性)的工作方式与 Azure 自动化 Runbook 中相同。Parameter declaration in DSC configurations, including parameter types and properties, works the same as in Azure Automation runbooks. 若要了解有关 Runbook 参数的详细信息,请参阅 Starting a runbook in Azure Automation(在 Azure 自动化中启动 Runbook)。See Starting a runbook in Azure Automation to learn more about runbook parameters.

以下示例使用 FeatureNameIsPresent 参数来确定编译期间在 ParametersExample.sample 节点配置中生成的属性值。The following example uses FeatureName and IsPresent parameters to determine the values of properties in the ParametersExample.sample node configuration, generated during compilation.

Configuration ParametersExample
{
    param(
        [Parameter(Mandatory=$true)]
        [string] $FeatureName,

        [Parameter(Mandatory=$true)]
        [boolean] $IsPresent
    )

    $EnsureString = 'Present'
    if($IsPresent -eq $false)
    {
        $EnsureString = 'Absent'
    }

    Node 'sample'
    {
        WindowsFeature ($FeatureName + 'Feature')
        {
            Ensure = $EnsureString
            Name   = $FeatureName
        }
    }
}

可以在 Azure Automation State Configuration 门户或 Azure PowerShell 中编译使用基本参数的 DSC 配置。You can compile DSC configurations that use basic parameters in the Azure Automation State Configuration portal or with Azure PowerShell.

门户Portal

在门户中,可在单击“编译”后输入参数值。In the portal, you can enter parameter values after clicking Compile.

配置编译参数

Azure PowerShellAzure PowerShell

PowerShell 需要哈希表中的参数,其中的键必须与参数名称匹配,值等于参数值。PowerShell requires parameters in a hashtable, where the key matches the parameter name and the value equals the parameter value.

$Parameters = @{
    'FeatureName' = 'Web-Server'
    'IsPresent' = $False
}

Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'ParametersExample' -Parameters $Parameters

若要了解如何将 PSCredential 对象作为参数传递,请参阅凭据资产For information about passing PSCredential objects as parameters, see Credential assets.

在 Azure 自动化中编译包含复合资源的配置Compile configurations containing composite resources in Azure Automation

借助复合资源功能,可将 DSC 配置用作某个配置中的嵌套资源。The Composite Resources feature allows you to use DSC configurations as nested resources inside a configuration. 使用此功能可以将多个配置应用于单个资源。This feature enables the application of multiple configurations to a single resource. 请参阅复合资源:将 DSC 配置用作资源,了解有关复合资源的详细信息。See Composite resources: Using a DSC configuration as a resource to learn more about composite resources.

备注

为了正确编译包含复合资源的配置,必须先将复合所依赖的任何 DSC 资源导入到 Azure 自动化中。So that configurations containing composite resources compile correctly, you must first import into Azure Automation any DSC resources that the composites rely upon. 添加 DSC 复合资源与将任何 PowerShell 模块添加到 Azure 自动化无差异。Adding a DSC composite resource is no different from adding any PowerShell module to Azure Automation. 管理 Azure 自动化中的模块一文中介绍了此过程。This process is documented in Manage Modules in Azure Automation.

在 Azure 自动化中编译配置的同时管理 ConfigurationDataManage ConfigurationData when compiling configurations in Azure Automation

ConfigurationData 是一个内置的 DSC 参数,可使你在使用 PowerShell DSC 时将结构化配置与任何环境特定配置分开。ConfigurationData is a built-in DSC parameter that allows you to separate structural configuration from any environment-specific configuration while using PowerShell DSC. 有关详细信息,请参阅区分 PowerShell DSC 中的“What”与“Where”For more information, see Separating "What" from "Where" in PowerShell DSC.

备注

在 Azure Automation State Configuration 中进行编译时,可以在 Azure PowerShell 中使用 ConfigurationData,但在 Azure 门户中却不行。When compiling in Azure Automation State Configuration, you can use ConfigurationData in Azure PowerShell but not in the Azure portal.

以下示例 DSC 配置通过 $ConfigurationData$AllNodes 关键字来使用 ConfigurationDataThe following example DSC configuration uses ConfigurationData via the $ConfigurationData and $AllNodes keywords. 在本示例中还需要 xWebAdministration 模块You also need the xWebAdministration module for this example.

Configuration ConfigurationDataSample
{
    Import-DscResource -ModuleName xWebAdministration -Name MSFT_xWebsite

    Write-Verbose $ConfigurationData.NonNodeData.SomeMessage

    Node $AllNodes.Where{$_.Role -eq 'WebServer'}.NodeName
    {
        xWebsite Site
        {
            Name         = $Node.SiteName
            PhysicalPath = $Node.SiteContents
            Ensure       = 'Present'
        }
    }
}

可以使用 Windows PowerShell 编译上述 DSC 配置。You can compile the preceding DSC configuration with Windows PowerShell. 以下脚本将两个节点配置添加到 Azure Automation State Configuration 拉取服务:ConfigurationDataSample.MyVM1 和 ConfigurationDataSample.MyVM3。The following script adds two node configurations to the Azure Automation State Configuration pull service: ConfigurationDataSample.MyVM1 and ConfigurationDataSample.MyVM3.

$ConfigData = @{
    AllNodes = @(
        @{
            NodeName = 'MyVM1'
            Role = 'WebServer'
        },
        @{
            NodeName = 'MyVM2'
            Role = 'SQLServer'
        },
        @{
            NodeName = 'MyVM3'
            Role = 'WebServer'
        }
    )

    NonNodeData = @{
        SomeMessage = 'I love Azure Automation State Configuration and DSC!'
    }
}

Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'ConfigurationDataSample' -ConfigurationData $ConfigData

在编译期间使用 Azure 自动化中的资产Work with assets in Azure Automation during compilation

Azure Automation State Configuration 和 Runbook 中的资产引用是相同的。Asset references are the same in both Azure Automation State Configuration and runbooks. 有关详细信息,请参阅以下主题:For more information, see the following:

凭据资产Credential assets

Azure 自动化中的 DSC 配置可以使用 Get-AutomationPSCredential cmdlet 引用自动化凭据资产。DSC configurations in Azure Automation can reference Automation credential assets using the Get-AutomationPSCredential cmdlet. 如果配置具有用于指定 PSCredential 对象的参数,则可以通过将 Azure 自动化凭据资产的字符串名称传递给 cmdlet 来检索凭据,从而使用 Get-AutomationPSCredentialIf a configuration has a parameter that specifies a PSCredential object, use Get-AutomationPSCredential by passing the string name of an Azure Automation credential asset to the cmdlet to retrieve the credential. 然后将该对象用于需要 PSCredential 对象的参数。Then make use of that object for the parameter requiring the PSCredential object. 在后台将检索具有该名称的 Azure 自动化凭据资产并将其传递给配置。Behind the scenes, the Azure Automation credential asset with that name is retrieved and passed to the configuration. 以下示例演示了此方案的实际应用。The example below shows this scenario in action.

要在节点配置(MOF 配置文档)中保持凭据的安全,需要在节点配置 MOF 文件中为凭据加密。Keeping credentials secure in node configurations (MOF configuration documents) requires encrypting the credentials in the node configuration MOF file. 目前,必须授予 PowerShell DSC 权限以在节点配置 MOF 生成期间以纯文本形式输出凭据。Currently you must give PowerShell DSC permission to output credentials in plain text during node configuration MOF generation. PowerShell DSC 并不知道在通过编译作业生成整个 MOF 文件后,Azure 自动化会对其进行加密。PowerShell DSC is not aware that Azure Automation encrypts the entire MOF file after its generation through a compilation job.

可告知 PowerShell DSC,使用配置数据在生成的节点配置 MOF 中以纯文本形式输出凭据是可行的。You can tell PowerShell DSC that it is okay for credentials to be outputted in plain text in the generated node configuration MOFs using configuration Data. 针对出现在 DSC 配置中且使用凭据的每个节点块名称,应通过 ConfigurationData 传递 PSDscAllowPlainTextPassword = $trueYou should pass PSDscAllowPlainTextPassword = $true via ConfigurationData for each node block name that appears in the DSC configuration and uses credentials.

以下示例演示使用自动化凭据资产的 DSC 配置。The following example shows a DSC configuration that uses an Automation credential asset.

Configuration CredentialSample
{
    Import-DscResource -ModuleName PSDesiredStateConfiguration
    $Cred = Get-AutomationPSCredential 'SomeCredentialAsset'

    Node $AllNodes.NodeName
    {
        File ExampleFile
        {
            SourcePath      = '\\Server\share\path\file.ext'
            DestinationPath = 'C:\destinationPath'
            Credential      = $Cred
        }
    }
}

可以使用 PowerShell 编译上述 DSC 配置。You can compile the preceding DSC configuration with PowerShell. 以下 PowerShell 代码会将两个节点配置添加到 Azure Automation State Configuration 拉取服务器:CredentialSample.MyVM1CredentialSample.MyVM2The following PowerShell code adds two node configurations to the Azure Automation State Configuration pull server: CredentialSample.MyVM1 and CredentialSample.MyVM2.

$ConfigData = @{
    AllNodes = @(
        @{
            NodeName = '*'
            PSDscAllowPlainTextPassword = $True
        },
        @{
            NodeName = 'MyVM1'
        },
        @{
            NodeName = 'MyVM2'
        }
    )
}

Start-AzAutomationDscCompilationJob -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'MyAutomationAccount' -ConfigurationName 'CredentialSample' -ConfigurationData $ConfigData

备注

编译完成后,可能会收到错误消息 The 'Microsoft.PowerShell.Management' module was not imported because the 'Microsoft.PowerShell.Management' snap-in was already imported.,你可以放心地忽略此消息。When compilation is complete, you might receive the error message The 'Microsoft.PowerShell.Management' module was not imported because the 'Microsoft.PowerShell.Management' snap-in was already imported. You can safely ignore this message.

在 Windows PowerShell 中编译 DSC 配置Compile your DSC configuration in Windows PowerShell

在 Windows PowerShell 中编译 DSC 配置的过程包含在 PowerShell DSC 文档编写、编译和应用配置中。The process to compile DSC configurations in Windows PowerShell is included in the PowerShell DSC documentation Write, Compile, and Apply a Configuration. 可以从开发人员工作站或在生成服务(例如 Azure DevOps)中执行此过程。You can execute this process from a developer workstation or within a build service, such as Azure DevOps. 然后,可以将通过编译配置生成的 MOF 文件导入到 Azure State Configuration 服务中。You can then import the MOF files produced by compiling the configuration into the Azure State Configuration service.

在 Windows PowerShell 中编译还提供了对配置内容进行签名的选项。Compiling in Windows PowerShell also provides the option to sign configuration content. DSC 代理会在托管节点上对已签名的节点配置进行本地验证。The DSC agent verifies a signed node configuration locally on a managed node. 验证可确保应用于节点的配置来自授权的源。Verification ensures that the configuration applied to the node comes from an authorized source.

还可以导入已在 Azure 外部编译的节点配置(MOF 文件)。You can also import node configurations (MOF files) that have been compiled outside of Azure. 导入包括从开发人员工作站或在服务(如 Azure DevOps)中进行的编译。The import includes compilation from a developer workstation or in a service such as Azure DevOps. 此方法具有多个优势,包括性能和可靠性方面的优势。This approach has multiple advantages, including performance and reliability.

备注

节点配置文件不得大于 1 MB,以便 Azure 自动化将其导入。A node configuration file must be no larger than 1 MB to allow Azure Automation to import it.

若要详细了解如何为节点配置签名,请参阅 WMF 5.1 中的改进 - 如何为配置和模块签名For more information about signing of node configurations, see Improvements in WMF 5.1 - How to sign configuration and module.

在 Azure 门户中导入节点配置Import a node configuration in the Azure portal

  1. 在“自动化帐户”中的“配置管理”下,单击“State Configuration (DSC)”。 In your Automation account, click State configuration (DSC) under Configuration Management.

  2. 在“State Configuration (DSC)”页中,依次单击“配置”选项卡、“添加”。 On the State configuration (DSC) page, click on the Configurations tab, then click Add.

  3. 在“导入”页中,单击“节点配置文件”字段旁边的文件夹图标,浏览到本地计算机上的节点配置 MOF 文件。On the Import page, click the folder icon next to the Node Configuration File field to browse for a node configuration MOF file on your local computer.

    浏览本地文件

  4. 在“配置名称”字段中,输入名称。Enter a name in the Configuration Name field. 此名称必须与编译节点配置的配置名称匹配。This name must match the name of the configuration from which the node configuration was compiled.

  5. 单击“确定”。Click OK.

使用 Azure PowerShell 导入节点配置Import a node configuration with Azure PowerShell

可以使用 Import-AzAutomationDscNodeConfiguration cmdlet 将节点配置导入自动化帐户。You can use the Import-AzAutomationDscNodeConfiguration cmdlet to import a node configuration into your Automation account.

Import-AzAutomationDscNodeConfiguration -AutomationAccountName 'MyAutomationAccount' -ResourceGroupName 'MyResourceGroup' -ConfigurationName 'MyNodeConfiguration' -Path 'C:\MyConfigurations\TestVM1.mof'

后续步骤Next steps