Extensão de DSC do PowerShell

Artigo
10/15/2024

Observação

Antes de você habilitar a extensão de DSC, gostaríamos de informar que uma versão mais recente da DSC agora está em disponibilidade geral, gerenciada por um recurso de Gerenciamento Automatizado do Azure chamado configuração de máquina. O recurso de configuração de máquina combina os recursos do manipulador de extensão de DSC (Desired State Configuration), a State Configuration da Automação do Azure e os recursos mais solicitados nos comentários dos clientes. A configuração de máquina também inclui suporte a computadores híbridos por meio de servidores habilitados para Arc.

Visão geral

A extensão DSC PowerShell para Windows é publicada e recebe suporte da Microsoft. A extensão atualiza e aplica uma configuração de DSC do PowerShell em uma VM do Azure. A extensão de DSC chama a DSC do PowerShell para aplicar a configuração DSC recebida na VM. Este documento detalha as plataformas com opções de plataformas, configurações e implantação com suporte para a extensão da máquina virtual do DSC para Windows.

Pré-requisitos

Sistema operacional

A Extensão DSC suporta os seguintes OS

Windows Server 2022, Windows Server 2019, Windows Server 2016, Windows Server 2012R2, Windows Server 2012, Windows Server 2008 R2 SP1, Windows Client 7/8.1/10

Conectividade com a Internet

A extensão de DSC para Windows requer que a máquina virtual de destino seja capaz de se comunicar com o Azure e o local do pacote de configuração (arquivo. zip) se ele estiver armazenado em um local fora do Azure.

Esquema de extensão

O JSON a seguir mostra o esquema que serve para a parte das configurações da extensão DSC em um modelo do Azure Resource Manager.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "Microsoft.Powershell.DSC",
  "apiVersion": "2018-10-01",
  "location": "<location>",
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "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": {
            "forcePullAndApply": false,
            "downloadMappings": {
             "specificDependencyKey": "https://myCustomDependencyLocation"
            }
        }
    },
    "protectedSettings": {
        "configurationArguments": {
            "parameterOfTypePSCredential1": {
                "userName": "UsernameValue1",
                "password": "PasswordValue1"
            },
            "parameterOfTypePSCredential2": {
                "userName": "UsernameValue2",
                "password": "PasswordValue2"
            }
        },
        "configurationUrlSasToken": "?g!bber1sht0k3n",
        "configurationDataUrlSasToken": "?dataAcC355T0k3N"
    }
  }
}

Valores de propriedade

Nome	Valor/Exemplo	Tipo de Dados
apiVersion	01-10-2018	date
publicador	Microsoft.Powershell.DSC	string
type	DSC	string
typeHandlerVersion	2.77	INT

Valores da Propriedade de Configurações

