Compartir a través de

Cambios en el comportamiento de Desired State Configuration de PowerShell para la configuración de la máquina

  • Artículo

Antes de comenzar, es una buena idea leer la información general de la configuración de la máquina.

Hay disponible un tutorial de vídeo de este documento.

La configuración de la máquina usa Desired State Configuration de PowerShell versión 3 para auditar y configurar máquinas. La configuración de DSC define el estado en que debe encontrarse la máquina. Hay muchas diferencias importantes en el modo de implementación de DSC en la configuración de la máquina.

La configuración de la máquina usa PowerShell 7 multiplataforma

La configuración de la máquina está diseñada para que la experiencia de administración de Windows y Linux pueda ser coherente. En ambos entornos de sistema operativo, alguien con conocimientos de DSC de PowerShell puede crear y publicar configuraciones mediante aptitudes de scripting.

La configuración de la máquina solo usa la versión 3 de PowerShell DSC y no depende de la implementación anterior de DSC para Linux ni de los proveedores nx* incluidos en ese repositorio.

A partir de la versión 1.26.33, la configuración de la máquina funciona en PowerShell 7.1.2 para Windows y PowerShell 7.2, versión preliminar 6 para Linux. A partir de la versión 7.2, el módulo PSDesiredStateConfiguration dejó de formar parte de la instalación de PowerShell y, en su lugar, se instala como un módulo de la Galería de PowerShell.

Varias configuraciones

La configuración de la máquina admite la asignación de varias configuraciones en la misma máquina. No se requieren pasos especiales en el sistema operativo de la extensión de configuración de la máquina. No es necesario establecer configuraciones parciales.

Las dependencias se administran por configuración

Cuando una configuración se empaqueta mediante las herramientas disponibles, las dependencias necesarias para la configuración se incluyen en un archivo .zip. Las máquinas extraen el contenido a una carpeta única para cada configuración. El agente suministrado por la extensión de configuración de máquinas crea una sesión PowerShell dedicada para cada configuración. Usa un $Env:PSModulePath que limita la carga automática de módulos solo a la ruta donde se extrajo el paquete.

Este cambio tiene múltiples ventajas:

  • Es posible usar versiones de módulos distintas para cada configuración, en la misma máquina.
  • Cuando una configuración ya no es necesaria en una máquina, el agente elimina de forma segura toda la carpeta donde se extrajo la configuración. No es necesario administrar dependencias compartidas entre configuraciones.
  • No es necesario administrar varias versiones de ningún módulo en un servicio central.

Los artefactos se administran como paquetes

La característica State Configuration de Azure Automation incluye la administración de artefactos para scripts de configuración y módulos. Una vez publicadas ambas en el servicio, el script puede compilarse en formato MOF. Del mismo modo, el Windows Pull Server también requiere la administración de configuraciones y módulos en la instancia del servicio web. Por el contrario, la extensión DSC tiene un modelo simplificado en el que todos los artefactos se empaquetan juntos y se almacenan en una ubicación accesible desde el equipo de destino mediante una solicitud HTTPS. Azure Blob Storage es la opción más popular para hospedar los artefactos.

La configuración de la máquina solo usa el modelo simplificado en el que todos los artefactos se empaquetan juntos y se accede a ellos desde la máquina de destino a través de HTTPS. No es necesario publicar módulos, scripts ni compilar en el servicio. Un cambio es que el paquete siempre debe incluir un MOF compilado. No es posible incluir un archivo de script en el paquete y compilarlo en la máquina de destino.

Tamaño máximo del paquete de configuración personalizado

En State Configuration de Azure Automation, las configuraciones de DSC tenían un tamaño limitado. La configuración de la máquina admite un tamaño de paquete total de 100 MB antes de la compresión. No hay ningún límite específico en el tamaño del archivo MOF dentro del paquete.

El modo de configuración se establece en el artefacto del paquete

Al crear el paquete de configuración, el modo se establece mediante las siguientes opciones:

  • Audit: verifica el cumplimiento de una máquina. No se realiza ningún cambio.
  • AuditandSet: comprueba y corrige el estado de cumplimiento de la máquina. Se realizan cambios si la máquina no es compatible.

El modo se establece en el paquete y no en el servicio Local Configuration Manager porque cada configuración puede aplicarse con un modo diferente.

Compatibilidad con parámetros a través de Azure Resource Manager

Los parámetros establecidos por la matriz de propiedades configurationParameter en asignaciones de configuración de máquina sobrescriben el texto estático dentro de un archivo MOF de configuración cuando el archivo se almacena en una máquina. Los parámetros permiten la personalización y que un operador controle los cambios desde la API de servicio sin necesidad de ejecutar comandos dentro de la máquina.

Los parámetros de Azure Policy que pasan valores a las asignaciones de configuración de la máquina deben ser de tipo cadena. No es posible pasar matrices mediante parámetros, aunque el recurso de DSC admita matrices.

