Extensão de Configuração de Estado Desejado com modelos do Azure Resource Manager

Artigo
12/18/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 em geral, gerenciada por um recurso chamado configuração de máquina. O recurso de configuração da máquina inclui recursos do manipulador de extensão DSC (Configuração de Estado Desejado) e os recursos mais comumente solicitados a partir 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.

Este artigo descreve o modelo do Azure Resource Manager para o manipulador de extensão DSC (Configuração de Estado Desejado).

Nota

Você pode encontrar exemplos de esquema ligeiramente diferentes. A alteração no esquema ocorreu na versão de outubro de 2016. Para obter detalhes, consulte Atualizar de um formato anterior.

Exemplo de bíceps para uma VM

A extensão DSC herda propriedades de extensão padrão. Para obter mais informações, consulte VirtualMachineExtension classe.

@description('URI of the configuration package')
param configUri string

@description('first configuration parameter')
param arg1 string

@description('second configuration parameter')
@secure()
param arg2 string

var configName = split(split(configUri, '/')[4], '.')[0]

resource vm 'Microsoft.Compute/virtualMachines@2023-09-01' existing = {
  name: srvName
}

resource configuration_dscext 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: 'configurationname_dscext'
  parent: vm
  location: location
  properties: {
    publisher: 'Microsoft.Powershell'
    type: 'DSC'
    typeHandlerVersion: '2.77'
    autoUpgradeMinorVersion: true
    settings: {
      wmfVersion: 'latest'
      configuration: {
        url: configUri
        script: 'configurationname_dscext.ps1'
        function: 'configurationname_dscext'
      }
      configurationArguments: {
        arg1: arg1
      }
      advancedOptions: {
        rebootNodeIfNeeded: true
      }
    }
    protectedSettings: {
      configurationArguements: {
        arg2: arg2
      }
    }
  }
}

Exemplo de bíceps para conjuntos de dimensionamento de máquina virtual do Windows

Um nó de conjunto de escala de máquina virtual tem uma seção que inclui um atributo extensionProfile . Em extensões, adicione os detalhes para DSC Extension.

Para obter os detalhes mais recentes sobre a criação de modelos que implantam extensões para Conjuntos de Escala de Máquina Virtual, consulte o documento Microsoft.Compute virtualMachineScaleSets

A extensão DSC herda propriedades de extensão padrão. Para obter mais informações, consulte VirtualMachineScaleSetExtension classe.

Configurações vs. protectedSettings

Todas as configurações são salvas em um arquivo de texto de configurações na VM. As propriedades listadas em configurações são propriedades públicas. As propriedades públicas não são criptografadas no arquivo de texto de configurações. As propriedades listadas em protectedSettings são criptografadas com um certificado e não são mostradas em texto sem formatação no arquivo de configurações na VM.

Se a configuração precisar de credenciais, você poderá incluí-las em protectedSettings:

"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
               "userName": "UsernameValue1",
               "password": "PasswordValue1"
        }
    }
}

Exemplo de uso do script de configuração no Armazenamento do Azure

O exemplo a seguir é da visão geral do manipulador de extensão DSC. Este exemplo usa modelos do Resource Manager em vez de cmdlets para implantar a extensão. Salve a configuração IisInstall.ps1, coloque-a em um arquivo .zip (exemplo: iisinstall.zip) e carregue o arquivo em uma URL acessível. Este exemplo usa o armazenamento de Blob do Azure, mas você pode baixar arquivos de .zip de qualquer local arbitrário.

No modelo do Gerenciador de Recursos, o código a seguir instrui a VM a baixar o arquivo correto e executar a função PowerShell apropriada:

"settings": {
    "configuration": {
        "url": "https://demo.blob.core.windows.net/iisinstall.zip",
        "script": "IisInstall.ps1",
        "function": "IISInstall"
    }
},
"protectedSettings": {
    "configurationUrlSasToken": "odLPL/U1p9lvcnp..."
}

Atualizar a partir de um formato anterior

Todas as configurações em um formato anterior da extensão (e que têm as propriedades públicas ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken ou Properties) se adaptam automaticamente ao formato atual da extensão. Eles correm exatamente como antes.

O esquema a seguir mostra a aparência do esquema de configurações anterior:

