Creación de definiciones de directivas de configuración de máquina personalizadas

  • Artículo

Antes de comenzar, es aconsejable leer la página de información general de la configuración de máquina y los detalles sobre las opciones de corrección para la configuración de máquina.

Importante

Se requiere la extensión de configuración de la máquina para máquinas virtuales de Azure. Para implementar la extensión a gran escala en todas las máquinas, asigne la iniciativa de directiva siguiente: Deploy prerequisites to enable machine configuration policies on virtual machines

Para usar paquetes de configuración de máquina que aplican configuraciones, se requiere la versión de la extensión de configuración de invitado de máquina virtual de Azure 1.26.24 o posterior, o el agente de Arc 1.10.0 o posterior.

Las definiciones de directiva de configuración de máquinas personalizadas que usan AuditIfNotExists o DeployIfNotExists están en estado de compatibilidad con disponibilidad general (GA).

Realice los pasos siguientes para crear sus propias directivas de auditoría del cumplimiento o administración del estado de las máquinas de Azure o habilitadas para Arc.

Instalación de PowerShell 7 y módulos de PowerShell necesarios

En primer lugar, configure un entorno de creación de configuración de máquina para instalar la versión necesaria de PowerShell para el sistema operativo y el módulo GuestConfiguration.

Creación y publicación de un artefacto de paquete de configuración de máquina

Si aún no lo ha hecho, cree y publique un paquete de configuración de máquina personalizado siguiendo los pasos descritos en Creación de artefactos de paquetes de configuración de máquina personalizados. A continuación, valide el paquete en el entorno de desarrollo siguiendo los pasos descritos en Cómo probar los artefactos del paquete de configuración de máquina.

Nota:

El código de ejemplo de este artículo hace referencia a la variable $contentUri. Si está usando la misma sesión de PowerShell que en los tutoriales anteriores para crear y probar los artefactos de su paquete, es posible que esa variable ya tenga el URI de su paquete.

Si no tiene la variable $contentUri establecida en el URI de su paquete en su sesión de PowerShell, deberá establecerla. Este ejemplo usa la cadena de conexión de una cuenta de almacenamiento y el cmdlet New-AzStorageContext para crear un contexto de almacenamiento. Después obtiene el blob de almacenamiento del paquete publicado y usa las propiedades de ese objeto para obtener el URI del contenido.

$connectionString = '<storage-account-connection-string>'
$context = New-AzStorageContext -ConnectionString $connectionString
$getParams = @{
    Context   = $context
    Container = '<container-name>'
    Blob      = '<published-package-file-name>'
}
$blob = Get-AzStorageBlob @getParams
$contentUri = $blob.ICloudBlob.Uri.AbsoluteUri

Requisitos de directivas para la configuración de máquina

La sección metadatos de la definición de directiva debe incluir dos propiedades para que el servicio de configuración de máquina automatice el aprovisionamiento y la generación de informes de las asignaciones de la configuración de invitado. La propiedad categoría debe establecerse en Guest Configuration y una sección denominada guestConfiguration debe contener información sobre la asignación de la configuración de máquina. El cmdlet New-GuestConfigurationPolicy crea este texto automáticamente.

En el ejemplo siguiente se muestra la sección metadatos que New-GuestConfigurationPolicy crea automáticamente.

"metadata": {
    "category": "Guest Configuration",
    "guestConfiguration": {
        "name": "test",
        "version": "1.0.0",
        "contentType": "Custom",
        "contentUri": "CUSTOM-URI-HERE",
        "contentHash": "CUSTOM-HASH-VALUE-HERE",
        "configurationParameter": {}
    }
}

Si el efecto de definición se establece en DeployIfNotExists, entonces la sección debe contener detalles de implementación sobre una asignación de configuración de máquina. El cmdlet New-GuestConfigurationPolicy crea este texto automáticamente.

Creación de una definición de Azure Policy

Una vez que se ha creado y cargado un paquete de directivas personalizadas de configuración de máquina, cree la definición de la directiva de configuración de máquina. El cmdlet New-GuestConfigurationPolicy toma un paquete de directivas personalizado y crea una definición de directivas.

El parámetro PolicyId de New-GuestConfigurationPolicy requiere una cadena única. Se requiere usar un identificador único global (GUID). Para las nuevas definiciones, genere un nuevo GUID mediante el cmdlet New-GUID. Al realizar actualizaciones en la definición, use la misma cadena única para PolicyId para asegurarse de que se actualiza la definición correcta.

