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

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 ao público, gerenciada por um recurso da configuração de máquina nomeada do Azure Automange. O recurso de configuração da máquina combina recursos do manipulador de extensão DSC (Configuração de Estado Desejado), Configuração do Estado de Automação do Azure e os recursos mais comumente solicitados 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). Muitos dos exemplos usam RegistrationURL (fornecido como um String) e RegistrationKey (fornecido como um PSCredential para integrar com a Automação do Azure. Para obter detalhes sobre como obter esses valores, consulte Usar metaconfiguração DSC para registrar máquinas híbridas.

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 ao público, gerenciada por um recurso da configuração de máquina nomeada do Azure Automange. O recurso de configuração da máquina combina recursos do manipulador de extensão DSC (Configuração de Estado Desejado), Configuração do Estado de Automação do Azure e os recursos mais comumente solicitados 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.

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

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

{
  "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 conjuntos de dimensionamento de máquinas virtuais do Windows

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

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

"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 detalhadas sobre as configurações

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

Para obter uma lista dos 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	Tipo	Description
configurações.wmfVersion	string	Especifica a versão do Windows Management Framework (WMF) que deve ser instalada na sua VM. Definir essa propriedade como a mais recente instala a versão mais recente do WMF. Atualmente, os únicos valores possíveis para essa propriedade são 4.0, 5.0, 5.1 e mais recentes. Estes valores possíveis estão sujeitos a atualizações. O valor padrão é mais recente.
configurações.configuração.url	string	Especifica o local da URL a partir do qual baixar o arquivo de .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 SAS. Esta propriedade é necessária se settings.configuration.script ou settings.configuration.function estiverem definidos. Se nenhum valor for fornecido para essas propriedades, a extensão chamará o script de configuração padrão para definir metadados do Location Configuration Manager (LCM) e os argumentos deverão ser fornecidos.
configurações.configuration.script	string	Especifica o nome do arquivo do script que contém a definição da configuração do DSC. Esse script deve estar na pasta raiz do arquivo de .zip baixado da URL especificada pela propriedade settings.configuration.url . Esta propriedade é necessária se settings.configuration.url ou settings.configuration.script estiverem definidos. Se nenhum valor for fornecido para essas propriedades, a extensão chamará o script de configuração padrão para definir metadados LCM e os argumentos deverão ser fornecidos.
configurações.configuration.function	string	Especifica o nome da configuração do DSC. A configuração nomeada deve ser incluída no script que settings.configuration.script define. Esta propriedade é necessária se settings.configuration.url ou settings.configuration.function estiverem definidos. Se nenhum valor for fornecido para essas propriedades, a extensão chamará o script de configuração padrão para definir metadados LCM e os argumentos deverão ser fornecidos.
settings.configurationArgumentos	Coleção	Define todos os parâmetros que você deseja passar para sua configuração DSC. Esta propriedade não está encriptada.
configurações.configurationData.url	string	Especifica a URL a partir da qual o arquivo de dados de configuração (.psd1) deve ser usado como entrada para a configuração do DSC. Se a URL fornecida exigir um token SAS para acesso, defina a propriedade protectedSettings.configurationDataUrlSasToken como o valor do seu token 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 essa propriedade em branco ou nula habilita a telemetria. O valor padrão é ''. Para obter mais informações, consulte Coleta de dados de extensão DSC do Azure.
settings.advancedOptions.downloadMapeamentos	Coleção	Define locais alternativos a partir dos quais fazer o download do WMF. Para obter mais informações, consulte Azure DSC extension 2.8 e como mapear downloads das dependências de extensão para seu próprio local.
protectedSettings.configurationArguments	Coleção	Define todos os parâmetros que você deseja passar para sua configuração DSC. Esta propriedade é encriptada.
protectedSettings.configurationUrlSasToken	string	Especifica o token SAS a ser usado para acessar a URL que settings.configuration.url define. Esta propriedade é encriptada.
protectedSettings.configurationDataUrlSasToken	string	Especifica o token SAS a ser usado para acessar a URL que settings.configurationData.url define. Esta propriedade é encriptada.

Script de configuração padrão

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

Nome da propriedade	Tipo	Description
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Propriedade necessária. Especifica a chave usada para um nó se registrar no 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 na conta de automação. Veja o exemplo.
settings.configurationArguments.RegistrationUrl	string	Propriedade necessária. Especifica a URL do ponto de extremidade de automação onde o nó tenta se registrar. Esse valor pode ser descoberto automaticamente usando o método de referência na conta de automação.
settings.configurationArguments.NodeConfigurationName	string	Propriedade necessária. Especifica a configuração do nó na conta de automação a ser atribuída ao nó.
settings.configurationArguments.ConfigurationMode	string	Especifica o modo para LCM. As opções válidas incluem ApplyOnly, ApplyandMonitor e ApplyandAutoCorrect. O valor padrão é ApplyandMonitor.
configurações.configuraçãoArguments.RefreshFrequencyMins	UINT32	Especifica a frequência com que o LCM tenta verificar se há atualizações com a conta de automação. O valor padrão é 30. O valor mínimo é 15.
configurações.configuraçãoArguments.ConfiguraçãoModeFrequênciaMins	UINT32	Especifica a frequência com que o LCM valida a configuração atual. O valor padrão é 15. O valor mínimo é 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Especifica se um nó pode ser reinicializado automaticamente se uma operação DSC o solicitar. O valor predefinido é falso.
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	boolean	Especifica se o LCM substitui módulos existentes no nó. O valor predefinido é falso.

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

O exemplo a seguir mostra o comportamento padrão para a extensão DSC, que é fornecer configurações de metadados para LCM e registrar com o serviço Automation DSC. 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 LCM.

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

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

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

O exemplo a seguir obtém o RegistrationUrl e o 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 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. Para obter mais informações, consulte a tabela em Detalhes.

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

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

Problema: O valor RegistrationKey em protectedSettings.configurationArguments não pode ser fornecido como qualquer tipo diferente de um 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 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.