Conjunto de desencadenadores ajeno a la máquina

En las versiones anteriores de DSC, un desafío era corregir el desfase a gran escala sin una gran cantidad de código personalizado y la dependencia de conexiones remotas de WinRM. La configuración de invitado soluciona este problema. Los usuarios de la configuración de la máquina controlan la corrección de desfase a través de la corrección a petición.

La secuencia incluye el método Get

Cuando la configuración de la máquina audita o configura una máquina, se usa la misma secuencia de eventos para Windows y Linux. El cambio notable en el comportamiento es que el método Get es llamado por el servicio para devolver detalles sobre el estado de la máquina.

  1. El agente primero ejecuta Test para determinar si la configuración se encuentra en el estado correcto.
  2. Si el paquete se establece en Audit, el valor booleano devuelto por la función determina si el estado de Azure Resource Manager para la asignación de invitados debe ser Compliant o NonCompliant.
  3. Si el paquete se establece en AuditandSet, el valor booleano determina si se debe corregir la máquina aplicando la configuración mediante el método Set. Si el método Test devuelve $false, se ejecuta Set. Si Test devuelve $true, entonces Set no se ejecuta.
  4. Por último, el proveedor ejecuta Get para devolver el estado actual de cada configuración, de modo que haya detalles disponibles tanto sobre el motivo por el que una máquina no es compatible como para confirmar que el estado actual es compatible.

Requisitos especiales para Get

El método DSC Get tiene requisitos especiales para la configuración de la máquina que no son necesarios para DSC.

  • La tabla hash que se devuelve debe incluir una propiedad llamada Reasons.
  • La propiedad Reasons debe ser una matriz.
  • Cada elemento de la matriz debe ser una tabla hash con claves denominadas Code y Phrase.
  • No deben devolverse valores distintos de la tabla hash.

El servicio utiliza la propiedad Reasons para estandarizar el modo en que se presenta la información sobre el cumplimiento. Puede considerar cada elemento de Reasons como un mensaje sobre la conformidad o no conformidad del recurso. La propiedad es una matriz porque un recurso podría no cumplir los requisitos por más de un motivo.

El servicio espera las propiedades Code y Phrase. Creación de un recurso personalizado, establezca el texto que desea mostrar como la razón por la que el recurso no es conforme como el valor de Phrase. Code tiene requisitos de formato específicos, por lo que los informes pueden mostrar claramente información sobre el recurso usado para realizar la auditoría. Con esta solución, la configuración de invitado es extensible. Se podría ejecutar cualquier comando, siempre que la salida se pueda devolver como un valor de cadena para la propiedad Phrase.

  • Code (cadena): el nombre del recurso, repetido, y luego un nombre corto sin espacios como identificador del motivo. Estos tres valores deben estar delimitados por signos de dos puntos sin espacios.
    • Un ejemplo sería registry:registry:keynotpresent
  • Phrase (cadena): texto legible para explicar el motivo por el que la configuración no es compatible.
    • Un ejemplo sería The registry key $key isn't present on the machine.
$reasons = @()
$reasons += @{
  Code   = 'Name:Name:ReasonIdentifer'
  Phrase = 'Explain why the setting is not compliant'
}
return @{
    reasons = $reasons
}

Al utilizar herramientas de línea de comandos para obtener información que se devuelve en Get, es posible que la herramienta devuelva resultados que no esperaba. Aunque capture la salida en PowerShell, también podría haberse escrito en un error estándar. Para evitar este problema, considere la posibilidad de redirigir la salida a null.

Clase incrustada de la propiedad Reasons

En los recursos basados en scripts (solo Windows), la clase Reasons se incluye en el archivo MOF del esquema como se muestra a continuación.

[ClassVersion("1.0.0.0")]
class Reason
{
  [Read] String Phrase;
  [Read] String Code;
};

[ClassVersion("1.0.0.0"), FriendlyName("ResourceName")]
class ResourceName : OMI_BaseResource
{
  [Key, Description("Example description")] String Example;
  [Read, EmbeddedInstance("Reason")] String Reasons[];
};

En los recursos basados en clases (Windows y Linux), la clase Reason se incluye en el módulo PowerShell de la siguiente manera. Linux distingue entre mayúsculas y minúsculas, por lo que C en Code y P en Phrase deben ir en mayúsculas.

enum ensure {
  Absent
  Present
}

class Reason {
  [DscProperty()]
  [string] $Code

  [DscProperty()]
  [string] $Phrase
}

[DscResource()]
class Example {

  [DscProperty(Key)]
  [ensure] $ensure

  [DscProperty()]
  [Reason[]] $Reasons

  [Example] Get() {
    # return current current state
  }

  [void] Set() {
    # set the state
  }

  [bool] Test() {
    # check whether state is correct
  }
}

