Dokumentacja schematu typu zasobu DSC

Streszczenie

Określa, czy zasób jest zasobem karty, zasobem grupy, czy zwykłym zasobem.

Metadane

SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json
Type:          string
ValidValues:  [Resource, Adapter, Group, Import]

Opis

DsC obsługuje trzy rodzaje zasobów DSC opartych na poleceniach:

• Resource — wskazuje, że manifest nie jest przeznaczony dla zasobu grupy ani karty.
• Group — wskazuje, że manifest dotyczy zasobu grupy .
• Adapter — wskazuje, że manifest dotyczy zasobu karty .
• Import — wskazuje, że manifest dotyczy zasobu importera .

Jeśli kind nie jest zdefiniowana w manifeście zasobu, rozszerzenie DSC wywnioskuje wartość właściwości. Jeśli właściwość adapter jest zdefiniowana w manifeście zasobu, rozszerzenie DSC wywnioskuje wartość kind jako Adapter. Jeśli właściwość adapter nie jest zdefiniowana, rozszerzenie DSC wywnioskuje wartość kind jako Resource. DsC nie może wywnioskować, czy manifest dotyczy zasobu grupy.

Podczas definiowania zasobu grupy zawsze jawnie zdefiniuj właściwość kind w manifeście jako Group.

Zasoby adaptera

Zasób adaptera udostępnia zasoby nienależące do poleceń dsC. Zawsze mają właściwość resources, która przyjmuje tablicę zagnieżdżonych wystąpień zasobów. Adaptery mogą zapewnić dodatkową kontrolę nad sposobem przetwarzania dostosowanych zasobów.

Zasób karty musi zawsze definiować adaptera i weryfikować właściwości w manifeście zasobu.

Na przykład karta Microsoft.DSC/PowerShell umożliwia korzystanie z zasobów konfiguracji żądanego stanu programu PowerShell (PSDSC) w usłudze DSC. Zasoby PSDSC są publikowane jako składniki modułów programu PowerShell. Nie definiują manifestów zasobów.

Grupowanie zasobów

Zasoby grupy zawsze działają na zagnieżdżonych wystąpieniach zasobów DSC. Zasoby grupy mogą zmieniać sposób przetwarzania zagnieżdżonych wystąpień, takich jak zasób grupy Microsoft.DSC/Assertion.

Zasób grupy musi zawsze definiować właściwość typu w manifeście zasobu.

Zasoby grupy mogą również służyć do łączenia zestawów zasobów na potrzeby przetwarzania, takich jak zasób Microsoft.DSC/Group. Możesz użyć właściwości dependsOn dla wystąpienia zasobu w konfiguracji, aby wskazać zasób grupy zamiast wyliczać każdy zasób na liście.

Zasoby importera

Zasoby importera rozpoznają źródło zewnętrzne dla zestawu zagnieżdżonych wystąpień zasobów DSC. Właściwości zasobu importera definiują sposób znajdowania i rozpoznawania źródła zewnętrznego.

Zasób importera musi zawsze definiować rodzaju i rozpoznawać właściwości w manifeście zasobu.

Na przykład zasób importera Microsoft.DSC/Import rozpoznaje wystąpienia z zewnętrznego dokumentu konfiguracji, umożliwiając tworzenie konfiguracji z wielu plików.

Zagnieżdżone wystąpienia zasobów

Wystąpienia zasobów zadeklarowane w zasobach adaptera i grupy lub rozpoznawane przez zasoby importera są nazywane wystąpieniami zasobów zagnieżdżonych .

W przypadku wystąpień zagnieżdżonych wystąpienie zasobu jest sąsiadujące, jeśli:

• Jest zadeklarowany w tym samym wystąpieniu grupy lub karty.
• Jest on rozpoznawany przez to samo wystąpienie importera.

Wystąpienie zasobu jest zewnętrzne do wystąpienia zagnieżdżonego, jeśli:

• Jest zadeklarowana poza wystąpieniem grupy lub karty
• Jest on rozpoznawany przez inne wystąpienie importera
• Jest on zagnieżdżony wewnątrz sąsiedniej grupy, karty lub wystąpienia importera.

W przypadku wystąpień najwyższego poziomu inne wystąpienia na najwyższym poziomie są sąsiadujące. Wszystkie inne wystąpienia są zewnętrzne.

Rozważmy następujący fragment kodu konfiguracji. Definiuje siedem wystąpień zasobów:

• Na najwyższym poziomie konfiguracja definiuje wystąpienia TopLevelEcho, TopLevelOSInfoi TopLevelGroup.
• Wystąpienie TopLevelGroup definiuje zagnieżdżone wystąpienia NestedEcho i NestedGroup.
• Wystąpienie NestedGroup definiuje zagnieżdżone wystąpienia DeeplyNestedEcho i DeeplyNestedOSInfo.

