Extensão Desired State Configuration com os modelos do Azure Resource Manager

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

Exemplo de Bicep para uma máquina virtual

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

@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 do Bicep para conjuntos de dimensionamento de máquinas virtuais do Windows

Um nó de conjunto de dimensionamento de máquinas virtuais tem uma seção que inclui um atributo extensionProfile. Em extensões, adicione os detalhes para a extensão de DSC.

Para ver os detalhes mais recentes sobre a criação de modelos que implantam extensões para Conjuntos de Dimensionamento de Máquinas Virtuais, confira o documento Microsoft.Compute virtualMachineScaleSets

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

Configurações versus protectedSettings

Todas as configurações foram salvas em um arquivo de texto de configurações na VM. Propriedades listadas em Configurações são propriedades públicas. 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 exibidas como texto sem formatação no arquivo de configurações da VM.

Se a configuração precisar de credenciais, você pode incluir as credenciais em protectedSettings:

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

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

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

No modelo do Resource Manager, o código a seguir instrui a VM a baixar o arquivo correto e, em seguida, executar a função apropriada do PowerShell:

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

Atualizar 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) serão adaptadas automaticamente ao formato atual da extensão. Elas são executadas como antes.

O esquema a seguir mostra como se parecia o 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 formato anterior se adapta ao formato atual:

Solução de problemas

Confira alguns erros que você pode encontrar e como corrigi-los.

Valores inválidos

"Privacy.dataCollection é '{0}'. Os únicos valores possíveis são '', 'Enable' e 'Disable'". "WmfVersion é '{0}'. Ú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álida

"A URL de ConfigurationData é '{0}'." Essa não é uma URL válida" "DataBlobUri é '{0}'. Essa não é uma URL válida" "Configuration.url é '{0}'. Essa não é uma URL válida"

Problema: uma URL fornecida não é válida.

Solução: Verifique todas as URLs fornecidas. Certifique-se de que todas as URLs apontem para locais válidos que a extensão possa acessar na máquina remota.

Tipo ConfigurationArgument inválido

"Tipo de configurationArguments inválido {0}"

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

Solução: Torne a propriedade ConfigurationArguments uma tabela de hash. Siga o formato fornecido no exemplo anterior. Fique atento às chaves, vírgulas e aspas.

ConfigurationArguments duplicado

"Argumentos '{0}' duplicados encontrados em configurationArguments públicos e protegidos"

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

Solução: Remova uma das propriedades duplicadas.

Propriedades ausentes

“settings.Configuration.function requer a especificação de settings.configuration.url ou de settings.configuration.module”

“settings.Configuration.url requer a especificação de settings.configuration.script”

“settings.Configuration.script requer a especificação de settings.configuration.url”

“settings.Configuration.url requer a especificação de settings.configuration.function”

“protectedSettings.ConfigurationUrlSasToken requer a especificação de settings.configuration.url”

“protectedSettings.ConfigurationDataUrlSasToken requer a especificação de settings.configurationData.url”

Problema: uma propriedade definida precisa de outra propriedade, que está ausente.

Soluções:

• Forneça a propriedade ausente.
• Remova a propriedade que precisa da propriedade ausente.

Próximas etapas

• Saiba mais sobre Uso de conjuntos de dimensionamento de máquinas virtuais com a extensão de DSC do Azure.
• Encontre mais detalhes sobre Gerenciamento de credenciais seguras do DSC.
• Obtenha uma introdução ao manipulador de extensões DSC do Azure.
• Para obter mais informações sobre o DSC do PowerShell, vá até o Centro de documentação do PowerShell.