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

Ejemplo de Bicep para una máquina virtual

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

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

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

Para obtener los detalles más recientes sobre la creación de plantillas que implementan extensiones para virtual Machine Scale Sets, consulte el documento Microsoft.Compute virtualMachineScaleSets

La extensión DSC hereda las propiedades de extensión predeterminadas. Para más información, consulte la clase VirtualMachineScaleSetExtension.

Configuración frente a 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 enumeradas en protectedSettings se cifran con un certificado y no se muestran 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"
        }
    }
}

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

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}") Los únicos valores posibles son '', 'Enable' y 'Disable'. "WmfVersion is '{0}'. ("WmfVersion es '{0}') Los únicos valores posibles son: y 'latest'" (y 'más reciente').

Problema: se proporcionó un valor no permitido.

Solución: cambie el valor no válido por un valor válido.

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}") No es una dirección URL válida"

Problema: una dirección 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 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 requiere 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 necesite 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.