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

Artículo
12/18/2024

Nota:

Antes de habilitar la extensión DSC, nos gustaría hacerle saber que ahora hay disponible una versión más reciente de DSC, administrada por una característica denominada configuración de máquina. La característica de configuración de la máquina incluye características del controlador de extensión Desired State Configuration (DSC) y las características más solicitadas por los clientes. La configuración de máquina también incluye compatibilidad con las máquinas híbridas mediante servidores habilitados para Arc.

En este artículo se describe la plantilla de Azure Resource Manager para el controlador de la extensión Desired State Configuration (DSC).

Nota:

Podría encontrar ejemplos de esquema levemente distintos. El cambio en el esquema ocurrió en la versión de octubre de 2016. Para obtener detalles, vea Actualización desde un formato anterior.

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: {
      configurationArguements: {
        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.

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

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:

Nombre de propiedad actual	Equivalente en el esquema anterior
settings.wmfVersion	settings.wmfVersion
settings.configuration.url	settings.ModulesUrl
settings.configuration.script	Primera parte de settings.ConfigurationFunction (antes de \\)
settings.configuration.function	Segunda parte de settings.ConfigurationFunction (después de \\)
settings.configuration.module.name	settings.ModuleSource
settings.configuration.module.version	settings.ModuleVersion
settings.configurationArguments	settings.Properties
settings.configurationData.url	protectedSettings.DataBlobUri (sin token de SAS)
settings.privacy.dataCollection	settings.Privacy.dataCollection
settings.advancedOptions.downloadMappings	settings.advancedOptions.downloadMappings
protectedSettings.configurationArguments	protectedSettings.Properties
protectedSettings.configurationUrlSasToken	settings.SasToken
protectedSettings.configurationDataUrlSasToken	Token de SAS de protectedSettings.DataBlobUri

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.

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

Compartir a través de