Compartilhar via


Referência de esquema de tipo de recurso DSC

Sinopse

Identifica se um recurso é um recurso de adaptador, um recurso de grupo ou um recurso normal.

Metadados

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]

Descrição

O DSC dá suporte a três tipos de recursos DSC baseados em comando:

  • Resource - Indica que o manifesto não é para um grupo ou recurso de adaptador.
  • Group - Indica que o manifesto é para um recurso de grupo .
  • - Indica que o manifesto é para umde recurso do adaptador de .
  • - Indica que o manifesto é para umde recurso do importador .

Quando kind não é definido no manifesto do recurso, o DSC infere o valor da propriedade. Se a propriedade adapter for definida no manifesto do recurso, o DSC inferirá o valor de kind como Adapter. Se a propriedade adapter não estiver definida, o DSC inferirá o valor de kind como Resource. A DSC não pode inferir se um manifesto é para um recurso de grupo.

Ao definir um recurso de grupo, sempre defina explicitamente a propriedade kind no manifesto como Group.

Recursos do adaptador

Um recurso de adaptador disponibiliza recursos não baseados em comando para DSC. Eles sempre têm uma propriedade resources que usa uma matriz de instâncias de recurso aninhadas. Os adaptadores podem fornecer controle adicional sobre como os recursos adaptados são processados.

Um recurso do adaptador deve sempre definir o do adaptador e validar as propriedades no manifesto do recurso.

Por exemplo, o adaptador Microsoft.DSC/PowerShell permite que você use recursos de PSDSC (Configuração de Estado Desejado) do PowerShell no DSC. Os recursos do PSDSC são publicados como componentes de módulos do PowerShell. Eles não definem manifestos de recurso.

Agrupar recursos

Os recursos de grupo sempre operam em instâncias aninhadas de recurso DSC. Os recursos de grupo podem alterar a forma como as instâncias aninhadas são processadas, como o recurso de grupo Microsoft.DSC/Assertion.

Um recurso de grupo deve sempre definir o tipo propriedade no manifesto do recurso.

Os recursos de grupo também podem ser usados para agrupar conjuntos de recursos para processamento, como o recurso Microsoft.DSC/Group. Você pode usar a propriedade dependsOn para uma instância de recurso em uma configuração para apontar para um recurso de grupo em vez de enumerar cada recurso na lista.

Recursos do importador

Os recursos do importador resolvem uma origem externa para um conjunto de instâncias aninhadas do Recurso DSC. As propriedades de um recurso de importador definem como localizar e resolver a origem externa.

Um recurso de importador deve sempre definir o tipo e resolver propriedades no manifesto do recurso.

Por exemplo, o recurso Microsoft.DSC/Import importador resolve instâncias de um documento de configuração externa, permitindo que você componha configurações de vários arquivos.

Instâncias de recursos aninhadas

As instâncias de recurso declaradas nos recursos do adaptador e do grupo ou resolvidas pelos recursos do importador são chamadas instâncias de recursos aninhadas.

Para instâncias aninhadas, uma instância de recurso será adjacente se:

  • Ele é declarado no mesmo grupo ou instância do adaptador.
  • Ela é resolvida pela mesma instância do importador.

Uma instância de recurso será externa para uma instância aninhada se:

  • Ele é declarado fora da instância do grupo ou do adaptador
  • Ela é resolvida por uma instância de importador diferente
  • Ele é aninhado dentro de um grupo adjacente, adaptador ou instância do importador.

Para instâncias de nível superior, outras instâncias no nível superior são adjacentes. Todas as outras instâncias são externas.

Considere o snippet de configuração a seguir. Ele define sete instâncias de recurso:

  • No nível superior, a configuração define as instâncias TopLevelEcho, TopLevelOSInfoe TopLevelGroup.
  • A instância TopLevelGroup define as instâncias aninhadas NestedEcho e NestedGroup.
  • A instância NestedGroup define as instâncias aninhadas DeeplyNestedEcho e 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: { }