"settings": {
    "WMFVersion": "latest",
    "ModulesUrl": "https://UrlToZipContainingConfigurationScript.ps1.zip",
    "SasToken": "SAS Token if ModulesUrl points to private Azure Blob Storage",
    "ConfigurationFunction": "ConfigurationScript.ps1\\ConfigurationFunction",
    "Properties": {
        "ParameterToConfigurationFunction1": "Value1",
        "ParameterToConfigurationFunction2": "Value2",
        "ParameterOfTypePSCredential1": {
            "UserName": "UsernameValue1",
            "Password": "PrivateSettingsRef:Key1"
        },
        "ParameterOfTypePSCredential2": {
            "UserName": "UsernameValue2",
            "Password": "PrivateSettingsRef:Key2"
        }
    }
},
"protectedSettings": {
    "Items": {
        "Key1": "PasswordValue1",
        "Key2": "PasswordValue2"
    },
    "DataBlobUri": "https://UrlToConfigurationDataWithOptionalSasToken.psd1"
}

Veja como o formato anterior se adapta ao formato atual:

Nome da propriedade atual	Esquema anterior equivalente
configurações.wmfVersion	Configurações. WMFVersion
configurações.configuração.url	Configurações. ModulesUrl
configurações.configuration.script	Primeira parte das configurações. ConfigurationFunction (antes de \\)
configurações.configuration.function	Segunda parte das configurações. ConfigurationFunction (após \\)
settings.configuration.module.name	Configurações. ModuleSource
configurações.configuration.module.version	Configurações. ModuleVersion
settings.configurationArgumentos	Configurações. Propriedades
configurações.configurationData.url	protectedSettings.DataBlobUri (sem token SAS)
settings.privacy.dataCollection	Configurações. Privacidade.dataCollection
settings.advancedOptions.downloadMapeamentos	Configurações. AdvancedOptions.DownloadMapeamentos
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	Configurações. SasToken
protectedSettings.configurationDataUrlSasToken	Token SAS de protectedSettings.DataBlobUri

Resolução de Problemas

Aqui estão alguns dos erros que você pode encontrar e como você pode corrigi-los.

Valores inválidos

"Privacy.dataCollection é '{0}'. Os únicos valores possíveis são '', 'Ativar' e 'Desativar'". "WmfVersion é '{0}'. Apenas os valores possíveis são ... e 'mais recente'".

Problema: um valor fornecido não é permitido.

Solução: altere o valor inválido para um valor válido.

URL Inválido

"ConfigurationData.url é '{0}'. Este não é um URL válido" "DataBlobUri é '{0}'. Este não é um URL válido" "Configuration.url é '{0}'. Este não é um URL válido"

Problema: um URL fornecido não é válido.

Solução: verifique todos os URLs fornecidos. Certifique-se de que todas as URLs sejam resolvidas para locais válidos que a extensão possa acessar na máquina remota.

Tipo ConfigurationArgument inválido

"Tipo configurationArguments inválido {0}"

Problema: A propriedade ConfigurationArguments não pode ser resolvida para um objeto de tabela Hash.

Solução: torne sua propriedade ConfigurationArguments uma tabela Hash. Siga o formato fornecido nos exemplos anteriores. Preste atenção às citações, vírgulas e chaves.

Duplicar ConfigurationArguments

"Encontrados argumentos duplicados '{0}' em configurações públicas e protegidasArguments"

Problema: Os ConfigurationArguments em configurações públicas e ConfigurationArguments em configurações protegidas têm propriedades com o mesmo nome.

Solução: Remova uma das propriedades duplicadas.

Propriedades em falta

"Configurações. Configuration.function requer que settings.configuration.url ou settings.configuration.module seja especificado"

"Configurações. Configuration.url requer que settings.configuration.script seja especificado"

"Configurações. Configuration.script requer que settings.configuration.url seja especificado"

"Configurações. Configuration.url requer que settings.configuration.function seja especificado"

"protectedSettings.ConfigurationUrlSasToken requer que settings.configuration.url seja especificado"

"protectedSettings.ConfigurationDataUrlSasToken requer que settings.configurationData.url seja especificado"

Problema: Uma propriedade definida precisa de outra propriedade, que está faltando.

Soluções:

Forneça a propriedade em falta.
Remova a propriedade que precisa da propriedade ausente.

Próximos passos

Saiba mais sobre como usar conjuntos de dimensionamento de máquina virtual com a extensão DSC do Azure.
Encontre mais detalhes sobre o gerenciamento seguro de credenciais da DSC.
Obtenha uma introdução ao manipulador de extensão DSC do Azure.
Para obter mais informações sobre o PowerShell DSC, vá para o centro de documentação do PowerShell.

Partilhar via