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

Observação

Antes de você habilitar a extensão de DSC, gostaríamos de informar que uma versão mais recente da DSC agora está em disponibilidade geral, gerenciada por um recurso de Gerenciamento Automatizado do Azure chamado configuração de máquina. O recurso de configuração de máquina combina os recursos do manipulador de extensão de DSC (Desired State Configuration), a State Configuration da Automação do Azure e os recursos mais solicitados 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). Muitos dos exemplos usam RegistrationURL (fornecido como cadeia de caracteres) e RegistrationKey (fornecido como PSCredential) para fazer a integração com a Automação do Azure. Para obter detalhes sobre como obter esses valores, consulte Usar a metaconfiguração DSC para registrar máquinas híbridas.

Observação

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

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 de modelo para uma VM do Windows

O snippet a seguir vai na seção Recursos do modelo. A extensão de DSC herda propriedades de extensão padrão. Para obter mais informações, consulte a classe VirtualMachineExtension.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/Microsoft.Powershell.DSC')]",
  "apiVersion": "2018-06-01",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', parameters('VMName'))]"
  ],
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "protectedSettings": {
      "Items": {
        "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
      }
    },
    "settings": {
      "Properties": [
        {
          "Name": "RegistrationKey",
          "Value": {
            "UserName": "PLACEHOLDER_DONOTUSE",
            "Password": "PrivateSettingsRef:registrationKeyPrivate"
          },
          "TypeName": "System.Management.Automation.PSCredential"
        },
        {
          "Name": "RegistrationUrl",
          "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
          "TypeName": "System.String"
        },
        {
          "Name": "NodeConfigurationName",
          "Value": "[parameters('nodeConfigurationName')]",
          "TypeName": "System.String"
        }
      ]
    }
  }
}

Exemplo de modelo para conjunto de dimensionamento de máquinas virtuais do Windows

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

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

"extensionProfile": {
    "extensions": [
      {
        "name": "Microsoft.Powershell.DSC",
        "properties": {
          "publisher": "Microsoft.Powershell",
          "type": "DSC",
          "typeHandlerVersion": "2.77",
          "autoUpgradeMinorVersion": true,
          "protectedSettings": {
            "Items": {
              "registrationKeyPrivate": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-06-30').Keys[0].value]"
            }
          },
          "settings": {
            "Properties": [
              {
                "Name": "RegistrationKey",
                "Value": {
                  "UserName": "PLACEHOLDER_DONOTUSE",
                  "Password": "PrivateSettingsRef:registrationKeyPrivate"
                },
                "TypeName": "System.Management.Automation.PSCredential"
              },
              {
                "Name": "RegistrationUrl",
                "Value": "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
                "TypeName": "System.String"
              },
              {
                "Name": "NodeConfigurationName",
                "Value": "[parameters('nodeConfigurationName')]",
                "TypeName": "System.String"
              }
            ]
          }
        }
      }
    ]
  }

Informações de configuração detalhadas

Use o esquema a seguir na seção configurações da extensão de DSC do Azure em um modelo do Resource Manager.

Para obter uma lista de argumentos disponíveis para o script de configuração padrão, consulte Script de configuração padrão.

"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": {
        "downloadMappings": {
            "customWmfLocation": "http://myWMFlocation"
        }
    }
},
"protectedSettings": {
    "configurationArguments": {
        "parameterOfTypePSCredential1": {
            "userName": "UsernameValue1",
            "password": "PasswordValue1"
        },
        "parameterOfTypePSCredential2": {
            "userName": "UsernameValue2",
            "password": "PasswordValue2"
        }
    },
    "configurationUrlSasToken": "?g!bber1sht0k3n",
    "configurationDataUrlSasToken": "?dataAcC355T0k3N"
}

Detalhes

Nome da propriedade	Type	Descrição
settings.wmfVersion	string	Especifica a versão do Windows Management Framework (WMF) que deve ser instalada em sua VM. Configurar essa propriedade como latest instala a versão mais recente de WMF. Atualmente, os únicos valores possíveis para essa propriedade são 4.0, 5.0, 5.1 e o mais recente. Esses valores possíveis estão sujeitos a atualizações. O valor padrão é latest.
settings.configuration.url	string	Especifica o local da URL de onde baixar seu arquivo .zip de configuração DSC. Se a URL fornecida exigir um token SAS para acesso, defina a propriedade protectedSettings.configurationUrlSasToken como o valor do seu token de SAS. Esta propriedade será necessária se settings.configuration.script ou settings.configuration.function estiverem definidas. Se nenhum valor for fornecido para essas propriedades, a extensão chama o script de configuração padrão para definir os metadados do LCM (Location Configuration Manager) e os argumentos devem ser fornecidos.
settings.configuration.script	string	Especifica o nome do arquivo do script que contém a definição de sua configuração DSC. Esse script deve estar na pasta raiz do arquivo .zip que é baixado da URL especificada pela propriedade settings.configuration.url. Esta propriedade é necessária se settings.configuration.url ou settings.configuration.script estiverem definidas. Se nenhum valor for fornecido para essas propriedades, a extensão chama o script de configuração padrão para definir os metadados do LCM e os argumentos devem ser fornecidos.
settings.configuration.function	string	Especifica o nome da configuração DSC. A configuração que é denominada deve estar contida no script definido por settings.configuration.script. Esta propriedade será necessária se settings.configuration.script.url ou settings.configuration.function estiverem definidas. Se nenhum valor for fornecido para essas propriedades, a extensão chama o script de configuração padrão para definir os metadados do LCM e os argumentos devem ser fornecidos.
settings.configurationArguments	Coleção	Define os parâmetros que você deseja passar para a configuração de DSC. Essa propriedade não é criptografada.
settings.configurationData.url	string	Especifica a URL de onde baixar o arquivo de dados de configuração (.psd1) para usar como entrada para a sua configuração de DSC. Se a URL fornecida exigir um token SAS para acesso, defina a propriedade protectedSettings.configurationDataUrlSasToken como o valor do seu token de SAS.
settings.privacy.dataCollection	string	Habilita ou desabilita a coleta de telemetria. Os únicos valores possíveis para essa propriedade são Enable, Disable, '' ou $null. Deixar esta propriedade em branco ou nulo permite telemetria. O valor padrão é '' . Para obter mais informações, consulte coleta de dados de extensão de DSC do Azure.
settings.advancedOptions.downloadMappings	Coleção	Define os locais alternativos de onde baixar o WMF. Para obter mais informações, consulte extensão de DSC do Azure 2.8 e como mapear downloads das dependências de extensão para seu próprio local.
protectedSettings.configurationArguments	Coleção	Define os parâmetros que você deseja passar para a configuração de DSC. Essa propriedade é criptografada.
protectedSettings.configurationUrlSasToken	string	Especifica o token SAS a usar para acessar a URL definida por settings.configuration.url. Essa propriedade é criptografada.
protectedSettings.configurationDataUrlSasToken	string	Especifica o token SAS a ser usado para acessar a URL definida por settings.configurationData.url. Essa propriedade é criptografada.

