Dela via

DSC-resurser

I Microsofts DSC-plattform (Desired State Configuration) representerar DSC-resurser ett standardiserat gränssnitt för att hantera inställningarna för ett system. Resurser kan modellera komponenter som är så allmänna som en fil eller så specifika som en IIS-serverinställning. Resurser använder en deklarativ syntax i stället för imperativ. I stället för att ange hur ett system ska ställas in på önskat tillstånd anger du med DSC vad det önskade tillståndet är. Resurser hanterar "hur" åt dig.

Resurser hanterar instanser av en konfigurerbar komponent. Resursen PSDscResources/Environment hanterar till exempel miljövariabler. Varje miljövariabel är en annan instans av resursen. Varje resurs definierar ett schema som beskriver hur du verifierar och hanterar en instans av resursen.

DSC stöder flera typer av resurser:

  • En resurs som definieras med ett resursmanifest är en kommandoresurs . DSC använder manifestet för att avgöra hur resursen ska anropas och hur resursinstansens egenskaper ska verifieras.
  • En gruppresurs är en kommandoresurs med en resources egenskap som tar en matris med resursinstanser och bearbetar dem. Gruppresurser kan tillämpa särskild hantering på sina kapslade resursinstanser, till exempel att ändra den användare som resurserna körs som.
  • En adapterresurs är en gruppresurs som gör det möjligt att använda icke-kommandoresurser med DSC. Till exempel kan resurserna och Microsoft.DSC/PowerShellMicrosoft.Windows/WindowsPowerShell adaptern användas med PowerShell DSC-resurser (PSDSC) i DSC, vilket anropar resurserna i PowerShell respektive Windows PowerShell.

Namn på resurstyper

Varje resurs har ett fullständigt kvalificerat typnamn som identifierar resursen. Du använder typnamnet för att ange en resurs i konfigurationsdokument och som värde för flaggan --resource när du dsc resource * använder kommandona.

Det fullständigt kvalificerade typnamnet för en resurs använder följande syntax:

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

Varje resurs måste definiera en owner och en name. Komponenterna group och area gör det möjligt att organisera resurser i relaterade namnrymder, som Microsoft.SqlServer/Database och Microsoft.SqlServer.Database/Role.

Mer information om typnamn och hur DSC verifierar dem finns i schemareferens för fullständigt kvalificerat typnamn i DSC-resursen.

Resursegenskaper

Egenskaperna för en resurs är de inställningar och alternativ som en användare kan deklarera för att hantera en instans. Resurser har alltid minst en egenskap. Resurser definierar sina egenskaper i instansschemat.

Egenskaper är valfria som standard. Resurser kan anropas direkt eller deklareras i en konfiguration med endast de egenskaper som är relevanta för den aktuella uppgiften eller syftet. Du behöver inte deklarera varje egenskap för en instans. Egenskaper kan ha standardvärden för önskat tillstånd.

De flesta egenskaper är en av de grundläggande typerna:

  • Strängegenskaper kräver att egenskapsvärdet är en uppsättning tecken, till exempel machine.
  • Heltalsegenskaper kräver att egenskapsvärdet är ett tal utan en bråkdel, till exempel 5.
  • Booleska egenskaper kräver att egenskapsvärdet är antingen true eller false.
  • Matrisegenskaper kräver att egenskapsvärdet är en lista med objekt. Vanligtvis anger matrisegenskaper att värdena måste vara av en viss typ, till exempel en lista med slutkodsheltal eller en lista med filsökvägar.

Komplexa egenskaper kräver att egenskapsvärdet är ett objekt med definierade underegenskaper. Underegenskaperna kan vara grundläggande eller komplexa, men de är vanligtvis av grundläggande typ.