A matriz a seguir define as relações de cada instância na configuração:

TopLevelEcho TopLevelOSInfo TopLevelGroup AninhadoEcho NestedGroup DeeplyNestedEcho DeeplyNestedOSInfo
TopLevelEcho Eu Adjacente Adjacente Externo Externo Externo Externo
TopLevelOSInfo Adjacente Eu Adjacente Externo Externo Externo Externo
TopLevelGroup Adjacente Adjacente Eu Externo Externo Externo Externo
NestedEcho Externo Externo Externo Eu Adjacente Externo Externo
NestedGroup Externo Externo Externo Adjacente Eu Externo Externo
DeeplyNestedEcho Externo Externo Externo Externo Externo Eu Adjacente
DeeplyNestedOSInfo Externo Externo Externo Externo Externo Adjacente Eu

Referenciando instâncias aninhadas

As instâncias de recurso aninhadas têm limitações para a propriedade dependsOn e a função de configuração reference().

  1. Você só pode referenciar instâncias adjacentes. Você não pode referenciar uma instância aninhada de fora da instância que a declare ou resolva. Você não pode usar uma referência a um recurso fora do grupo, adaptador ou recurso do importador para uma instância aninhada.
  2. Você só pode usar a propriedade dependsOn para instâncias adjacentes. Você deve adicionar uma dependência ao grupo, adaptador ou instância do importador, não a uma instância aninhada. Instâncias aninhadas não podem depender de instâncias externas.

Os exemplos a seguir mostram referências e dependências válidas e inválidas. Os exemplos usam o recurso Microsoft.DSC/Group, mas a funcionalidade é a mesma para recursos de importação e adaptador.

Exemplo 1 – Referências e dependências válidas

Esta configuração de exemplo define várias referências e dependências válidas. Ele também define duas instâncias do recurso Microsoft.DSC/Group, uma aninhada dentro da outra.

A instância de nível superior do recurso Test/Echo faz referência e depende da instância de nível superior do recurso Microsoft/OSInfo. As instâncias de nível superior dos recursos Test/Echo e Microsoft/OSInfo dependem da instância de nível superior do recurso 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

A instância de nível superior do Microsoft.DSC/Group define três instâncias de recurso aninhadas: Test/Echo, Microsoft/OSInfoe Microsoft.DSC/Group. Como no nível superior, a instância Test/Echo faz referência e depende da instância deMicrosoft/OSInfo aninhada adjacente e essa instância depende da instância de Microsoft.DSC/Group aninhada adjacente.

# 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

Por fim, a instância aninhada de Microsoft.DSC/Group define duas instâncias aninhadas. A instância profundamente aninhada de referências de Test/Echo e depende da instância profundamente aninhada de 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: {}

Em todos os casos, as referências e dependências são para instâncias adjacentes na configuração. As instâncias no nível superior dependem apenas ou fazem referência a outras instâncias no nível superior. As instâncias aninhadas no grupo de nível superior dependem ou fazem referência a outras instâncias aninhadas no mesmo grupo. As instâncias profundamente aninhadas definidas no grupo aninhado dependem ou fazem referência a outras instâncias profundamente aninhadas no mesmo grupo.

Juntando a configuração, você obtém este documento completo:

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

Exemplo 2 – Referência e dependência inválidas em uma instância aninhada

Esta configuração de exemplo é inválida, pois a instância de nível superior do recurso Test/Echo faz referência e depende da instância de Microsoft/OSInfo aninhada. A instância aninhada é externa à instância de nível superior, não adjacente.

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

Exemplo 3 – Referência e dependência inválidas em uma instância externa

Esta configuração de exemplo é inválida, pois a instância aninhada do recurso Test/Echo faz referência e depende da instância de Microsoft/OSInfo de nível superior. A instância de nível superior é externa à instância aninhada, não adjacente.

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