Parámetros del cmdlet New-GuestConfigurationPolicy:

  • PolicyId: un GUID.
  • ContentUri: URI de HTTP(S) público del paquete de contenido de configuración de máquina.
  • DisplayName: Nombre para mostrar de la directiva.
  • Descripción: Descripción de la directiva.
  • Parámetro: parámetros de directiva proporcionados en una tabla hash.
  • PolicyVersion: versión de la directiva.
  • Ruta de acceso: Ruta de acceso de destino donde se crean las definiciones de directiva.
  • Plataform: plataforma de destino (Windows/Linux) para la directiva de configuración de máquina y el paquete de contenido.
  • Modo: (distingue mayúsculas de minúsculas: ApplyAndMonitor, ApplyAndAutoCorrect, Audit) elija si la directiva debe auditar o implementar la configuración. El valor predeterminado es Audit.
  • Tag agrega uno o varios filtros de etiquetas a la definición de directiva.
  • Category establece el campo de metadatos de categoría en la definición de directiva.

Para obtener más información sobre el parámetro Mode, consulte la página Configuración de las opciones de corrección para la configuración de máquina.

Cree una definición de directiva que realice una auditoría mediante un paquete de configuración personalizado en una ruta de acceso especificada:

$PolicyConfig      = @{
  PolicyId      = '_My GUID_'
  ContentUri    = $contentUri
  DisplayName   = 'My audit policy'
  Description   = 'My audit policy'
  Path          = './policies/auditIfNotExists.json'
  Platform      = 'Windows'
  PolicyVersion = 1.0.0
}

New-GuestConfigurationPolicy @PolicyConfig

Cree una definición de directiva que implemente una configuración mediante un paquete de configuración personalizado en una ruta de acceso especificada:

$PolicyConfig2      = @{
  PolicyId      = '_My GUID_'
  ContentUri    = $contentUri
  DisplayName   = 'My deployment policy'
  Description   = 'My deployment policy'
  Path          = './policies/deployIfNotExists.json'
  Platform      = 'Windows'
  PolicyVersion = 1.0.0
  Mode          = 'ApplyAndAutoCorrect'
}

New-GuestConfigurationPolicy @PolicyConfig2

La salida del cmdlet devuelve un objeto que contiene el nombre para mostrar de la definición y la ruta de acceso de los archivos de directiva. Los archivos JSON de definición que crean definiciones de directiva de auditoría se denominan auditIfNotExists.json y los archivos que crean definiciones de directiva para aplicar configuraciones, deployIfNotExists.json.

Filtrado de directivas de configuración de máquina mediante etiquetas

De forma opcional, las definiciones de directiva que crean los cmdlets en el módulo GuestConfiguration pueden incluir un filtro para las etiquetas. El parámetro Tag de New-GuestConfigurationPolicy admite una matriz de tablas hash que contiene entradas de etiquetas individuales. Las etiquetas se agregan a la sección if de la definición de directiva y no se pueden modificar mediante una asignación de directiva.

A continuación se muestra un fragmento de código de ejemplo de una definición de directiva que filtra por etiquetas.

"if": {
  "allOf" : [
    {
      "allOf": [
        {
          "field": "tags.Owner",
          "equals": "BusinessUnit"
        },
        {
          "field": "tags.Role",
          "equals": "Web"
        }
      ]
    },
    {
      // Original machine configuration content
    }
  ]
}

Uso de parámetros en definiciones de directivas de configuración de máquina personalizadas

La configuración de máquina admite la invalidación de propiedades de una configuración DSC en tiempo de ejecución. Esta característica significa que los valores del archivo MOF del paquete no tienen que considerarse estáticos. Los valores de invalidación se proporcionan mediante Azure Policy y no cambian el modo en que se crean o compilan las configuraciones DSC.

La configuración de máquina admite los siguientes tipos de valor para los parámetros:

  • String
  • Booleano
  • Doble
  • Float

Los cmdlets New-GuestConfigurationPolicy e Get-GuestConfigurationPackageComplianceStatus incluyen un parámetro denominado Parámetros. Este parámetro toma una definición de tabla hash que incluye todos los detalles sobre cada parámetro y crea las secciones necesarias de cada archivo que se usa para crear la definición de Azure Policy.

En el ejemplo siguiente se crea una definición de directiva para auditar un servicio que el usuario selecciona de una lista en el momento de la asignación de la directiva.