Resurser kan definiera sina egenskaper som skrivskyddade eller skrivskyddade:

  • En skrivskyddad resursegenskap definierar metadata om en instans som resursen kan hämta men som en användare inte kan ange direkt. Du kan inte ange skrivskyddade egenskaper i önskat tillstånd för en instans. Exempel på skrivskyddade egenskaper är den senaste gången en fil ändrades eller vem som har skapat ett installerat programpaket.
  • En skrivskyddad resursegenskap definierar ett värde som resursen använder under en resursåtgärd, men som inte kan returneras för det aktuella tillståndet för en instans. Exempel på skrivskyddade egenskaper är autentiseringsuppgifter som används för att autentisera under en resursåtgärd och den tillfälliga katalog som ska användas när du hämtar och packar upp ett fjärrarkiv.

DSC definierar en uppsättning kanoniska resursegenskaper som anger att en resurs deltar i den delade semantik som DSC-motorn tillhandahåller. Till exempel anger alla resurser som innehåller den _exist kanoniska egenskapen i sitt instansschema att resursen hanterar instanser som kan skapas och tas bort. Om en resurs har den _exist kanoniska egenskapen och delete funktionen kan DSC hantera anrop av borttagningsåtgärden i stället för Set när det önskade tillståndet anger att instansen inte ska finnas. Mer information om tillgängliga kanoniska egenskaper finns i kanoniska DSC-egenskaper.

Lista resurser

Du kan använda DSC för att lista tillgängliga resurser med kommandot dsc resource list . DSC söker efter PATH kommandobaserade resurser och anropar tillgängliga resursprovidrar för att lista sina resurser.

Som standard returnerar kommandot varje identifierad DSC-resurs.

dsc resource list

Type                                        Kind      Version  Capabilities  RequireAdapter  Description
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Microsoft.DSC.Debug/Echo                    Resource  1.0.0    gs--t---
Microsoft.DSC.Transitional/RunCommandOnSet  Resource  0.1.0    gs------                      Takes a single-command line to execute on DSC set operation
Microsoft.DSC/Assertion                     Group     0.1.0    gs--t---                      `test` will be invoked for all resources in the supplied configuration.
Microsoft.DSC/Group                         Group     0.1.0    gs--t---                      All resources in the supplied configuration is treated as a group.
Microsoft.DSC/Include                       Importer  0.1.0    gs--t---                      Allows including a configuration file with optional parameter file.
Microsoft.DSC/PowerShell                    Adapter   0.1.0    gs--t-e-                      Resource adapter to classic DSC Powershell resources.
Microsoft.Windows/RebootPending             Resource  0.1.0    g-------                      Returns info about pending reboot.
Microsoft.Windows/Registry                  Resource  0.1.0    gs-w-d--                      Manage Windows Registry keys and values
Microsoft.Windows/WMI                       Adapter   0.1.0    g-------                      Resource adapter to WMI resources.
Microsoft.Windows/WindowsPowerShell         Adapter   0.1.0    gs--t---                      Resource adapter to classic DSC Powershell resources in Windows PowerShell.
Microsoft/OSInfo                            Resource  0.1.0    g-----e-                      Returns information about the operating system.
Microsoft/Process                           Resource  0.1.0    gs--t-e-                      Returns information about running processes.

Du kan filtrera resultaten efter en resurs typnamn, beskrivning och taggar. Mer information finns i dsc-resurslista

Anropa resurser

Du kan anropa resurser direkt med kommandona dsc resource * för att hantera en enskild instans via de tre primära DSC-åtgärderna: Get, Test, Set. Om resursen har kapacitet kan du också anropa åtgärderna Exportera eller Ta bort .

Hämta åtgärder

Varje resurs implementerar Get-åtgärden , som hämtar det faktiska tillståndet för en resursinstans. Använd kommandot för att anropa åtgärden dsc resource get .

Du kan till exempel använda Microsoft.Windows/Registry resursen för att hämta det faktiska tillståndet för ett registernyckelvärde:

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

actualState:
  keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
  valueName: SystemRoot
  valueData:
    String: C:\WINDOWS

Teståtgärder

Vissa resurser implementerar teståtgärden . För resurser som inte implementerar teståtgärden kan DSC verifiera en instanss tillstånd med ett syntetiskt test. Det syntetiska testet är en strikt skiftlägesokänslig jämförelse av de önskade och faktiska värdena för instansens egenskaper. Endast resurser som har avancerade eller komplexa valideringskrav behöver implementera teståtgärden själva.

