Compilar configurações DSC na State Configuration da Automação do Azure

Observação

O State Configuration da Automação do Azure será desativado em 30 de setembro de 2027, faça a transição para a Configuração de Máquina do Azure até essa data. Para saber mais, confira a postagem no blog sobre o anúncio. O serviço de Configuração de Máquina do Azure combina recursos da Extensão DSC, da Configuração de Estado da Automação do Azure e dos recursos mais solicitados por meio de comentários dos clientes. A Configuração de Máquinas do Azure também inclui suporte a máquina híbrida por meio servidores habilitados para Arc.

Cuidado

O DSC de Automação do Azure para Linux foi desativado em 30 de setembro de 2023. Para obter mais informações, confira o comunicado.

Você pode compilar as configurações DSC (Desired State Configuration) na State Configuration da Automação do Azure das seguintes maneiras:

• Serviço de compilação de State Configuration do Azure

  • Método para iniciantes com interface do usuário interativa
  • Acompanhar facilmente o estado do trabalho

• Windows PowerShell

  • Chamada do Windows PowerShell no serviço de build ou estação de trabalho local
  • Integrar com pipeline de teste de desenvolvimento
  • Fornece valores de parâmetro complexos
  • Trabalhar com elementos de nó e não nó em escala
  • Aprimoramento significativo do desempenho

Você também pode usar modelos de Azure Resource Manager com a extensão de DSC (Desired State Configuration) do Azure para enviar configurações por push para suas VMs do Azure. A extensão de DSC do Azure usa a estrutura do Agente de VM do Azure para entregar, aplicar e gerar relatórios sobre configurações da DSC executadas em VMs do Azure. Para obter detalhes de build usando modelos de Azure Resource Manager, confira Extensão de Desired State Configuration com modelos do Azure Resource Manager.

Compilar uma configuração DSC na State Configuration do Azure

Portal

1. Em sua conta de Automação, selecione DSC (State Configuration).
2. Clique na guia Configurações e, em seguida, selecione o nome da configuração para compilar.
3. Selecione Compilar.
4. Se a configuração não tiver parâmetros, você será solicitado a confirmar se deseja compilá-la. Se a configuração tiver parâmetros, o painel Compilar Configuração será aberto para que você possa fornecer os valores de parâmetro.
5. A página Trabalho de Compilação é aberta para que você possa acompanhar o status do trabalho de compilação. Você também pode usar essa página para controlar as configurações de nó (documentos de configuração do MOF) colocadas no servidor de pull da State Configuration da Automação do Azure.

PowerShell do Azure

Você pode usar Start-AzAutomationDscCompilationJob para iniciar a compilação com o Windows PowerShell. O código de exemplo a seguir inicia a compilação de uma configuração DSC chamada SampleConfig.

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

Start-AzAutomationDscCompilationJob retorna um objeto de trabalho de compilação que você pode usar para acompanhar o status desse trabalho. Você pode usar esse objeto de trabalho de compilação com Get-AzAutomationDscCompilationJob para determinar o status do trabalho de compilação e Get-AzAutomationDscCompilationJobOutput para exibir as transmissões dele (saída). O exemplo a seguir inicia a compilação da configuração SampleConfig, aguarda até a conclusão dela e exibe os respectivos fluxos.

$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

Declarar parâmetros básicos

A declaração de parâmetro nas configurações DSC, incluindo tipos de parâmetros e propriedades, funciona da mesma maneira que os runbooks da Automação do Azure. Para saber mais sobre os parâmetros de runbook, confira Iniciando um runbook na Automação do Azure.

O exemplo a seguir usa os parâmetros FeatureName e IsPresent para determinar os valores das propriedades na configuração de nó ParametersExample.sample gerada durante a compilação.

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

É possível compilar as configurações DSC que usam parâmetros básicos no portal de State Configuration da Automação do Azure ou com o Azure PowerShell.

Portal

No portal, é possível inserir valores de parâmetro depois de clicar em Compilar.

PowerShell do Azure

O PowerShell requer parâmetros em uma tabela de hash em que a chave corresponda ao nome do parâmetro e o valor seja igual ao valor do parâmetro.

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

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

Para obter informações sobre como transmitir objetos PSCredential como parâmetros, confira Ativos de credencial.

Compilar configurações que contêm recursos de composição na Automação do Azure

O recurso Recursos de Composição permitem que você use as configurações DSC como recursos aninhados dentro de uma configuração. Esse recurso permite que a aplicação de várias configurações a um recurso. Consulte recursos de composição: utilizando uma configuração DSC como um recurso para saber mais sobre recursos de composição.

Observação

Para que as configurações que contêm recursos de composição sejam compiladas corretamente, você deve primeiro importar para a Automação do Azure os recursos de DSC dos quais as composições dependem. Adicionar um recurso de composição de DSC não é diferente de adicionar qualquer módulo do PowerShell à Automação do Azure. Esse processo está documentado em Gerenciar módulos na Automação do Azure.

Gerenciar ConfigurationData ao compilar configurações na Automação do Azure

ConfigurationData é um parâmetro DSC interno permite que você separe a configuração estrutural de qualquer configuração específica a um ambiente, usando simultaneamente a DSC do PowerShell. Para obter mais informações, confira Separando "o que" de "onde" na DSC do PowerShell.

Observação

Ao compilar no State Configuration da Automação do Azure, é possível usar ConfigurationData no Azure PowerShell, mas não no portal do Azure.

