Compartir a través de

Recursos de DSC

  • Artículo

En la plataforma de Desired State Configuration de Microsoft (DSC), los recursos de DSC representan una interfaz estandarizada para administrar la configuración de un sistema. Los recursos pueden modelar componentes como genéricos como un archivo o como específico como una configuración de servidor IIS. Los recursos usan una sintaxis declarativa en lugar de imperativa. En lugar de especificar cómo establecer un sistema en el estado deseado, con DSC se especifica cuál es el estado deseado. Los recursos controlan el "cómo" por usted.

Los recursos administran instancias de un componente configurable. Por ejemplo, el PSDscResources/Environment recurso administra variables de entorno. Cada variable de entorno es una instancia diferente del recurso. Cada recurso define un esquema que describe cómo validar y administrar una instancia del recurso.

DSCv3 admite varios tipos de recursos:

  • Un recurso definido con un manifiesto de recursos es un recurso basado en comandos . DSC usa el manifiesto para determinar cómo invocar el recurso y cómo validar las propiedades de la instancia de recurso.
  • Un grupo de recursos es un recurso basado en comandos con una resources propiedad que toma una matriz de instancias de recursos y los procesa. Los grupos de recursos pueden aplicar un control especial a sus instancias de recursos anidadas, como cambiar el usuario al que se ejecutan los recursos.
  • Un proveedor de recursos es un grupo de recursos que permite el uso de recursos no basados en comandos con DSCv3. Por ejemplo, el DSC/PowerShellGroup proveedor de recursos habilita el uso de recursos de DSC implementados en módulos de PowerShell.

Nombres de tipo de recurso

Los recursos se identifican por su nombre de tipo completo. El nombre de tipo se usa para especificar un recurso en los documentos de configuración y como el valor de la --resource marca cuando se usan los dsc resource * comandos .

El nombre de tipo completo de un recurso usa la sintaxis siguiente:

<owner>[.<group>][.<area>]/<name>

Cada recurso debe definir y owner .name Los group componentes y area permiten organizar los recursos en espacios de nombres relacionados, como Microsoft.SqlServer/Database y Microsoft.SqlServer.Database/Role.

Para obtener más información sobre los nombres de tipo y cómo DSC los valida, consulte Referencia de esquema de nombre de tipo completo del recurso de DSC.

Propiedades del recurso

Las propiedades de un recurso son la configuración y las opciones que un usuario puede declarar para administrar una instancia. Los recursos siempre tienen al menos una propiedad. Los recursos definen sus propiedades en su esquema.

Las propiedades son opcionales de forma predeterminada. Los recursos se pueden invocar directamente o declarar en una configuración con solo las propiedades que son relevantes para la tarea o el propósito actual. No es necesario declarar todas las propiedades de una instancia. Las propiedades pueden tener valores predeterminados para su estado deseado.

La mayoría de las propiedades son uno de los tipos básicos:

  • Las propiedades de cadena requieren que el valor de propiedad sea un conjunto de caracteres, como machine.
  • Las propiedades de entero requieren que el valor de propiedad sea un número sin una parte fraccionarcional, como 5.
  • Las propiedades booleanas requieren que el valor de propiedad sea true o false.
  • Las propiedades de matriz requieren que el valor de propiedad sea una lista de elementos. Normalmente, las propiedades de matriz especifican que los valores deben ser de un tipo determinado, como una lista de enteros de código de salida o una lista de rutas de acceso de archivo.

Las propiedades complejas requieren que el valor de propiedad sea un objeto con subpropiedades definidas. Las subpropiedades pueden ser básicas o complejas, pero normalmente son un tipo básico.

Enumeración de recursos

Puede usar DSC para enumerar los recursos disponibles con el dsc resource list comando . DSC busca PATH recursos basados en comandos e invoca proveedores de recursos disponibles para enumerar sus recursos.

De forma predeterminada, el comando devuelve todos los recursos de DSC detectados.

dsc resource list

type                       version tags                        description
----                       ------- ----                        -----------
Test/TestGroup             0.1.0
Microsoft/OSInfo           0.1.0   {os, linux, windows, macos} Returns information about the operating system.
Microsoft.Windows/Registry 0.1.0   {Windows, NT}               Registry configuration provider for the Windows Registry
                                                               This is a test resource.
DSC/PowerShellGroup        0.1.0   {PowerShell}                Resource provider to classic DSC Powershell resources.
DSC/AssertionGroup         0.1.0                               `test` will be invoked for all resources in the supplied configuration.
DSC/ParallelGroup          0.1.0                               All resources in the supplied configuration run concurrently.
                                                               This is a test resource.