Använd kommandot för att anropa åtgärden dsc resource test . DSC returnerar data som innehåller:

  • Det önskade tillståndet för instansen.
  • Det faktiska tillståndet för instansen.
  • Om instansen är i önskat tillstånd.
  • Listan över egenskaper som inte är i önskat tillstånd.

Du kan till exempel testa om det finns en specifik registernyckel:

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

desiredState:
  keyPath: HKCU\key\that\does\not\exist
  _exist: true
actualState:
  keyPath: HKCU\key\that\does\not\exist
  _exist: false
inDesiredState: false
differingProperties:
- _exist

Ange åtgärder

De flesta resurser implementerar åtgärden Set , som framtvingar önskat tillstånd för en instans. När den används med DSC Set är åtgärden idempotent, vilket innebär att resursen endast anropar åtgärden när en instans inte är i önskat tillstånd. Eftersom åtgärden är idempotent är det samma sak att anropa den upprepade gånger som att anropa den en gång. Den idempotenta modellen förhindrar biverkningar från att köra kod i onödan.

Resurser som inte implementerar åtgärden Set är kontrollresurser . Du kan använda kontrollresurser för att hämta och verifiera tillståndet för en instans, men du kan inte använda dem för att framtvinga ett önskat tillstånd.

Använd kommandot för att anropa åtgärden dsc resource set . DSC returnerar data som innehåller:

  • Tillståndet för instansen före åtgärden.
  • Tillståndet för instansen efter åtgärden.
  • Listan över egenskaper som åtgärden ändrade.

Du kan till exempel skapa en registernyckel genom att ange önskat tillstånd för en nyckel som inte finns.

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

beforeState:
  keyPath: HKCU\example\key
  _exist: false
afterState:
  keyPath: HKCU\example\key
  valueName: Example
  valueData:
    String: This is an example.
changedProperties:
- valueName
- valueData
- _exist

Borttagningsåtgärder

Vissa resurser implementerar borttagningsåtgärden för enkelhetens skull. Med den här åtgärden kan du anropa resursen för att ta bort en instans från systemet.

Använd kommandot för att anropa åtgärden dsc resource delete . När du anropar borttagningsåtgärden DSC returnerar inga utdata om det inte uppstår ett fel.

Du kan till exempel ta bort registret som skapades i exemplet med åtgärden Set :

dsc resource delete --resource Microsoft.Windows/Registry --input '{
    "keyPath":   "HKCU\\example\\key"
}'

Exportera åtgärder

Vissa resurser implementerar exportåtgärden , som returnerar varje instans av resursen i systemet. Den här åtgärden kan hjälpa dig att identifiera hur en dator för närvarande är konfigurerad.

Använd kommandot för att anropa åtgärden dsc resource export . När du anropar exportåtgärden DSC returnerar en matris med resursinstansdefinitioner som du kan kopiera till ett konfigurationsdokument.

Deklarera resursinstanser

DSC-konfigurationsdokument gör det möjligt att hantera mer än en resurs eller resursinstans i taget. Konfigurationsdokument deklarerar en samling resursinstanser och deras önskade tillstånd. Konfigurationsdokument gör det möjligt att modellera komplexa önskade tillstånd genom att sätta samman olika resurser och instanser, till exempel genom att definiera en säkerhetsbaslinje för efterlevnad eller inställningarna för en webbservergrupp.

En resursinstansdeklaration innehåller alltid:

  • name - Ett kort, läsbart namn för den instans som är unik i dokumentet. Det här namnet används för loggning och hjälper till att dokumentera en instanss syfte i dokumentet.
  • type - Det fullständigt kvalificerade typnamnet för resursen för att identifiera resursen som DSC ska använda för att hantera instansen.
  • properties - Det önskade tillståndet för instansen. DSC verifierar värdena mot resursens instansschema.

Det här exempelkonfigurationsdokumentet deklarerar en instans av resursen Microsoft.Windows/Registry .

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

Se även