Nome	Tipo de Dados	Descrição
settings.wmfVersion	string	Especifica a versão do Windows Management Framework que deve ser instalada em sua VM. Configurar essa propriedade como 'latest' instalará a versão mais atualizada do WMF. Os únicos valores possíveis atualmente para essa propriedade são ‘4.0’, ‘5.0’, e a mais recente. Esses valores possíveis estão sujeitos a atualizações. O valor padrão é ‘latest’.
settings.configuration.url	string	Especifica o local da URL de onde baixar o arquivo zip configuração DSC. Se a URL fornecida exigir um token SAS para acesso, será necessário definir a propriedade protectedSettings.configurationUrlSasToken como o valor do token de SAS. Esta propriedade será necessária se settings.configuration.script e/ou settings.configuration.function estiverem definidas.
settings.configuration.script	string	Especifica o nome do arquivo do script que contém a definição de sua configuração DSC. Esse script deve estar na pasta raiz do arquivo zip baixado da URL especificada pela propriedade configuration.url. Esta propriedade é necessária se settings.configuration.url e/ou settings.configuration.script estiverem definidas.
settings.configuration.function	string	Especifica o nome da configuração DSC. A configuração denominada deve estar contida no script definido por configuration.script. Esta propriedade será necessária se settings.configuration.script.url e/ou settings.configuration.function estiverem definidas.
settings.configurationArguments	Coleção	Define os parâmetros que você deseja passar para a configuração de DSC. Esta propriedade não será criptografada.
settings.configurationData.url	string	Especifica a URL de onde baixar o arquivo de dados de configuração (.pds1) para usar como entrada para a sua configuração de DSC. Se a URL fornecida exigir um token SAS para acesso, será necessário definir a propriedade protectedSettings.configurationDataUrlSasToken como o valor do token de SAS.
settings.privacy.dataEnabled	string	Habilita ou desabilita a coleta de telemetria. Os únicos valores possíveis para essa propriedade são ‘Enable’, ‘Disable’, ”, ou $null. Deixar esta propriedade em branco ou nulo permitirá telemetria
settings.advancedOptions.forcePullAndApply	Bool	Essa configuração foi projetada para aprimorar a experiência de trabalhar com a extensão para registrar nós com o DSC de Automação do Azure. Se o valor for `$true`, a extensão aguardará a primeira execução da configuração retirada do serviço antes de retornar êxito/falha. Se o valor for definido como $false, o status retornado pela extensão somente fará referência a se o nó foi registrado com êxito no State Configuration da Automação do Azure e a configuração do nó não será executada durante o registro.
settings.advancedOptions.downloadMappings	Coleção	Define locais alternativos para fazer o download de dependências como WMF e .NET

Valores da Propriedade de Configurações Protegidos

Nome	Tipo de Dados	Descrição
protectedSettings.configurationArguments	string	Define os parâmetros que você deseja passar para a configuração de DSC. Esta propriedade será criptografada.
protectedSettings.configurationUrlSasToken	string	Especifica o token SAS para acessar a URL definida por configuration.url. Esta propriedade será criptografada.
protectedSettings.configurationDataUrlSasToken	string	Especifica o token SAS para acessar a URL definida por configurationData.url. Esta propriedade será criptografada.

Implantação de modelo

Extensões de VM do Azure podem ser implantadas com modelos do Azure Resource Manager. Modelos são ideais ao implantar uma ou mais máquinas virtuais que exigem configuração pós-implantação. Um modelo do Resource Manager de amostra que inclui a extensão DSC para Windows pode ser encontrado na Galeria de Início Rápido do Azure.

Solução de problemas e suporte

Solucionar problemas

Dados sobre o estado das implantações de extensão podem ser recuperados do Portal do Azure usando a CLI do Azure. Para ver o estado da implantação das extensões de uma determinada VM, execute o comando a seguir usando a CLI do Azure.

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

Pacote de extensão é baixado e implantado para esse local na VM do Azure

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}

O arquivo de status de extensão contém os códigos de status de êxito/erro de subsequentes, juntamente com o erro detalhado e a descrição para cada execução de extensão.

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}\Status\{0}.Status  -> {0} being the sequence number

Logs de saída de extensão são registrados no seguinte diretório:

C:\WindowsAzure\Logs\Plugins\{Extension_Name}\{Extension_Version}

Códigos de erro e seus significados

Código do Erro	Significado	Ação possível
1000	Erro genérico	A mensagem de erro é fornecida pela exceção específica em logs de extensão
52	Erro de Instalação da Extensão	A mensagem de erro é fornecida pela exceção específica
1002	Erro de instalação Wmf	Erro ao instalar WMF.
1004	Pacote Zip Inválido	Zip inválido ; Erro ao desempacotar o zip
1100	Erro de Argumento	Indica um problema na entrada fornecida pelo usuário. A mensagem de erro é fornecida pela exceção específica

Suporte

Caso precise de mais ajuda em qualquer ponto deste artigo, entre em contato com os especialistas do Azure nos fóruns do Azure e do Stack Overflow no MSDN. Como alternativa, você pode registrar um incidente de suporte do Azure. Vá para o site de suporte do Azure e selecione Obter suporte. Para saber mais sobre como usar o suporte do Azure, leia as Perguntas frequentes sobre o suporte do Microsoft Azure.

Compartilhar via