DSC/Group                  0.1.0                               All resources in the supplied configuration is treated as a group.

Puede filtrar los resultados por el nombre de tipo, la descripción y las etiquetas de un recurso. Para más información, consulte la lista de recursos de dsc.

Invocación de recursos

Puede invocar recursos directamente con los dsc resource * comandos para administrar una sola instancia a través de las tres operaciones de DSC Get, Test y Set.

Operaciones Get

Cada recurso implementa la operación Get , que recupera el estado real de una instancia de recurso. Use el dsc resource get comando para invocar la operación.

Por ejemplo, puede usar el Microsoft.Windows/Registry recurso para obtener el estado real de un valor de clave del Registro:

'{
    "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
    "valueName": "SystemRoot"
}' | dsc resource get --resource Microsoft.Windows/Registry

actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

Operaciones de prueba

Algunos recursos implementan la operación de prueba . En el caso de los recursos que no implementan la operación de prueba , DSCv3 puede validar el estado de una instancia con una prueba sintética. La prueba sintética es una comparación estricta sin distinción entre mayúsculas y minúsculas de los valores deseados y reales de las propiedades de la instancia. Solo los recursos que tienen requisitos de validación avanzados o complejos deben implementar la propia operación de prueba .

Use el dsc resource test comando para invocar la operación. DSC devuelve datos que incluyen:

  • Estado deseado para la instancia.
  • Estado real de la instancia.
  • Si la instancia está en el estado deseado.
  • Lista de propiedades que no están en el estado deseado.

Por ejemplo, puede probar si existe una clave del Registro específica:

'{
    "keyPath": "HKCU\\key\\that\\does\\not\\exist",
}' | dsc resource test --resource Microsoft.Windows/Registry

desiredState:
  keyPath: HKCU\key\that\does\not\exist
actualState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: ''
  _inDesiredState: false
inDesiredState: false
differingProperties:
- keyPath

Operaciones de conjunto

La mayoría de los recursos implementan la operación Set , que aplica el estado deseado para una instancia. Cuando se usa con DSCv3, la operación Set es idempotente, lo que significa que el recurso solo invoca la operación cuando una instancia no está en el estado deseado. Dado que la operación es idempotente, invocarla repetidamente es la misma que invocarla una vez. El modelo idempotente impide que los efectos secundarios se ejecuten innecesariamente código.

Los recursos que no implementan la operación Set son recursos de aserción . Puede usar recursos de aserción para recuperar y validar el estado de una instancia, pero no puede usarlos para aplicar un estado deseado.

Use el dsc resource set comando para invocar la operación. DSC devuelve datos que incluyen:

  • Estado de la instancia antes de la operación.
  • Estado de la instancia después de la operación.
  • Lista de propiedades que cambió la operación.

Por ejemplo, puede crear una clave del Registro estableciendo el estado deseado para una clave que no existe.

'{
    "keyPath":   "HKCU\\example\\key",
    "valueName": "Example",
    "valueData": { "String": "This is an example." }
}' | dsc resource set --resource Microsoft.Windows/Registry

beforeState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: ''
afterState:
  $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
  keyPath: HKCU\example\key
  valueName: Example
  valueData:
    String: This is an example.
changedProperties:
- keyPath
- valueName
- valueData

Declaración de instancias de recursos

Los documentos de configuración de DSC permiten administrar más de un recurso o instancia de recurso a la vez. Los documentos de configuración declaran una colección de instancias de recursos y su estado deseado. Esto permite modelar estados deseados complejos mediante la composición de diferentes recursos e instancias juntos, como definir una línea base de seguridad para el cumplimiento o la configuración de una granja de servidores web.

Una declaración de instancia de recurso siempre incluye:

  • name - Nombre corto y legible para la instancia que es única en el documento. Este nombre se usa para el registro y ayuda a documentar el propósito de una instancia en el documento.
  • type : el nombre de tipo completo del recurso para identificar el DSC del recurso debe usar para administrar la instancia.
  • properties : estado deseado para la instancia. DSC valida los valores con respecto al esquema de instancia del recurso.

Este fragmento de código de documento de configuración de ejemplo declara una instancia del Microsoft.Windows/Registry recurso.

$schema: https://schemas.microsoft.com/dsc/2023/08/configuration.schema.json
resources:
  - name: example key value
    type: Microsoft.Windows/Registry
    properties:
      keyPath: HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.

Consulte también