Compartilhar via

Extensão de configuração de estado desejado com os modelos do Azure Resource Manager

  • Artigo

Observação

Antes de você habilitar a extensão de DSC, gostaríamos de informar que uma versão mais recente da DSC já está em disponibilidade geral. Ela é gerenciada por um recurso chamado configuração de máquina. O recurso de configuração de máquina inclui os recursos do manipulador de extensões da DSC (Desired State Configuration) e os recursos mais solicitados com base 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.

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

Observação

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

Exemplo do Bicep para uma VM

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: {
      configurationArguements: {
        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.

Comparação entre settings e 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. Propriedades 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ê 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 de manipulador de extensão de 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:

Nome da Propriedade Atual Equivalente ao esquema anterior
settings.wmfVersion settings.wmfVersion
settings.configuration.url settings.ModulesUrl
settings.configuration.script Primeira parte de settings.ConfigurationFunction (antes de \\)
settings.configuration.function Segunda parte de settings.ConfigurationFunction (depois de \\)
settings.configuration.module.name settings.ModuleSource
settings.configuration.module.version settings.ModuleVersion
settings.configurationArguments settings.Properties
settings.configurationData.url protectedSettings.DataBlobUri (sem token SAS)
settings.privacy.dataCollection settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings settings.advancedOptions.downloadMappings
protectedSettings.configurationArguments protectedSettings.Properties
protectedSettings.configurationUrlSasToken settings.SasToken
protectedSettings.configurationDataUrlSasToken Token SAS de protectedSettings.DataBlobUri

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 'latest'".

Problema: um valor fornecido não é permitido.

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

URL inválida

"ConfigurationData.url é '{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 resolvem para locais válidos que a extensão pode acessar no computador remoto.

Tipo ConfigurationArgument inválido

"Tipo configurationArgument 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