resources:
- name: TopLevelEcho
  type: Test/Echo
  properties: { output: 'top level instance' }
- name: TopLevelOSInfo
  type: Microsoft/OSInfo
  properties: { }
- name: TopLevelGroup
  type: Microsoft.DSC/Group
  properties:
    $schema:
    resources:
    - name: NestedEcho
      type: Test/Echo
      properties: { output: 'nested instance' }
    - name: NestedGroup
      type: Microsoft.DSC/Group
      properties:
        $schema:
        resources:
        - name: DeeplyNestedEcho
          type: Test/Echo
          properties: { output: 'deeply nested instance' }
        - name: DeeplyNestedOSInfo
          type: Microsoft/OSInfo
          properties: { }

Poniższa macierz definiuje relacje poszczególnych wystąpień w konfiguracji:

	TopLevelEcho	TopLevelOSInfo	TopLevelGroup	ZagnieżdżoneEcho	Zagnieżdżona grupa	DeeplyNestedEcho	DeeplyNestedOSInfo
TopLevelEcho	Jaźń	Przyległy	Przyległy	Zewnętrzny	Zewnętrzny	Zewnętrzny	Zewnętrzny
TopLevelOSInfo	Przyległy	Jaźń	Przyległy	Zewnętrzny	Zewnętrzny	Zewnętrzny	Zewnętrzny
TopLevelGroup	Przyległy	Przyległy	Jaźń	Zewnętrzny	Zewnętrzny	Zewnętrzny	Zewnętrzny
NestedEcho	Zewnętrzny	Zewnętrzny	Zewnętrzny	Jaźń	Przyległy	Zewnętrzny	Zewnętrzny
NestedGroup	Zewnętrzny	Zewnętrzny	Zewnętrzny	Przyległy	Jaźń	Zewnętrzny	Zewnętrzny
DeeplyNestedEcho	Zewnętrzny	Zewnętrzny	Zewnętrzny	Zewnętrzny	Zewnętrzny	Jaźń	Przyległy
DeeplyNestedOSInfo	Zewnętrzny	Zewnętrzny	Zewnętrzny	Zewnętrzny	Zewnętrzny	Przyległy	Jaźń

Odwoływanie się do zagnieżdżonych wystąpień

Zagnieżdżone wystąpienia zasobów mają ograniczenia dotyczące właściwości dependsOn oraz funkcji konfiguracji reference().

1. Możesz odwoływać się tylko do sąsiednich wystąpień. Nie można odwołać się do wystąpienia zagnieżdżonego spoza wystąpienia, które deklaruje je lub rozwiązuje. Nie można użyć odwołania do zasobu spoza grupy, karty lub zasobu importera dla wystąpienia zagnieżdżonego.
2. Dla sąsiednich wystąpień można używać tylko właściwości dependsOn. Należy dodać zależność od grupy, karty lub wystąpienia importera, a nie wystąpienia zagnieżdżonego. Zagnieżdżone wystąpienia nie mogą zależeć od wystąpień zewnętrznych.

W poniższych przykładach pokazano prawidłowe i nieprawidłowe odwołania i zależności. W przykładach użyto zasobu Microsoft.DSC/Group, ale funkcjonalność jest taka sama w przypadku kart i importu zasobów.

Przykład 1 — prawidłowe odwołania i zależności

Ta przykładowa konfiguracja definiuje kilka prawidłowych odwołań i zależności. Definiuje również dwa wystąpienia zasobu Microsoft.DSC/Group, jedno zagnieżdżone wewnątrz drugiego.

Wystąpienie najwyższego poziomu odwołania do zasobu Test/Echo i zależy od wystąpienia najwyższego poziomu zasobu Microsoft/OSInfo. Wystąpienia najwyższego poziomu zasobów Test/Echo i Microsoft/OSInfo zależą od wystąpienia najwyższego poziomu zasobu Microsoft.DSC/Group.

resources:
# The top level echo references and depends on the top-level OSInfo.
# It also depends on the top-level Group.
- name: Top level echo
  type: Test/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Top level OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
# The top level OSInfo depends on the top-level Group.
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
  dependsOn:
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties: # snipped for brevity

Wystąpienie najwyższego poziomu Microsoft.DSC/Group definiuje trzy zagnieżdżone wystąpienia zasobów: Test/Echo, Microsoft/OSInfoi Microsoft.DSC/Group. Podobnie jak na najwyższym poziomie, wystąpienie Test/Echo odwołuje się i zależy od sąsiedniego zagnieżdżonego wystąpieniaMicrosoft/OSInfo i to wystąpienie zależy od sąsiedniego zagnieżdżonego wystąpienia Microsoft.DSC/Group.

