Referência de esquema do 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 suporta três tipos de recursos DSC baseados em comando:

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

Quando kind não está 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. O 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 comandos para o DSC. Eles sempre têm uma propriedade resources que usa uma matriz de instâncias de recursos aninhados. Os adaptadores podem fornecer controle adicional sobre como os recursos adaptados são processados.

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

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

Recursos do grupo

Os recursos de grupo sempre operam em instâncias de recurso DSC aninhadas. 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 fonte externa para um conjunto de instâncias aninhadas de Recursos DSC. As propriedades de um recurso importador definem como localizar e resolver a fonte externa.

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

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

Instâncias de recursos aninhados

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

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

• É declarado no mesmo grupo ou instância do adaptador.
• É resolvido pela mesma instância do importador.

Uma instância de recurso é externa a uma instância aninhada se:

• É declarado fora do grupo ou da instância do adaptador
• É resolvido por uma instância de importador diferente
• Ele está aninhado dentro de um grupo, adaptador ou instância de importador adjacente.

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

Considere o seguinte trecho de configuração. Ele define sete instâncias de recursos:

• 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	Grupo de Nível Superior	NestedEcho	NestedGroup	DeeplyNestedEcho	DeeplyNestedOSInfo
TopLevelEcho	Eu mesmo	Adjacente	Adjacente	Externa	Externa	Externa	Externa
TopLevelOSInfo	Adjacente	Eu mesmo	Adjacente	Externa	Externa	Externa	Externa
TopLevelGroup	Adjacente	Adjacente	Eu mesmo	Externa	Externa	Externa	Externa
NestedEcho	Externa	Externa	Externa	Eu mesmo	Adjacente	Externa	Externa
NestedGroup	Externa	Externa	Externa	Adjacente	Eu mesmo	Externa	Externa
DeeplyNestedEcho	Externa	Externa	Externa	Externa	Externa	Eu mesmo	Adjacente
DeeplyNestedOSInfo	Externa	Externa	Externa	Externa	Externa	Adjacente	Eu mesmo

Referenciando instâncias aninhadas

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

1. Você só pode fazer referência a instâncias adjacentes. Não é possível fazer referência a uma instância aninhada de fora da instância que a declara ou resolve. Não é possível usar uma referência a um recurso fora do grupo, adaptador ou recurso importador para uma instância aninhada.
2. Você só pode usar a propriedade dependsOn para instâncias adjacentes. Você deve adicionar uma dependência no grupo, adaptador ou instância do importador, não uma instância aninhada. As 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 adaptador e importação.

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

Este exemplo de configuração 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 recursos aninhados: Test/Echo, Microsoft/OSInfoe Microsoft.DSC/Group. Como no nível superior, a instância Test/Echo faz referência e depende da instânciaMicrosoft/OSInfo aninhada adjacente e essa instância depende da instância aninhada Microsoft.DSC/Group 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

Finalmente, a instância aninhada de Microsoft.DSC/Group define duas instâncias aninhadas. A instância profundamente aninhada de Test/Echo referências 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 apenas ou fazem referência a outras instâncias aninhadas no mesmo grupo. As instâncias profundamente aninhadas definidas no grupo aninhado dependem apenas 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 inválida e dependência em uma instância aninhada

Este exemplo de configuração é inválido, porque 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 inválida e dependência de uma instância externa

Este exemplo de configuração é inválido, porque 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')]"