DSC 资源类型架构参考

2024-06-25

概要

标识资源是适配器资源、组资源还是普通资源。

元数据

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]

描述

DSC 支持三种类型的基于命令的 DSC 资源：

Resource - 指示清单不适用于组或适配器资源。
Group - 指示清单适用于组资源组。
Adapter - 指示清单适用于适配器资源。
Import - 指示清单适用于导入程序资源。

在资源清单中未定义 kind 时，DSC 将推断该属性的值。如果在资源清单中定义了 adapter 属性，DSC 会将 kind 的值推断为 Adapter。如果未定义 adapter 属性，DSC 会将 kind 的值推断为 Resource。 DSC 无法推断清单是否适用于组资源。

定义组资源时，始终将清单中的 kind 属性显式定义为 Group。

适配器资源

适配器资源使基于命令的资源可用于 DSC。它们始终具有一个 resources 属性，该属性采用嵌套资源实例的数组。适配器可以进一步控制调整的资源的处理方式。

适配器资源必须始终定义适配器，并验证资源清单中的属性。

例如，Microsoft.DSC/PowerShell 适配器允许在 DSC 中使用 PowerShell Desired State Configuration （PSDSC）资源。 PSDSC 资源作为 PowerShell 模块的组件发布。它们不定义资源清单。

对资源进行分组

组资源始终在嵌套 DSC 资源实例上运行。组资源可以更改嵌套实例的处理方式，例如 Microsoft.DSC/Assertion 组资源。

组资源必须始终在资源清单中定义类型属性。

还可以使用组资源将资源集捆绑在一起进行处理，例如 Microsoft.DSC/Group 资源。可以使用配置中的资源实例的 dependsOn 属性指向组资源，而不是枚举列表中的每个资源。

导入程序资源

导入程序资源将外部源解析为一组嵌套的 DSC 资源实例。导入程序资源的属性定义如何查找和解析外部源。

导入程序资源必须始终定义类型，并解析资源清单中的属性。

例如，Microsoft.DSC/Import 导入程序资源从外部配置文档解析实例，使你能够从多个文件撰写配置。

嵌套资源实例

适配器和组资源中声明的资源实例或由导入程序资源解析的资源实例称为 嵌套资源实例。

对于嵌套实例，如果以下情况，则资源实例相邻：

它在同一组或适配器实例中声明。
它由同一导入程序实例解析。

如果以下情况下，资源实例 嵌套实例的外部：

它在组或适配器实例外部声明
它由其他导入程序实例解析
它嵌套在相邻的组、适配器或导入程序实例内。

对于顶级实例，顶层的其他实例相邻。所有其他实例都是外部实例。

请考虑以下配置代码片段。它定义七个资源实例：

在顶层，配置定义 TopLevelEcho、TopLevelOSInfo和 TopLevelGroup 实例。
TopLevelGroup 实例定义嵌套实例 NestedEcho 和 NestedGroup。
NestedGroup 实例定义嵌套实例 DeeplyNestedEcho 和 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: { }

以下矩阵定义配置中每个实例的关系：

	TopLevelEcho	TopLevelOSInfo	TopLevelGroup	NestedEcho	NestedGroup	DeeplyNestedEcho	DeeplyNestedOSInfo
TopLevelEcho	自我	邻近的	邻近的	外部	外部	外部	外部
TopLevelOSInfo	邻近的	自我	邻近的	外部	外部	外部	外部
TopLevelGroup	邻近的	邻近的	自我	外部	外部	外部	外部
NestedEcho	外部	外部	外部	自我	邻近的	外部	外部
NestedGroup	外部	外部	外部	邻近的	自我	外部	外部
DeeplyNestedEcho	外部	外部	外部	外部	外部	自我	邻近的
DeeplyNestedOSInfo	外部	外部	外部	外部	外部	邻近的	自我

引用嵌套实例

嵌套资源实例对 dependsOn 属性和 reference（）配置函数有限制。

只能引用相邻实例。不能从声明或解析它的实例外部引用嵌套实例。不能对嵌套实例的组、适配器或导入程序资源之外的资源使用引用。
只能对相邻实例使用 dependsOn 属性。必须添加组、适配器或导入程序实例的依赖项，而不是嵌套实例。嵌套实例不能依赖于外部实例。

以下示例显示了有效引用和无效的引用和依赖项。这些示例使用 Microsoft.DSC/Group 资源，但适配器和导入资源的功能相同。

示例 1 - 有效的引用和依赖项

此示例配置定义了多个有效的引用和依赖项。它还定义了 Microsoft.DSC/Group 资源的两个实例，一个实例嵌套在另一个资源内。

Test/Echo 资源引用的顶级实例，取决于 Microsoft/OSInfo 资源的顶级实例。 Test/Echo 和 Microsoft/OSInfo 资源的顶级实例都依赖于 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

Microsoft.DSC/Group 的顶级实例定义了三个嵌套资源实例：Test/Echo、Microsoft/OSInfo和 Microsoft.DSC/Group。与顶层一样，Test/Echo 实例引用并依赖于相邻的嵌套Microsoft/OSInfo 实例，该实例依赖于相邻的嵌套 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

最后，Microsoft.DSC/Group 的嵌套实例定义两个嵌套实例。 Test/Echo 引用的深度嵌套实例，取决于 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: {}

在每种情况下，引用和依赖项都位于配置中的相邻实例。顶级实例仅依赖于或引用顶层的其他实例。嵌套在顶级组中的实例仅依赖于或引用同一组中的其他嵌套实例。嵌套组中定义的深度嵌套实例仅依赖于或引用同一组中的其他深度嵌套实例。

将配置组合在一起，可获取此完整文档：

# 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: {}

示例 2 - 对嵌套实例的引用和依赖项无效

此示例配置无效，因为 Test/Echo 资源引用的顶级实例取决于嵌套 Microsoft/OSInfo 实例。嵌套实例位于顶层实例外部，而不是相邻实例。

# 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: {}

示例 3 - 对外部实例的引用和依赖项无效

此示例配置无效，因为 Test/Echo 资源引用的嵌套实例取决于顶级 Microsoft/OSInfo 实例。顶级实例位于嵌套实例外部，而不是相邻实例。

# 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')]"

通过