# Other top-level instances snipped for brevity
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
    resources:
    # The nested echo references and depends on the adjacent nested OSInfo.
    - name: Nested echo
      type: Test/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Nested OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
    # The nested OSInfo depends on the adjacent nested Group.
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties: # snipped for brevity

Na koniec zagnieżdżone wystąpienie Microsoft.DSC/Group definiuje dwa zagnieżdżone wystąpienia. Głęboko zagnieżdżone wystąpienie odwołań Test/Echo i zależy od głęboko zagnieżdżonego wystąpienia Microsoft/OSInfo.

- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
    resources:
    # Snipped the Test/Echo and Microsoft/OSInfo instances for brevity
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties:
        $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
        resources:
        # The deeply nested echo references and depends on the adjacent
        # deeply nested OSInfo.
        - name: Deeply nested echo
          type: Test/Echo
          properties:
            output:  >-
              [reference(
                resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')
              ).actualState]
          dependsOn:
            - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
        - name: Deeply nested OSInfo
          type: Microsoft.OSInfo
          properties: {}

W każdym przypadku odwołania i zależności dotyczą sąsiednich wystąpień w konfiguracji. Wystąpienia na najwyższym poziomie zależą tylko od innych wystąpień na najwyższym poziomie lub odwołują się do innych wystąpień. Wystąpienia zagnieżdżone w grupie najwyższego poziomu zależą tylko od innych zagnieżdżonych wystąpień w tej samej grupie lub odwołują się do innych zagnieżdżonych wystąpień. Głęboko zagnieżdżone wystąpienia zdefiniowane w zagnieżdżonej grupie zależą tylko od innych głęboko zagnieżdżonych wystąpień w tej samej grupie lub odwołują się do innych głęboko zagnieżdżonych wystąpień.

Łącząc konfigurację, uzyskasz pełny dokument:

# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
# The top level echo references and depends on the top-level OSInfo.
- name: Top level echo
  type: Test/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Top level OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"
# The top level OSInfo depends on the top-level Group.
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
  dependsOn:
    - "[resourceId('Microsoft.DSC/Group', 'Top level group')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
    resources:
    # The nested echo references and depends on the adjacent nested OSInfo.
    - name: Nested echo
      type: Test/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Nested OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
    # The nested OSInfo depends on the adjacent nested Group.
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}
    - name: Nested Group
      type: Microsoft.DSC/Group
      properties:
        $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
        resources:
        # The deeply nested echo references and depends on the adjacent
        # deeply nested OSInfo.
        - name: Deeply nested echo
          type: Test/Echo
          properties:
            output:  >-
              [reference(
                resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')
              ).actualState]
          dependsOn:
            - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
        - name: Deeply nested OSInfo
          type: Microsoft.OSInfo
          properties: {}

Przykład 2 — nieprawidłowe odwołanie i zależność od wystąpienia zagnieżdżonego

Ta przykładowa konfiguracja jest nieprawidłowa, ponieważ wystąpienie najwyższego poziomu odwołania do zasobów Test/Echo i zależy od zagnieżdżonego wystąpienia Microsoft/OSInfo. Zagnieżdżone wystąpienie jest zewnętrzne dla wystąpienia najwyższego poziomu, a nie sąsiadujące.

# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
- name: Top level echo
  type: Test/Echo
  properties:
    output:  >-
      [reference(
        resourceId('Microsoft/OSInfo', 'Nested OSInfo')
      ).actualState]
  dependsOn:
    - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]"
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
    resources:
    - name: Nested OSInfo
      type: Microsoft/OSInfo
      properties: {}

Przykład 3 — nieprawidłowe odwołanie i zależność od wystąpienia zewnętrznego

Ta przykładowa konfiguracja jest nieprawidłowa, ponieważ zagnieżdżone wystąpienie Test/Echo zasobów jest zależne od wystąpienia Microsoft/OSInfo najwyższego poziomu. Wystąpienie najwyższego poziomu jest zewnętrzne dla zagnieżdżonego wystąpienia, a nie sąsiadującego.

# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
- name: Top level OSInfo
  type: Microsoft/OSInfo
  properties: {}
- name: Top level group
  type: Microsoft.DSC/Group
  properties:
    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
    resources:
    - name: Nested echo
      type: Test/Echo
      properties:
        output:  >-
          [reference(
            resourceId('Microsoft/OSInfo', 'Top level OSInfo')
          ).actualState]
      dependsOn:
        - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]"