# This DSC resource definition...
Service 'UserSelectedNameExample' {
    Name   = 'ParameterValue'
    Ensure = 'Present'
    State  = 'Running'
}

# ...can be converted to a hash table:
$PolicyParameterInfo     = @(
  @{
    # Policy parameter name (mandatory)
    Name                 = 'ServiceName'
    # Policy parameter display name (mandatory)
    DisplayName          = 'windows service name.'
    # Policy parameter description (optional)
    Description          = 'Name of the windows service to be audited.'
    # DSC configuration resource type (mandatory)
    ResourceType         = 'Service'
    # DSC configuration resource id (mandatory)
    ResourceId           = 'UserSelectedNameExample'
    # DSC configuration resource property name (mandatory)
    ResourcePropertyName = 'Name'
    # Policy parameter default value (optional)
    DefaultValue         = 'winrm'
    # Policy parameter allowed values (optional)
    AllowedValues        = @('BDESVC','TermService','wuauserv','winrm')
  })

# ...and then passed into the `New-GuestConfigurationPolicy` cmdlet
$PolicyParam = @{
  PolicyId      = 'My GUID'
  ContentUri    = $contentUri
  DisplayName   = 'Audit Windows Service.'
  Description   = "Audit if a Windows Service isn't enabled on Windows machine."
  Path          = '.\policies\auditIfNotExists.json'
  Parameter     = $PolicyParameterInfo
  PolicyVersion = 1.0.0
}

New-GuestConfigurationPolicy @PolicyParam

Publicación de la definición de Azure Policy

Por último, puede publicar las definiciones de directivas con el cmdlet New-AzPolicyDefinition. Los comandos siguientes publican la directiva de configuración de máquina en el centro de directivas.

Para ejecutar el comando New-AzPolicyDefinition, necesita acceso para crear definiciones de directivas en Azure. Los requisitos de autorización específicos se documentan en la página Información general de Azure Policy. El rol integrado recomendado es Resource Policy Contributor.

New-AzPolicyDefinition -Name 'mypolicydefinition' -Policy '.\policies\auditIfNotExists.json'

O bien, si la directiva es una implementación porque no existe una directiva (DINE), use este comando:

New-AzPolicyDefinition -Name 'mypolicydefinition' -Policy '.\policies\deployIfNotExists.json'

Con la definición de directiva creada en Azure, el último paso es asignar la definición. Consulte cómo asignar la definición con el portal, la CLI de Azure y Azure PowerShell.

Ciclo de vida de la directiva

Si desea publicar una actualización de la definición de directiva, realice el cambio en el paquete de configuración de invitado y en los detalles de la definición de Azure Policy.

Nota

La propiedad version de la asignación de configuración de máquina solo afecta a los paquetes hospedados por Microsoft. El procedimiento recomendado para el control de versiones del contenido personalizado es incluir la versión en el nombre de archivo.

En primer lugar, al ejecutar New-GuestConfigurationPackage, especifique un nombre para el paquete que lo haga único con respecto a las versiones anteriores. Puede incluir un número de versión en el nombre, como PackageName_1.0.0. El número de este ejemplo solo se usa para hacer que el paquete sea único, no para especificar que el paquete sea más reciente o más antiguo que otros paquetes.

En segundo lugar, actualice los parámetros que se usan con el cmdlet New-GuestConfigurationPolicy después de cada una de las explicaciones siguientes.

  • Versión: al ejecutar el cmdlet New-GuestConfigurationPolicy, debe especificar un número de versión mayor que el que está publicado actualmente.
  • contentUri: al ejecutar el cmdlet New-GuestConfigurationPolicy, debe especificar un URI para la ubicación del paquete. La inclusión de una versión del paquete en el nombre de archivo garantiza que el valor de esta propiedad cambie en cada versión.
  • contentHash: el cmdlet New-GuestConfigurationPolicy actualiza esta propiedad automáticamente. Es un valor hash del paquete que creó New-GuestConfigurationPackage. La propiedad debe ser correcta para el archivo .zip que se publica. Si solo se actualiza la propiedad contentUri, la extensión rechaza el paquete de contenido.

La manera más fácil de publicar un paquete actualizado es repetir el proceso que se describe en este artículo y especificar un número de versión actualizado. Este proceso garantiza que todas las propiedades se hayan actualizado correctamente.

Pasos siguientes