Extensão DSC do PowerShell

Artigo
08/25/2024

Nota

Antes de habilitar a extensão DSC, gostaríamos que você soubesse que uma versão mais recente do DSC agora está disponível ao público, gerenciada por um recurso da configuração de máquina nomeada do Azure Automange. O recurso de configuração da máquina combina recursos do manipulador de extensão DSC (Configuração de Estado Desejado), Configuração do Estado de Automação do Azure e os recursos mais comumente solicitados dos comentários dos clientes. A configuração da máquina também inclui suporte a máquinas híbridas através de servidores habilitados para Arc.

Descrição geral

A extensão DSC do PowerShell para Windows é publicada e suportada pela Microsoft. A extensão carrega e aplica uma Configuração DSC do PowerShell em uma VM do Azure. A Extensão DSC chama o DSC do PowerShell para executar a configuração DSC recebida na VM. Este documento detalha as plataformas, configurações e opções de implantação suportadas para a extensão de máquina virtual DSC para Windows.

Pré-requisitos

Sistema operativo

A extensão DSC suporta os seguintes sistemas operacionais

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

Ligação à Internet

A extensão 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 para a parte de 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	2018-10-01	data
editora	Microsoft.Powershell.DSC	string
tipo	DSC	string
typeHandlerVersion	2.77	número inteiro

Valores da propriedade Settings

Name	Tipo de Dados	Description
configurações.wmfVersion	string	Especifica a versão do Windows Management Framework que deve ser instalada em sua VM. Definir esta propriedade como 'mais recente' instalará a versão mais atualizada do WMF. Os únicos valores atuais possíveis para esta propriedade são '4.0', '5.0' e 'mais recente'. Estes valores possíveis estão sujeitos a atualizações. O valor padrão é 'mais recente'.
configurações.configuração.url	string	Especifica o local da URL a partir do qual o arquivo zip de configuração DSC deve ser baixado. Se a URL fornecida exigir um token SAS para acesso, você precisará definir a propriedade protectedSettings.configurationUrlSasToken como o valor do seu token SAS. Esta propriedade é necessária se settings.configuration.script e/ou settings.configuration.function estiverem definidos.
configurações.configuration.script	string	Especifica o nome do arquivo do script que contém a definição da configuração do 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 definidos.
configurações.configuration.function	string	Especifica o nome da configuração do DSC. A configuração nomeada deve estar contida no script definido por configuration.script. Esta propriedade é necessária se settings.configuration.url e/ou settings.configuration.function estiverem definidos.
settings.configurationArgumentos	Coleção	Define todos os parâmetros que você gostaria de passar para sua configuração DSC. Esta propriedade não será encriptada.
configurações.configurationData.url	string	Especifica a URL a partir da qual o arquivo de dados de configuração (.pds1) deve ser usado como entrada para a configuração do DSC. Se a URL fornecida exigir um token SAS para acesso, você precisará definir a propriedade protectedSettings.configurationDataUrlSasToken como o valor do seu token SAS.
settings.privacy.dataEnabled	string	Habilita ou desabilita a coleta de telemetria. Os únicos valores possíveis para esta propriedade são 'Enable', 'Disable', ", ou $null. Deixar essa propriedade em branco ou nula habilitará a telemetria
configurações.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 Azure Automation DSC. Se o valor for `$true`, a extensão aguardará a primeira execução da configuração retirada do serviço antes de retornar sucesso/falha. Se o valor for definido como $false, o status retornado pela extensão se referirá apenas se o nó foi registrado com êxito na Configuração do Estado de Automação do Azure e a configuração do nó não será executada durante o registro.
settings.advancedOptions.downloadMapeamentos	Coleção	Define locais alternativos para baixar dependências, como WMF e .NET

Valores da propriedade Configurações Protegidas

Name	Tipo de Dados	Description
protectedSettings.configurationArguments	string	Define todos os parâmetros que você gostaria de passar para sua configuração DSC. Esta propriedade será encriptada.
protectedSettings.configurationUrlSasToken	string	Especifica o token SAS para acessar a URL definida por configuration.url. Esta propriedade será encriptada.
protectedSettings.configurationDataUrlSasToken	string	Especifica o token SAS para acessar a URL definida por configurationData.url. Esta propriedade será encriptada.

Implementação de modelos

As extensões de VM do Azure podem ser implantadas com modelos do Azure Resource Manager. Os modelos são ideais ao implantar uma ou mais máquinas virtuais que exigem configuração pós-implantação. Um modelo de exemplo do Resource Manager 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

Resolver problemas

Pode obter dados sobre o estado das implementações de extensões no portal do Azure e na CLI do Azure. Para ver o estado de implantação das extensões de uma determinada VM, execute o seguinte comando usando a CLI do Azure.

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

O pacote de extensão é baixado e implantado neste local na VM do Azure

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

O ficheiro de estado da extensão contém o subestado e estado de êxito/códigos de erro juntamente com o erro detalhado e uma descrição para cada extensão executada.

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

Os registos de saída da extensão são registados no seguinte diretório:

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

Códigos de erro e seus significados

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

Suporte

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

Partilhar via