Script de configuração padrão

Para obter mais informações sobre os seguintes valores, consulte Configurações Básicas do Local Configuration Manager. Você pode usar o script de configuração padrão de extensão DSC para configurar apenas as propriedades do LCM que são listadas na tabela a seguir.

Nome da propriedade	Type	Descrição
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Propriedade exigida. Especifica a chave que é usada para um nó para registrar com o serviço de Automação do Azure como a senha de um objeto de credencial do PowerShell. Esse valor pode ser descoberto automaticamente usando o método listkeys em relação à conta de Automação. Veja o exemplo.
settings.configurationArguments.RegistrationUrl	string	Propriedade exigida. Especifica a URL do ponto de extremidade de Automação em que o nó tenta registrar. Esse valor pode ser descoberto automaticamente usando o método de referência em relação à conta de Automação.
settings.configurationArguments.NodeConfigurationName	string	Propriedade exigida. Especifica a configuração de nó na conta de Automação para atribuir ao nó.
settings.configurationArguments.ConfigurationMode	string	Especifica o modo para o LCM. As opções válidas incluem ApplyOny, ApplyandMonitior e ApplyandAutoCorrect. O valor padrão é ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Especifica com que frequência o LCM tenta verificar a conta de automação para atualizações. O valor padrão é 30. O valor mínimo é 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Especifica com que frequência o LCM valida a configuração atual. O valor padrão é 15. O valor mínimo é 15.
settings.configurationArguments.RebootNodeIfNeeded	booleano	Especifica se um nó pode ser reinicializado automaticamente se uma operação de DSC solicitar. O valor padrão é false.
settings.configurationArguments.ActionAfterReboot	string	Especifica o que acontece após uma reinicialização ao aplicar uma configuração. As opções válidas são ContinueConfiguration e StopConfiguration. O valor padrão é ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	booleano	Especifica se o LCM substitui os módulos existentes no nó. O valor padrão é false.

settings vs.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 de script de configuração

O exemplo a seguir mostra o comportamento padrão para a extensão de DSC, que é fornecer configurações de metadados para o LCM e registrar com o serviço de DSC de Automação. Os argumentos de configuração são necessários. Os argumentos de configuração são passados para o script de configuração padrão para definir metadados do LCM.

"settings": {
    "configurationArguments": {
        "RegistrationUrl" : "[parameters('registrationUrl1')]",
        "NodeConfigurationName" : "nodeConfigurationNameValue1"
    }
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "registrationKey"
        }
    }
}

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..."
}

Exemplo usando os valores de registro referenciados da Automação do Azure

O exemplo a seguir obtém RegistrationUrl e RegistrationKey fazendo referência às propriedades da conta de Automação do Azure e usando o método listkeys para recuperar a Chave Primária (0). Neste exemplo, os parâmetros automationAccountName e NodeConfigName foram fornecidos ao modelo.

"settings": {
    "RegistrationUrl" : "[reference(concat('Microsoft.Automation/automationAccounts/', parameters('automationAccountName'))).registrationUrl]",
    "NodeConfigurationName" : "[parameters('NodeConfigName')]"
},
"protectedSettings": {
    "configurationArguments": {
        "RegistrationKey": {
            "userName": "NOT_USED",
            "Password": "[listKeys(resourceId('Microsoft.Automation/automationAccounts/', parameters('automationAccountName')), '2018-01-15').Keys[0].value]"
        }
    }
}

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. Para saber mais, consulte a tabela em Detalhes.

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 RegistrationKey inválido

“Tipo inválido para o parâmetro RegistrationKey do tipo PSCredential.”

Problema: o valor RegistrationKey em protectedSettings.configurationArguments só pode ser fornecido como o tipo PSCredential.

Solução: Altere a entrada protectedSettings.configurationArguments de RegistrationKey para um tipo PSCredential usando o seguinte formato:

"configurationArguments": {
    "RegistrationKey": {
        "userName": "NOT_USED",
        "Password": "RegistrationKey"
    }
}

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

• 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.