Si el recurso tiene propiedades requeridas, esas propiedades también deben ser devueltas por Get en paralelo con la clase Reason. Si no se incluye Reason, el servicio incluye un comportamiento "catch-all" que compara los valores introducidos en Get y los valores devueltos por Get, y proporciona una comparación detallada como Reason.

Nombres de la configuración

El nombre de la configuración personalizada debe ser coherente en todas partes. Estos elementos deben tener el mismo nombre:

  • El archivo .zip del paquete de contenido
  • El nombre de configuración en el archivo MOF
  • El nombre de asignación de la configuración de máquina en la plantilla de Azure Resource Manager

Ejecución de comandos en Windows PowerShell

La ejecución de módulos de Windows en PowerShell se puede lograr mediante el siguiente patrón en sus recursos DSC. El siguiente patrón establece temporalmente el PSModulePath para ejecutar Windows PowerShell en lugar de PowerShell para descubrir los módulos necesarios disponibles en Windows PowerShell. Este ejemplo es un fragmento adaptado del recurso DSC que se usa en el recurso DSC incorporado Secure Web Server.

Este patrón establece temporalmente la ruta de ejecución de PowerShell para que se ejecute desde Windows PowerShell y descubre el cmdlet necesario, que en este caso es Get-WindowsFeature. Se devuelve la salida del comando y luego se estandariza para los requisitos de compatibilidad. Una vez ejecutado el cmdlet, $env:PSModulePath vuelve a la ruta original.

# The Get-WindowsFeature cmdlet needs to be run through Windows PowerShell
# rather than through PowerShell, which is what the Policy engine runs.
$null = Invoke-Command -ScriptBlock {
    param ([string]$FileName)

    $InitialPSModulePath   = $env:PSModulePath
    $WindowsPSFolder       = "$env:SystemRoot\System32\WindowsPowershell\v1.0"
    $WindowsPSExe          = "$WindowsPSFolder\powershell.exe"
    $WindowsPSModuleFolder = "$WindowsPSFolder\Modules"
    $GetFeatureScriptBlock = {
        param([string]$FileName)

        if (Get-Command -Name Get-WindowsFeature -ErrorAction SilentlyContinue) {
            Get-WindowsFeature -Name Web-Server |
                ConvertTo-Json |
                Out-File $FileName
        } else {
            Add-Content -Path $FileName -Value 'NotServer'
        }
    }

    try {
        # Set env variable to include Windows Powershell modules so we can find
        # the Get-WindowsFeature cmdlet.
        $env:PSModulePath = $WindowsPSModuleFolder
        # Call Windows PowerShell to get the info about the Web-Server feature
        & $WindowsPSExe -command $WindowsFeatureScriptBlock -args $FileName
    } finally {
        # Reset the env variable even if there's an error.
        $env:PSModulePath = $InitialPSModulePath
    }
}

Características comunes de DSC no disponibles durante la versión preliminar pública de la configuración de la máquina

Durante la versión pública preliminar, la configuración de máquina no admite especificar dependencias entre máquinas mediante WaitFor* recursos. No es posible que una máquina inspeccione y espere a que otra alcance un estado antes de progresar.

El control del reinicio no está disponible en la versión preliminar pública de la configuración de la máquina; $global:DSCMachineStatus tampoco está disponible. Las configuraciones no pueden reiniciar un nodo durante la configuración ni cuando esta finaliza.

Problemas conocidos de compatibilidad con los módulos admitidos

El módulo PsDscResources de la Galería de PowerShell y el módulo PSDesiredStateConfiguration que se incluye con Windows están soportados por Microsoft y constituyen un conjunto de recursos de uso común para DSC. Hasta que el módulo PSDscResources se actualice para DSCv3, tenga en cuenta los siguientes problemas de compatibilidad conocidos.

  • No use recursos del módulo PSDesiredStateConfiguration que viene con Windows. En su lugar, use PSDscResources.
  • No use los recursos WindowsFeature, WindowsFeatureSet, WindowsOptionalFeature y WindowsOptionalFeatureSet de PsDscResources. Hay un problema conocido al cargar el módulo DISM en PowerShell 7.1.3 en Windows Server que requiere una actualización.

Los recursos nx*para Linux que se incluyen en el repositorio DSC para Linux se escribieron en una combinación de los lenguajes C y Python. Debido a que el camino a seguir para DSC en Linux es usar PowerShell, los recursos nx* existentes no son compatibles con DSCv3. Hasta que haya disponible un nuevo módulo que contenga recursos admitidos para Linux es necesario crear recursos personalizados.

Coexistencia con la versión 3 y anteriores de DSC

La versión 3 de DSC de la configuración de la máquina puede coexistir con versiones anteriores instaladas en Windows y Linux. Las implementaciones son independientes. Sin embargo, no hay ninguna detección de conflictos entre las versiones de DSC, así que no intente administrar la misma configuración.

Pasos siguientes