Prostředky DSC

  • Článek

Na platformě Desired State Configuration (DSC) microsoftu představují prostředky DSC standardizované rozhraní pro správu nastavení systému. Prostředky můžou modelovat komponenty tak obecné jako soubor nebo specifické jako nastavení serveru služby IIS. Prostředky používají spíše deklarativní syntaxi než imperativní. Místo toho, abyste určili , jak nastavit systém na požadovaný stav, v DSC určíte, jaký je požadovaný stav. Prostředky zpracují "jak" za vás.

Prostředky spravují instance konfigurovatelné komponenty. Prostředek například PSDscResources/Environment spravuje proměnné prostředí. Každá proměnná prostředí je jinou instancí prostředku. Každý prostředek definuje schéma, které popisuje, jak ověřit a spravovat instanci prostředku.

DSCv3 podporuje několik druhů prostředků:

  • Prostředek definovaný pomocí manifestu prostředků je prostředek založený na příkazech . DSC pomocí manifestu určí, jak vyvolat prostředek a jak ověřit vlastnosti instance prostředku.
  • Skupina prostředků je prostředek založený na příkazech s resources vlastností, která přebírá pole instancí prostředků a zpracovává je. Skupiny prostředků můžou u vnořených instancí prostředků používat speciální zpracování, jako je například změna uživatele, pod jakým se prostředky spouští.
  • Poskytovatel prostředků je skupina prostředků, která umožňuje použití prostředků, které nejsou založené na příkazech, s DSCv3. Poskytovatel prostředků například DSC/PowerShellGroup umožňuje použití prostředků DSC implementovaných v modulech PowerShellu.

Názvy typů prostředků

Prostředky se identifikují podle plně kvalifikovaného názvu typu. Název typu se používá k určení prostředku v dokumentech konfigurace a jako hodnota příznaku --resource při použití dsc resource * příkazů.

Plně kvalifikovaný název typu prostředku používá následující syntaxi:

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

Každý prostředek musí definovat a ownername. Komponenty group a area umožňují uspořádání prostředků do souvisejících oborů názvů, jako jsou Microsoft.SqlServer/Database a Microsoft.SqlServer.Database/Role.

Další informace o názvech typů a o tom, jak je DSC ověřuje, najdete v tématu Referenční informace o schématu plně kvalifikovaného názvu typu prostředku DSC.

Vlastnosti prostředku

Vlastnosti prostředku jsou nastavení a možnosti, které může uživatel deklarovat pro správu instance. Prostředky mají vždy alespoň jednu vlastnost. Prostředky definují své vlastnosti ve schématu.

Vlastnosti jsou ve výchozím nastavení volitelné. Zdroje lze vyvolat přímo nebo deklarovat v konfiguraci pouze s vlastnostmi, které jsou relevantní pro aktuální úlohu nebo účel. Nemusíte deklarovat každou vlastnost instance. Vlastnosti můžou mít výchozí hodnoty pro požadovaný stav.

Většina vlastností je jedním ze základních typů:

  • Vlastnosti řetězce vyžadují, aby hodnota vlastnosti byla sada znaků, například machine.
  • Celočíselné vlastnosti vyžadují, aby hodnota vlastnosti byla číslo bez desetinné části, například 5.
  • Logické vlastnosti vyžadují, aby hodnota vlastnosti byla buď true , nebo false.
  • Vlastnosti pole vyžadují, aby hodnota vlastnosti byla seznamem položek. Vlastnosti pole obvykle určují, že hodnoty musí být určitého typu, například seznam celých čísel ukončovací kód nebo seznam cest k souborům.

Složité vlastnosti vyžadují, aby hodnota vlastnosti byla objektem s definovanými dílčími vlastnostmi. Dílčí vlastnosti můžou být základní nebo složité, ale obvykle se jedná o základní typ.

Výpis prostředků

Pomocí příkazu DSC můžete zobrazit seznam dostupných prostředků dsc resource list . DSC vyhledá PATH prostředky založené na příkazech a vyvolá dostupné poskytovatele prostředků, aby vypíše jejich prostředky.

Ve výchozím nastavení příkaz vrátí všechny zjištěné prostředky DSC.

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.

Výsledky můžete filtrovat podle názvu, popisu a značek typu prostředku. Další informace najdete v seznamu prostředků dsc.

Vyvolání prostředků

Prostředky můžete volat přímo pomocí dsc resource * příkazů pro správu jedné instance prostřednictvím tří operací Get, Test a Set DSC.

Získání operací

Každý prostředek implementuje operaci Get , která načte skutečný stav instance prostředku. dsc resource get K vyvolání operace použijte příkaz .

Prostředek můžete například použít Microsoft.Windows/Registry k získání skutečného stavu pro hodnotu klíče registru:

'{
    "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

Testovací operace

Některé prostředky implementují testovací operaci. U prostředků, které neimplementují testovací operaci, může DSCv3 ověřit stav instance pomocí syntetického testu. Syntetický test je přesné porovnání požadovaných a skutečných hodnot pro vlastnosti instance, které nerozlišují malá a velká písmena. Pouze prostředky, které mají pokročilé nebo složité požadavky na ověření, musí implementovat samotné testovací operace.

dsc resource test K vyvolání operace použijte příkaz . DSC vrací data, která zahrnují:

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

Můžete například otestovat, jestli existuje konkrétní klíč registru:

'{
    "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

Operace se sadami

Většina prostředků implementuje operaci Set , která vynucuje požadovaný stav instance. Při použití s DSCv3 je operace Setidempotentní, což znamená, že prostředek vyvolá operaci pouze v případě, že instance není v požadovaném stavu. Vzhledem k tomu, že je operace idempotentní, opakované vyvolání je stejné jako vyvolání jednou. Idempotentní model zabraňuje zbytečnému spuštění kódu vedlejšími účinky.

Prostředky, které neimplementují operaci Set , jsou prostředky kontrolního výrazu . Prostředky kontrolního výrazu můžete použít k načtení a ověření stavu instance, ale nemůžete je použít k vynucení požadovaného stavu.

dsc resource set K vyvolání operace použijte příkaz . DSC vrací data, která zahrnují:

  • Stav instance před operací.
  • Stav instance po operaci.
  • Seznam vlastností, které operace změnila.

Můžete například vytvořit klíč registru nastavením požadovaného stavu pro klíč, který neexistuje.

'{
    "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

Deklarace instancí prostředků

Dokumenty o konfiguraci DSC umožňují spravovat více než jeden prostředek nebo instanci prostředku najednou. Dokumenty konfigurace deklarují kolekci instancí prostředků a jejich požadovaný stav. Díky tomu je možné modelovat složité požadované stavy tak, že dohromady sestavíte různé prostředky a instance, jako je definování standardních hodnot zabezpečení pro dodržování předpisů nebo nastavení pro webovou farmu.

Deklarace instance prostředku vždy obsahuje:

  • name – Krátký, pro člověka čitelný název instance, který je v dokumentu jedinečný. Tento název se používá pro protokolování a pomáhá dokumentovat účel instance v dokumentu.
  • type – Plně kvalifikovaný název typu pro prostředek k identifikaci 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.

Tento příklad fragmentu konfiguračního Microsoft.Windows/Registry dokumentu deklaruje instanci prostředku.

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

Viz také