Konfigurační dokumenty DSC

Článek
01/11/2024

Na platformě Desired State Configuration (DSC) microsoftu deklarují konfigurační dokumenty DSC požadovaný stav systému jako datové soubory. Konfigurační dokumenty definují kolekci instancí prostředků DSC , které popisují, jaký by měl být požadovaný stav, nikoli způsob, jak systém do tohoto stavu uvést. Prostředky DSC zpracovávají postup pro instance konfiguračního dokumentu.

DSCv3 může zpracovávat konfigurační dokumenty do:

Pomocí příkazu načtěte aktuální stav definovaných dsc config get instancí prostředků.
Pomocí příkazu ověřte, jestli jsou instance v požadovaném dsc config test stavu.
Pomocí příkazu vynucujte dsc config set požadovaný stav instancí.

Konfigurační dokumenty jsou soubory YAML nebo JSON, které obsahují jeden objekt. Vlastnosti objektu definují, jak DSCv3 zpracovává dokument. Vlastnosti nejvyšší úrovně dokumentu jsou:

$schema (povinné) – Definuje kanonický identifikátor URI pro schéma JSON, které dokument dodržuje. DSC to používá k tomu, aby věděla, jak dokument ověřit a interpretovat.
resources (povinné) – Definuje kolekci instancí prostředků, které dokument spravuje.
metadata (volitelné) – Definuje libovolnou sadu poznámek pro dokument. DSC tato data neověřuje ani je přímo nepoužívá. Poznámky můžou obsahovat poznámky, například kdo dokument vytvořil, kdy ho někdo naposledy aktualizoval, nebo jakékoli jiné informace. DSC nepoužívá poznámky. Metadata slouží k použití v dokumentaci nebo jiných nástrojích.
parameters (volitelné) – Definuje sadu možností modulu runtime pro konfiguraci. Na parametry můžou instance prostředků odkazovat, aby se omezily duplicitní definice nebo povolily dynamické hodnoty. Parametry můžou mít výchozí hodnoty a je možné je nastavit při jakékoli operaci konfigurace.
variables (volitelné) – Definuje sadu opakovaně použitelných hodnot pro konfiguraci. Instance prostředků můžou odkazovat na proměnné, aby se snížil počet duplicitních definic.

Poznámka

DSC ještě není implementované pro zpracování parameters vlastností a variables . Mohou být definovány v dokumentu, ale nejsou odkazovány.

Definování konfiguračního dokumentu

Minimálně konfigurační dokument definuje $schema vlastnosti a resources . Vlastnost $schema musí být platný identifikátor URI pro schéma dokumentu konfigurace DSC. Vlastnost resources musí definovat aspoň jednu instanci prostředku DSC.

Příklad:

# example.dsc.config.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
resources:
  - name: example key value
    type: Microsoft.Windows/Registry
    properties:
      keyPath:   HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.

Ukázkový dokument definuje jednu instanci prostředku s názvem example key value. Instance používá Microsoft.Windows/Registry prostředek k deklaraci následujícího požadovaného stavu:

Klíč example\key registru by měl existovat v aktuálním uživatelském podregistru systému.
Klíč example\key registru by měl mít hodnotu s názvem Example.
Hodnota Example by měla být řetězec This is an example.

Ukázkový dokument je deklarativní. Popisuje požadovaný stav, nikoli způsob, jak systém do tohoto stavu uvést. Spoléhá na prostředek, který Microsoft.Windows/Registry zvládá získání, testování a nastavení stavu klíče a hodnoty registru.

Definování instancí prostředků

Jak je znázorněno v předchozím příkladu, konfigurační dokumenty obsahují kolekci instancí prostředků. Instance společně popisují požadovaný stav systému. Konfigurační dokument může obsahovat libovolný počet instancí prostředků.

Deklarace instance prostředku vždy obsahuje:

name – Krátký, lidsky čitelný název instance, který je v dokumentu jedinečný. Tento název se používá pro protokolování a pomáhá popsat účel instance.
type – Plně kvalifikovaný název typu prostředku, který by DSC měl použít ke správě instance.
properties – Požadovaný stav instance. DSC ověří hodnoty ve schématu instance prostředku.

Konfigurační dokumenty nemohou obsahovat stejnou instanci více než jednou. Deklarování stejné instance s různými vlastnostmi vede k cyklům vynucení, kdy každá deklarace vynucuje nekompatibilní stav instance při každém spuštění.

Získání aktuálního stavu konfigurace

Příkaz dsc config get načte aktuální stav instancí prostředků definovaných v dokumentu konfigurace. DSC také shromažďuje všechny zprávy vysílané prostředky během operace a označuje, jestli některý z prostředků vyvolal chybu.

cat ./example.config.dsc.yaml | dsc config get

results:
- name: example key value
  type: Microsoft.Windows/Registry
  result:
    actualState:
      $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
      keyPath: ''
messages: []
hadErrors: false

Testování konfigurace

Příkaz dsc config test porovná aktuální stav instancí prostředků s jejich požadovaným stavem. Výsledek pro každou instanci zahrnuje:

Požadovaný stav instance.
Skutečný stav instance.
Určuje, jestli je instance v požadovaném stavu.
Seznam vlastností, které jsou mimo požadovaný stav, pokud existují.

DSC také shromažďuje všechny zprávy vysílané prostředky během operace a označuje, jestli některý z prostředků vyvolal chybu.

cat ./example.config.dsc.yaml | dsc config test

results:
- name: example key value
  type: Microsoft.Windows/Registry
  result:
    desiredState:
      valueData:
        String: This is an example.
      keyPath: HKCU\example\key
      valueName: Example
    actualState:
      $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
      keyPath: ''
      _inDesiredState: false
    inDesiredState: false
    differingProperties:
    - valueData
    - keyPath
    - valueName
messages: []
hadErrors: false

Vynucení konfigurace

Příkaz dsc config set vynutí instance prostředků definované v dokumentu konfigurace do požadovaného stavu. Výsledek pro každou instanci zahrnuje:

Stav instance před operací.
Stav instance po operaci.
Které vlastnosti operace změnila, pokud existují.