A configuração DSC de exemplo a seguir usa ConfigurationData por meio das palavras-chave $ConfigurationData e $AllNodes. O módulo xWebAdministration também é necessário para este exemplo.

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'
        }
    }
}

Você pode compilar a configuração da DSC acima com o Windows PowerShell. O script a seguir adiciona duas configurações de nó ao serviço de pull da Configuração do Estado de Automação do Azure: ConfigurationDataSample.MyVM1 e 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

Trabalhar com ativos na Automação do Azure durante a compilação

As referências de ativos são as mesmas na State Configuration da Automação do Azure e nos runbooks. Para obter mais informações, consulte os seguintes artigos:

• Certificados
• Conexões
• Credenciais
• Variáveis

Ativos de credencial

Se uma configuração tem um parâmetro que especifica um objeto PSCredential, use Get-AutomationPSCredential passando o nome de um ativo de credencial de Automação do Azure para o cmdlet para recuperar a credencial. A Automação do Azure passa a credencial para a configuração.

Para manter as credenciais seguras em configurações de nó, criptografe as credenciais no arquivo MOF de configuração do nó. Você precisa conceder permissão de DSC do PowerShell para gerar credenciais em texto sem formatação durante a geração de MOF de configuração de nó. O DSC do PowerShell não reconhece que a Automação do Azure criptografa todo o arquivo MOF após ele ser gerado por meio de um trabalho de compilação.

Você pode informar à DSC do PowerShell que não há problema nas credenciais serem exportadas em texto sem formatação nos MOFs gerados da configuração de nó usando ConfigurationData. Você deve transmitir PSDscAllowPlainTextPassword = $true por meio de ConfigurationData para o nome do bloco de cada nó que aparece na configuração DSC e que usa credenciais.

O exemplo a seguir mostra uma configuração DSC que usa um ativo de credencial da Automação.

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

Você pode compilar a configuração da DSC acima com o PowerShell. O código do PowerShell abaixo adiciona duas configurações de nó ao servidor de pull da Configuração do Estado de Automação do Azure: CredentialSample.MyVM1 e CredentialSample.MyVM2.

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

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

Observação

Quando a compilação for concluída, você poderá receber a mensagem de erro The 'Microsoft.PowerShell.Management' module was not imported because the 'Microsoft.PowerShell.Management' snap-in was already imported. Você pode ignorar essa mensagem com segurança.

Compilar uma configuração DSC com o Windows PowerShell

O processo para compilar configurações DSC no Windows PowerShell está incluído na documentação do DSC do PowerShell Gravar, compilar e aplicar uma configuração. Você pode executar esse processo em uma estação de trabalho de desenvolvedor ou em um serviço de build, como o Azure DevOps. Em seguida, você pode importar os arquivos MOF produzidos compilando a configuração no serviço State Configuration do Azure.

A compilação no Windows PowerShell também fornece a opção de assinar o conteúdo de configuração. O agente DSC verifica uma configuração de nó assinada localmente em um nó gerenciado. A verificação garante que a configuração aplicada ao nó seja proveniente de uma fonte autorizada.

Você também pode importar configurações de nó que você compilou fora do Azure. A importação inclui a compilação de uma estação de trabalho de desenvolvedor ou em um serviço como o Azure DevOps. Essa abordagem tem várias vantagens, incluindo desempenho e confiabilidade.

Observação

Um arquivo de configuração de nó não pode ultrapassar 1 MB para que possa ser importado pela Automação do Azure.

Para obter mais informações sobre como assinar configurações de nó, confira Aprimoramentos no WMF 5.1 – Como assinar a configuração e o módulo.

Importar uma configuração de nó no portal do Azure

1. Na conta de Automação, selecione DSC (Desired State Configuration) em Gerenciamento de Configuração.

2. Na página DSC (State Configuration), selecione a guia Configurações e, em seguida, selecione Adicionar.

3. Na página Importar, selecione o ícone de pasta ao lado do campo Arquivo de Configuração de Nó para procurar um arquivo MOF de configuração de nó no computador local.

   

4. Insira um nome no campo Nome da Configuração. Esse nome deve corresponder ao nome da configuração a partir da qual a configuração de nó foi compilada.

5. Selecione OK.

Importar uma configuração de nó com o Azure PowerShell

Use o cmdlet Import-AzAutomationDscNodeConfiguration para importar uma configuração de nó para a conta de Automação.

$importAzAutomationDscNodeConfigurationSplat = @{
    AutomationAccountName = 'MyAutomationAccount'
    ResourceGroupName = 'MyResourceGroup'
    ConfigurationName = 'MyNodeConfiguration'
    Path = 'C:\MyConfigurations\TestVM1.mof'
}
Import-AzAutomationDscNodeConfiguration @importAzAutomationDscNodeConfigurationSplat

Próximas etapas

• Para começar, veja Introdução ao serviço State Configuration da Automação do Azure.
• Para saber como compilar configurações DSC para que possam ser atribuídas a nós de destino, confira Compilar configurações DSC no State Configuration da Automação do Azure.
• Para obter uma referência de cmdlet do PowerShell, confira Az.Automation.
• Para obter informações sobre preços, veja Preços do serviço State Configuration da Automação do Azure.
• Para ver um exemplo de uso do State Configuration em um pipeline de implantação contínua, confira Configurar a implantação contínua com o Chocolatey.