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
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
,TopLevelOSInfo
eTopLevelGroup
. - A instância
TopLevelGroup
define as instâncias aninhadasNestedEcho
eNestedGroup
. - A instância
NestedGroup
define as instâncias aninhadasDeeplyNestedEcho
eDeeplyNestedOSInfo
.
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
- 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.
- 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/OSInfo
e 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')]"