Desired State Configuration extensão com modelos de Resource Manager do Azure

Nota

Antes de ativar a extensão DSC, gostaríamos que soubesse que uma versão mais recente do DSC está agora disponível de forma geral, gerida por uma funcionalidade do Azure Automange com o nome configuração do computador. A funcionalidade de configuração do computador combina as funcionalidades do processador de extensões Desired State Configuration (DSC), Automatização do Azure State Configuration e as funcionalidades mais frequentemente pedidas a partir do feedback dos clientes. A configuração do computador também inclui suporte de máquina híbrida através de servidores compatíveis com o Arc.

Este artigo descreve o modelo de Resource Manager do Azure para o processador de extensões Desired State Configuration (DSC). Muitos dos exemplos utilizam RegistrationURL (fornecido como uma Cadeia) e RegistrationKey (fornecido como PSCredential para integrar com Automatização do Azure. Para obter detalhes sobre como obter esses valores, veja Utilizar a metaconfiguração do DSC para registar máquinas híbridas.

Nota

Antes de ativar a extensão DSC, gostaríamos que soubesse que uma versão mais recente do DSC está agora disponível de forma geral, gerida por uma funcionalidade do Azure Automange com o nome configuração do computador. A funcionalidade de configuração do computador combina as funcionalidades do processador de extensões Desired State Configuration (DSC), Automatização do Azure State Configuration e as funcionalidades mais frequentemente pedidas a partir do feedback dos clientes. A configuração do computador também inclui suporte de máquina híbrida através de servidores compatíveis com o Arc.

Nota

Poderá encontrar exemplos de esquema ligeiramente diferentes. A alteração no esquema ocorreu na versão de outubro de 2016. Para obter detalhes, consulte Atualizar a partir de um formato anterior.

Exemplo de modelo para uma VM do Windows

O fragmento seguinte vai para a secção Recurso do modelo. A extensão DSC herda as propriedades de extensão predefinidas. Para obter mais informações, veja VirtualMachineExtension class (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 conjuntos de dimensionamento de máquinas virtuais do Windows

Um nó de conjunto de dimensionamento de máquinas virtuais tem uma secção de propriedades que tem um atributo VirtualMachineProfile, extensionProfile . Em extensões, adicione os detalhes da Extensão DSC.

A extensão DSC herda as propriedades de extensão predefinidas. Para obter mais informações, veja VirtualMachineScaleSetExtension class (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 detalhadas sobre definições

Utilize o seguinte esquema na secção de definições da extensão do Azure DSC num modelo de Resource Manager.

Para obter uma lista dos argumentos disponíveis para o script de configuração predefinido, veja Script de configuração predefinido.

"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	Descrição
settings.wmfVersion	string	Especifica a versão do Windows Management Framework (WMF) que deve ser instalada na VM. Definir esta propriedade como mais recente instala a versão mais recente do WMF. Atualmente, os únicos valores possíveis para esta propriedade são 4.0, 5.0, 5.1 e mais recentes. Estes valores possíveis estão sujeitos a atualizações. O valor predefinido é o mais recente.
settings.configuration.url	string	Especifica a localização do URL a partir da qual pode transferir a configuração do DSC .zip ficheiro. Se o URL fornecido exigir um token de SAS para acesso, defina a propriedade protectedSettings.configurationUrlSasToken como o valor do token de SAS. Esta propriedade é necessária se settings.configuration.script ou settings.configuration.function estiverem definidos. Se não for dado nenhum valor para estas propriedades, a extensão chama o script de configuração predefinido para definir metadados de localização Configuration Manager (LCM) e os argumentos devem ser fornecidos.
settings.configuration.script	string	Especifica o nome de ficheiro do script que contém a definição da configuração do DSC. Este script tem de estar na pasta raiz do ficheiro .zip que é transferido a partir do URL especificado pela propriedade settings.configuration.url . Esta propriedade é necessária se settings.configuration.url ou settings.configuration.script estiverem definidos. Se não for dado nenhum valor para estas propriedades, a extensão chama o script de configuração predefinido para definir metadados LCM e os argumentos devem ser fornecidos.
settings.configuration.function	string	Especifica o nome da configuração do DSC. A configuração com o nome tem de 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 não for dado nenhum valor para estas propriedades, a extensão chama o script de configuração predefinido para definir metadados LCM e os argumentos devem ser fornecidos.
settings.configurationArguments	Coleção	Define todos os parâmetros que pretende transmitir para a configuração do DSC. Esta propriedade não está encriptada.
settings.configurationData.url	string	Especifica o URL a partir do qual pode transferir o ficheiro de dados de configuração (.psd1) para utilizar como entrada para a configuração do DSC. Se o URL fornecido exigir um token de SAS para acesso, defina a propriedade protectedSettings.configurationDataUrlSasToken como o valor do token de SAS.
settings.privacy.dataCollection	string	Ativa ou desativa a coleção de telemetria. Os únicos valores possíveis para esta propriedade são Ativar, Desativar, '' ou $null. Deixar esta propriedade em branco ou nula ativa a telemetria. O valor predefinido é "". Para obter mais informações, veja Recolha de dados da extensão do Azure DSC.
settings.advancedOptions.downloadMappings	Coleção	Define localizações alternativas a partir das quais pode transferir o WMF. Para obter mais informações, veja Azure DSC extension 2.8 and how to map downloads of the extension dependencies to your own location (Extensão 2.8 do Azure DSC e como mapear transferências das dependências da extensão para a sua própria localização).
protectedSettings.configurationArguments	Coleção	Define todos os parâmetros que pretende transmitir para a configuração do DSC. Esta propriedade está encriptada.
protectedSettings.configurationUrlSasToken	string	Especifica o token de SAS a utilizar para aceder ao URL que settings.configuration.url define. Esta propriedade está encriptada.
protectedSettings.configurationDataUrlSasToken	string	Especifica o token de SAS a utilizar para aceder ao URL que definições.configurationData.url define. Esta propriedade está encriptada.

Script de configuração predefinido

Para obter mais informações sobre os seguintes valores, veja Definições básicas Configuration Manager locais. Pode utilizar o script de configuração predefinido da extensão DSC para configurar apenas as propriedades LCM listadas na tabela seguinte.

Nome da propriedade	Tipo	Descrição
protectedSettings.configurationArguments.RegistrationKey	PSCredential	Propriedade necessária. Especifica a chave utilizada para um nó se registar no serviço Automatização do Azure como a palavra-passe de um objeto de credencial do PowerShell. Este valor pode ser detetado automaticamente com o método listkeys na conta de Automatização. Veja o exemplo.
settings.configurationArguments.RegistrationUrl	string	Propriedade necessária. Especifica o URL do ponto final de Automatização onde o nó tenta registar-se. Este valor pode ser detetado automaticamente com o método de referência na conta de Automatização.
settings.configurationArguments.NodeConfigurationName	string	Propriedade necessária. Especifica a configuração do nó na conta de Automatização a atribuir ao nó.
settings.configurationArguments.ConfigurationMode	string	Especifica o modo para LCM. As opções válidas incluem ApplyOnly, ApplyandMonitor e ApplyandAutoCorrect. O valor predefinido é ApplyandMonitor.
settings.configurationArguments.RefreshFrequencyMins	uint32	Especifica a frequência com que o LCM tenta verificar com a conta de Automatização as atualizações. O valor predefinido é 30. O valor mínimo é 15.
settings.configurationArguments.ConfigurationModeFrequencyMins	uint32	Especifica a frequência com que o LCM valida a configuração atual. O valor predefinido é 15. O valor mínimo é 15.
settings.configurationArguments.RebootNodeIfNeeded	boolean	Especifica se um nó pode ser reiniciado automaticamente se uma operação DSC o pedir. O valor predefinido é falso.
settings.configurationArguments.ActionAfterReboot	string	Especifica o que acontece após um reinício ao aplicar uma configuração. As opções válidas são ContinueConfiguration e StopConfiguration. O valor predefinido é ContinueConfiguration.
settings.configurationArguments.AllowModuleOverwrite	boolean	Especifica se o LCM substitui os módulos existentes no nó. O valor predefinido é falso.

definições vs. protectedSettings

Todas as definições são guardadas num ficheiro de texto de definições na VM. As propriedades listadas nas definições são propriedades públicas. As propriedades públicas não são encriptadas no ficheiro de texto de definições. As propriedades listadas em protectedSettings são encriptadas com um certificado e não são apresentadas em texto simples no ficheiro de definições na VM.

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

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

Script de configuração de exemplo

O exemplo seguinte mostra o comportamento predefinido da extensão DSC, que consiste em fornecer definições de metadados ao LCM e registar-se no serviço DSC de Automatização. São necessários argumentos de configuração. Os argumentos de configuração são transmitidos ao script de configuração predefinido para definir metadados LCM.

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

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

O exemplo seguinte é da descrição geral do processador de extensões do DSC. Este exemplo utiliza Resource Manager modelos em vez de cmdlets para implementar a extensão. Guarde a configuração do IisInstall.ps1, coloque-a num ficheiro de .zip (por exemplo: iisinstall.zip) e, em seguida, carregue o ficheiro num URL acessível. Este exemplo utiliza o armazenamento de Blobs do Azure, mas pode transferir .zip ficheiros a partir de qualquer localização arbitrária.

No modelo Resource Manager, o seguinte código indica à VM para transferir o ficheiro correto e, em seguida, executar a função adequada do PowerShell:

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

Exemplo com valores de registo Automatização do Azure referenciados

O exemplo seguinte obtém o RegistrationUrl e RegistrationKey ao referenciar as propriedades da conta Automatização do Azure e ao utilizar o método listkeys para obter 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 definições num formato anterior da extensão (e que têm as propriedades públicas ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken ou Properties) adaptam-se automaticamente ao formato atual da extensão. Correm como antes.

O esquema seguinte mostra como era o esquema de definições anteriores:

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

Eis como o formato anterior se adapta ao formato atual:

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

Resolução de problemas

Seguem-se alguns dos erros que pode encontrar e como pode corrigi-los.

Valores inválidos

"Privacy.dataCollection is '{0}'. Os únicos valores possíveis são "", "Ativar" e "Desativar". "WmfVersion é '{0}'. Apenas os valores possíveis são... e "mais recente".

Problema: não é permitido um valor fornecido.

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 is '{0}'. Este não é um URL válido" "DataBlobUri é "{0}". Este NÃO é um URL válido" "Configuration.url is '{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 todos os URLs são resolvidos para localizações válidas às quais a extensão pode aceder no computador remoto.

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

Solução: altere a entrada protectedSettings.configurationArguments para RegistrationKey para um tipo PSCredential com o seguinte formato:

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

Tipo de ConfigurationArgument inválido

"ConfigurationArguments type {0}inválido"

Problema: a propriedade ConfigurationArguments não consegue resolver para um objeto de tabela Hash .

Solução: torne a propriedade ConfigurationArguments numa tabela Hash. Siga o formato fornecido nos exemplos anteriores. Cuidado com aspas, vírgulas e chavetas.

Configuração DuplicadaArguments

"Foram encontrados argumentos duplicados '{0}' na configuração pública e protegidaArguments"

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

Solução: remova uma das propriedades duplicadas.

Propriedades em falta

"definições. Configuration.function requer que settings.configuration.url ou settings.configuration.module esteja especificado"

"definições. Configuration.url requer que settings.configuration.script esteja especificado"

"definições. Configuration.script requer que settings.configuration.url esteja especificado"

"definições. Configuration.url requer que settings.configuration.function esteja especificado"

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

"protectedSettings.ConfigurationDataUrlSasToken requer que settings.configurationData.url esteja especificado"

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

Soluções:

• Indique a propriedade em falta.
• Remova a propriedade que precisa da propriedade em falta.

Passos seguintes

• Saiba como utilizar conjuntos de dimensionamento de máquinas virtuais com a extensão do Azure DSC.
• Encontre mais detalhes sobre a gestão segura de credenciais do DSC.
• Obtenha uma introdução ao processador de extensões do Azure DSC.
• Para obter mais informações sobre o DSC do PowerShell, aceda ao centro de documentação do PowerShell.