Extensión Desired State Configuration con plantillas de Azure Resource Manager

En este artículo se describe la plantilla de Azure Resource Manager para el controlador de la extensión Desired State Configuration (DSC). Muchos de los ejemplos usan RegistrationURL (proporcionado como String) y RegistrationKey (proporcionado como PSCredential) para incorporarlos en Azure Automation. Para más información sobre cómo obtener esos valores, consulte Uso de la metaconfiguración de DSC para registrar máquinas híbridas.

Ejemplo de plantilla para una máquina virtual de Windows

El fragmento de código siguiente corresponde a la sección Resource de la plantilla. La extensión DSC hereda las propiedades de extensión predeterminadas. Para más información, consulte la clase 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"
        }
      ]
    }
  }
}

Ejemplo de plantilla para conjuntos de escalado de máquinas virtuales Windows

Un nodo del conjunto de escalado de máquinas virtuales tiene una sección properties que tiene un atributo VirtualMachineProfile, extensionProfile. En extensiones, agregue los detalles para la extensión DSC.

La extensión DSC hereda las propiedades de extensión predeterminadas. Para más información, consulte la clase 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"
              }
            ]
          }
        }
      }
    ]
  }

Información de configuración detallada

Use el esquema siguiente en la sección settings de la extensión DSC de Azure en una plantilla de Resource Manager.

Para una lista de los argumentos disponibles para el script de configuración predeterminada, consulte Script de configuración predeterminada.

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

Detalles

Script de configuración predeterminada

Para más información sobre los valores siguientes, consulte Configuración básica del administración de configuración local. Puede usar el script de configuración predeterminada de la extensión DSC para configurar solo las propiedades de LCM que aparecen en la tabla siguiente.

settings vs. protectedSettings

Todas las configuraciones se guardan en un archivo de texto de configuración en la máquina virtual. Las propiedades que aparece en settings son propiedades públicas. Las propiedades públicas no están cifradas en el archivo de texto de configuración. Las propiedades que aparecen en protectedSettings se cifran con un certificado y no aparecen en texto sin formato en el archivo de configuración de la máquina virtual.

Si la configuración necesita credenciales, puede incluirlas en protectedSettings:

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

Script de configuración de ejemplo

En el ejemplo siguiente se muestra el comportamiento predeterminado de la extensión DSC, que consiste en proporcionar la configuración de los metadatos al LCM y registrarse en el servicio de DSC de Automatización. Los argumentos de configuración son obligatorios. Los argumentos de configuración se transfieren al script de configuración predeterminada para establecer los metadatos del LCM.

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

Ejemplo con el script de configuración en Azure Storage

El ejemplo siguiente proviene de la información general del controlador de la extensión DSC. Este ejemplo usa plantillas de Resource Manager en lugar de cmdlets para implementar la extensión. Guarde la configuración IisInstall.ps1, colóquela en un archivo .zip (ejemplo: iisinstall.zip) y cargue el archivo en una dirección URL accesible. Este ejemplo usa Azure Blob Storage, pero puede descargar los archivos .zip desde cualquier ubicación arbitraria.

En la plantilla de Resource Manager, el código siguiente indica a la máquina virtual que descargue el archivo correcto y, luego, ejecute la función de PowerShell adecuada:

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

Ejemplo de uso de los valores de registro de Azure Automation a los que se hace referencia

En el ejemplo siguiente se obtienen RegistrationUrl y RegistrationKey, para lo que se hace referencia a las propiedades de la cuenta de Azure Automation y se utiliza el método listkeys para recuperar la clave principal (0). En este ejemplo, se han proporcionado los parámetros automationAccountName y NodeConfigName a la plantilla.

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

Actualización desde un formato anterior

Todas las configuraciones que estén en un formato anterior de la extensión (y que tienen las propiedades públicas ModulesUrl, ModuleSource, ModuleVersion, ConfigurationFunction, SasToken o Properties) se adaptan automáticamente al formato actual de la extensión. Se ejecuta tal como lo hacía antes.

