Partilhar via

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

Nota

A extensão do DSC será descontinuada em 31 de março de 2028. Faça a transição para a Configuração de Máquina do Azure até essa data. Para obter mais informações, consulte o anúncio na publicação de blogue. O serviço de Configuração de Máquina do Azure combina determinados recursos da Extensão DSC, Configuração do Estado de Automação do Azure e recursos comumente solicitados dos comentários dos clientes. A Configuração de Máquina do Azure também inclui suporte a máquinas híbridas por meio de servidores habilitados para Arc.

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

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 Atualização 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: {
      configurationArguments: {
        arg2: arg2
      }
    }
  }
}

Exemplo de Bicep para conjuntos de escalamento de máquinas virtuais do Windows

Um nó do conjunto de escala de máquinas virtuais tem uma seção que inclui o 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. configurações protegidas

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 da mesma forma que 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
settings.configuration.url Configurações.ModulesUrl
configurações.configuração.script Primeira parte das configurações. ConfigurationFunction (antes de \\)
definições.configuração.função Segunda parte das configurações. ConfigurationFunction (após \\)
definições.configuração.módulo.nome Configurações. FonteDoMódulo
definições.configuration.module.version Configurações.VersãoDoMódulo
settings.configurationArgumentos Configurações.Propriedades
configurações.configurationData.url protectedSettings.DataBlobUri (sem token SAS)
configurações.privacidade.coletaDeDados Configurações.Privacidade.ColeçãoDeDados
definições.opçõesAvançadas.downloadMapeamentos Configurações.OpçõesAvançadas.DescarregarMapeamentos
Argumentos de configuração de configurações protegidas protectedSettings.Propriedades
protectedSettings.configurationUrlSasToken Configurações SasToken
definiçõesProtegidas.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

A "Privacy.dataCollection" é '{0}'. Os únicos valores possíveis são '', 'Ativar' e 'Desativar'". "WmfVersion é '{0}'. Os únicos 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 tem o valor '{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 conduzam a locais válidos que a extensão consiga aceder na máquina remota.

Tipo de argumento de configuração inválido

"Tipo de argumentos de configuração inválido {0}"

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

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

Duplicar ArgumentosDeConfiguração

Foram encontrados argumentos duplicados '{0}' em argumentos de configuração públicos e protegidos.

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

settings.Configuration.function exige que settings.configuration.url ou settings.configuration.module seja especificado

"settings.Configuration.url requer que settings.configuration.script seja especificado"

"settings.Configuration.script requer que settings.configuration.url seja especificada"

"Configurações.Configuration.url requer que configurações.configuração.função seja especificado"

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

"protectedSettings.ConfigurationDataUrlSasToken" exige 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