El esquema siguiente muestra el aspecto que tenía el esquema de configuración 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"
}

Así se adapta el formato anterior al actual:

Solución de problemas

Esto son algunos de los errores que pueden surgir y cómo se pueden corregir.

Valores no válidos

"Privacy.dataCollection is '{0}'. ("Privacy.dataCollection es "{0}") The only possible values are '', 'Enable', and 'Disable'" (Privacy.dataCollection es '{0}'. Los únicos valores posibles son ", "Enable" y "Disable"). "WmfVersion is '{0}'. ("WmfVersion es "{0}") Los únicos valores posibles son: and "latest" (WmfVersion es '{0}'. Los únicos valores posibles son... y "latest").

Problema: se proporcionó un valor no permitido.

Solución: cambie el valor no válido por un valor válido. Para más información, consulte la tabla que aparece en Detalles.

Dirección URL no válida

"ConfigurationData.url is '{0}'. ("ConfigurationData.url es "{0}") This is not a valid URL" "DataBlobUri is '{0}'. (Esta dirección URL no es válida" "DataBlobUri es "{0}") This is not a valid URL" "Configuration.url is '{0}'. (Esta dirección URL no es válida" "Configuration.url es "{0}") This is not a valid URL" This is not a valid URL" (Configuration.url es '{0}'. No es una dirección URL válida)

Problema: una URL proporcionada no es válida.

Solución: revise todas las direcciones URL proporcionadas. Asegúrese de que todas las direcciones URL se resuelvan en ubicaciones válidas a las que la extensión pueda acceder en la máquina remota.

Tipo RegistrationKey no válido

"Tipo no válido para el parámetro RegistrationKey del tipo PSCredential."

Problema: el valor de RegistrationKey en protectedSettings.configurationArguments no se puede proporcionar como cualquier tipo que no sea PSCredential.

Solución: cambie la entrada de protectedSettings.configurationArguments de RegistrationKey a un tipo PSCredential con el formato siguiente:

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

Tipo de ConfigurationArgument no válido

"Invalid configurationArguments type {0}" ("Tipo {0} de configurationArguments" no válido)

Problema: la propiedad ConfigurationArguments no se puede resolver en un objeto Tabla hash.

Solución: convierta la propiedad ConfigurationArguments en una Tabla hash. Siga el formato proporcionado en los ejemplos anteriores. Esté atento a las comillas, comas y llaves.

ConfigurationArguments duplicadas

"Found duplicate arguments '{0}' in both public and protected configurationArguments" (Se encontraron argumentos duplicados "{0}" en propiedades configurationArguments públicas y privadas)

Problema: la propiedad ConfigurationArguments en la configuración pública y la propiedad ConfigurationArguments en la configuración protegida contienen propiedades con el mismo nombre.

Solución: quite una de las propiedades duplicadas.

Propiedades que faltan

"settings.Configuration.function requiere que se especifiquen settings.configuration.url o settings.configuration.module"

"settings.Configuration.url requiere que se especifique settings.configuration.script"

"settings.Configuration.script requiere que se especifique settings.configuration.url"

"settings.Configuration.url requiere que se especifique settings.configuration.function"

"protectedSettings.ConfigurationUrlSasToken requieres que se especifique settings.configuration.url"

"protectedSettings.ConfigurationDataUrlSasToken requiere que se especifique settings.configurationData.url"

Problema: una propiedad definida requiere otra propiedad que falta.

Soluciones:

• Proporcione la propiedad que falta.
• Quite la propiedad que necesita la propiedad que falta.

Pasos siguientes

• Obtenga información sobre el uso de los conjuntos de escalado de máquinas virtuales con la extensión DSC de Azure.
• Encuentre más detalles sobre la administración segura de credenciales de DSC.
• Obtenga una introducción al controlador de la extensión DSC de Azure.
• Para obtener más información sobre DSC de PowerShell, vaya al centro de documentación de PowerShell.