Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

aggrega inspect

aggrega inspect renderiza uma visão legível de qualquer entidade Aggrega — um Component de catálogo, um arquivo de entidade escrito, uma entidade publicada em um registry ou uma Release totalmente resolvida. É a superfície de depuração canônica para entender o que o compilador vai produzir: quais Components estendem quais bases, qual Recipe corresponde a cada tipo, quais Features se vinculam a cada nó e de onde exatamente vieram as contribuições de cada Feature.

Cada tipo de entidade tem uma visão natural de “contrato”. inspect mostra esse contrato — o esquema que um Component publica, os mapeamentos que um Manifest declara, a topologia que um Aggregate constrói, os vínculos de Feature por nó para os quais uma Release é resolvida. O material de tutorial e conceitual fica em outro lugar; inspect responde “para o que esta entidade é realmente resolvida?”

Um único argumento posicional é roteado pela forma do conteúdo; nenhum subcomando é necessário. O comando despacha de acordo com a seguinte heurística:

Forma do identificadorDespachoSaída
Começa com ./, ../ ou /, ou termina com .yaml / .ymlRamo de arquivoInspeção por arquivo com base no cabeçalho kind: do arquivo.
Começa com oci://Ramo de registryA entidade publicada nessa coordenada, lida do seu registry e renderizada pela visão que um arquivo do seu tipo recebe. Consulte Ler uma entidade publicada.
Qualquer outra coisaRamo de catálogoProcurar o identificador na pilha de busca do catálogo em todos os tipos de entidade; resolver as cadeias extends:; renderizar a visão própria do tipo encontrado.

Três níveis de detalhe

--list, o padrão e --detail formam uma disciplina uniforme de verbosidade em três níveis que todo tipo respeita. --list e --detail são mutuamente exclusivos — passar ambos é recusado em vez de resolvido silenciosamente.

  • --list — apenas identificadores. Um Component lista seu nome e os nomes dos seus sockets uses; uma MappingLibrary lista os nomes dos seus mapeamentos; um Aggregate lista os nomes dos seus componentes com seus tipos.
  • padrão — uma visão geral estruturada, ajustada para uso interativo. Ela começa com a identidade da entidade e, para todo tipo exceto um Manifest e uma Release, com sua descrição, quando a entidade escreve uma; uma entidade sem descrição não imprime nenhuma em vez de imprimir uma linha vazia. O restante da forma depende do tipo: um Component mostra seu esquema e seus sockets; um Aggregate mostra os componentes, seus valores e arestas com os vínculos que cada conexão traz, e o grafo de dependências; uma Release mostra a árvore de nós por boundary com os vínculos de Feature, cada um dos escritos em uma conexão listado abaixo dessa conexão.
  • --detail — corpos completos dos campos. Tudo o que o tipo contém: um Component adiciona seus mecanismos de autoinjeção, as Features exigidas e os rótulos; uma MappingLibrary expande o corpo completo do template de cada mapeamento; uma Recipe adiciona o corpo do seu workload, provides e as asserções.

Alguns tipos usam os níveis para revelar progressivamente mais de um corpo escrito. Uma MappingLibrary em --list mostra os nomes dos mapeamentos; no nível padrão, adiciona o exemplo de uso sintetizado de cada mapeamento; em --detail, expande o corpo completo do template.

Resolução: --raw e --resolved

Cada tipo tem uma profundidade de resolução padrão natural (veja a tabela abaixo). --raw e --resolved são substituições sempre disponíveis, e são mutuamente exclusivas — passar ambas é recusado em vez de resolvido silenciosamente:

  • --raw desativa toda resolução — a entidade é emitida como foi escrita, diretamente do arquivo.
  • --resolved ativa a profundidade de resolução completa do tipo.

Para os tipos cujo padrão é a forma escrita, --raw não tem efeito e --resolved aciona a resolução que o tipo suporta. Para os tipos cujo padrão é a forma resolvida, --raw é o desvio para a forma escrita.

--raw reproduz o arquivo, então um valor que um autor declarou sensível aparece nele exatamente como foi escrito. Esse é o contrato, não uma lacuna — uma visão como escrita que ocultasse silenciosamente parte de si mesma não seria como escrita. Trate a saída de --raw como você trata o arquivo de entidade de onde ela veio. --output yaml reproduz o arquivo da mesma forma, para todo tipo, incluindo uma Release.

Uma Release responde a mais duas perguntas, e cada uma é um documento diferente com seu próprio flag. O grafo compilado para o qual uma Release é resolvida é --ir-graph; seu fechamento de dependências é --closure. Consulte Saída legível por máquina e O fechamento de dependências: --closure abaixo.

Padrões por tipo

inspect conhece os tipos inspecionáveis de forma independente da tabela abaixo. Os tipos de catálogo são renderizados por padrão como escritos — seus arquivos são contratos autocontidos. Os tipos de instância usam por padrão uma visão resolvida, porque seu YAML escrito é apenas o ponto de partida de uma cascata ou de um pipeline.

TipoPadrãoO que “resolvido” significa
Componentcomo escritoO arquivo é um contrato autocontido; a resolução é feita em relação a um binding do Manifest, exibida por meio de --show-implements.
Featurecomo escritoO mesmo que Component.
Recipecomo escrito--show-implements resolve a referência ao Component em spec.implements.
FeatureRecipecomo escrito--show-implements resolve a referência à Feature em spec.implements.
MappingLibrarycomo escritoAs entradas são strings opacas de template Go; a renderização acontece no momento do consumo.
SchemaLibrarycomo escritoAs entradas são definições reutilizáveis de esquema e template resolvidas no momento do consumo.
WorkloadLibrarycomo escritoAs entradas são corpos de Workload reutilizáveis que uma Recipe importa, avaliados no momento do consumo.
ArtifactLibrarycomo escritoAs entradas são pacotes de artefatos reutilizáveis que uma Recipe importa, renderizados no momento do consumo.
Plugincomo escritoO arquivo é um contrato de plugin autocontido: tipos de socket, capacidades por export, restrições de runtime e ponteiro de assinatura. Endereçável pelo caminho do arquivo, ou pela sua coordenada <pluginType>/<name> em relação ao catálogo.
ManifestresolvidoA cadeia extends: é aplicada; os mapeamentos resolvidos de componentes e features são apresentados.
AggregateresolvidoA topologia é construída — o grafo uses e a ordenação são calculados.
ReleaseresolvidoO pipeline completo é executado: resolver, expandir anotações, executar guards, construir a topologia, construir o IR.

Um arquivo cujo kind: é Workload é rejeitado: um Workload existe apenas incorporado em uma Recipe e não é uma entidade inspecionável de forma independente. Inspecione uma Recipe para ver seu Workload.

Profundidade de resolução por tipo

A maioria dos tipos não tem pipeline — inspect lê o arquivo e o renderiza. Três tipos de instância são resolvidos de forma significativa:

  • Manifest aplica sua cadeia extends: — seguindo as importações de arquivos — e renderiza os mapeamentos mesclados de componentes e features. --raw mostra o arquivo como foi escrito.
  • Aggregate constrói sua topologia: o grafo uses é construído e a ordenação de dependências é calculada. A visão padrão mostra os componentes com seus valores e arestas, seguidos do grafo de dependências. --raw mostra a árvore de subsistemas como escrita.
  • Release executa todo o pipeline de compilação até o IR — resolver, expandir anotações, executar guards, construir a topologia, construir o IR — e renderiza a árvore de nós por boundary com os vínculos de Feature de cada nó e sua procedência. Os vínculos de governança que moldam o grafo são executados nesse pipeline em vez de serem ignorados para uma visão, então o que você lê reflete o que eles decidiram: os rótulos de um vínculo label-transform já estão aplicados antes que qualquer coisa seja comparada com eles, e as anotações injetadas por um vínculo annotation-transform se expandem em vínculos de Feature exatamente como uma anotação que você escreveu. Um vínculo cujo plugin este comando não consegue resolver o interrompe, em vez de deixar para você um grafo desenhado sem as decisões desse plugin. Uma Release que estende outra é desenhada, nesta visão e em --ir-graph, como a Release que sua cadeia extends: compõe — aquela que um build dela lê —, de modo que uma Release que nomeia apenas sua Release pai mostra o Aggregate, o Manifest e os boundaries dessa Release pai sob seu próprio nome. O Manifest que uma Release nomeia também é composto por meio da sua própria cadeia extends:, quer a Release estenda algo ou não, de modo que um vínculo cujo mapeamento esse Manifest herda mostra a realização que um build usa. --raw emite o arquivo da Release literalmente, sem pipeline. --closure faz uma pergunta diferente sobre a mesma Release e não executa nenhum pipeline; consulte O fechamento de dependências: --closure.

Não há um flag de profundidade separado; a alternância --raw / --resolved é o único controle de resolução, sobreposto ao padrão natural de cada tipo.

Comportamento em caso de erro

Um arquivo irmão referenciado que não carrega interrompe o comando imediatamente — uma Release apontando para um Aggregate ausente, uma entidade de catálogo quebrada na pilha de busca. Ele é interrompido com uma mensagem clara em vez de renderizar uma saída parcial, e não há modo continue-on-error para uma falha de carregamento: assim que um documento de que a resolução precisa fica ilegível, não há mais nada a resolver. Quando a resolução de um nome é interrompida em um documento de catálogo que o carregamento recusa, a mensagem declara essa recusa uma única vez: um cabeçalho com a categoria e, quando a recusa nomeia uma condição, seu código curto, depois o documento, depois o que há de errado com ele — para um documento que o esquema do seu tipo recusa, a linha e a restrição que ele viola. Ela não traz nenhuma sugestão de mover o arquivo — o catálogo o leu, e é por isso que ele foi recusado.

Uma Release cuja composição as verificações do compilador rejeitam é recusada em vez de renderizada. Resolver uma Release constrói o grafo, e as verificações que um build faz sobre o grafo finalizado — uma aresta uses: cujo alvo não satisfaz o selector: do seu socket, uma Feature vinculada a um componente que seu appliesTo: não admite, e as demais — são feitas aqui também, com o diagnóstico que um build dos mesmos documentos imprime. A recusa nomeia cada constatação em uma única execução em vez de parar na primeira, então uma única passada mostra a lista inteira a corrigir em vez da sua primeira entrada. É isso que mantém este comando honesto em relação a um deployment: uma visão que renderizasse uma composição que o build recusa informaria que um workspace está correto quando não está. As seleções que não resolvem nada não são afetadas — --raw, --output yaml e --closure reproduzem ou resolvem o que você escreveu sem construir um grafo.

Uma Release cujo lockfile já não corresponde ao resultado da sua resolução é recusada com a interrupção que aggrega build imprime. Onde há um lockfile ao lado da Release, toda seleção que resolve a Release — a visão padrão, --resolved, --ir-graph e --closure — exige que ele corresponda ao resultado da resolução da Release, com a comparação de desvio que um build executa antes de renderizar. Um lockfile que já não corresponde interrompe o comando com a recusa E0130 do build: cada entrada que divergiu e, em seguida, o aggrega pull --release <release> que a elimina. Nada é escrito na saída padrão e o comando termina com código diferente de zero, porque uma imagem traçada a partir do catálogo tal como está mostraria o que nenhum build dessa Release renderiza. --raw e --output yaml, sozinhos, não leem nem o lockfile nem o catálogo, e não estão sujeitos a ele. Uma Release sem lockfile ao lado é resolvida sobre o catálogo tal como está.

Um arquivo cujo kind: não é reconhecido informa o tipo desconhecido e o arquivo de onde veio. Um arquivo Workload informa que o tipo existe apenas incorporado e nomeia a entidade na qual é incorporado. Um identificador oci:// que não pode ser lido é recusado com a condição que nomeia o motivo; Ler uma entidade publicada as lista.

Resolução do catálogo

A pilha de busca do catálogo é montada com uma precedência em camadas: os flags --catalog (antepostos, em ordem) vêm primeiro, depois os catalog_dirs do workspace em .aggrega-config.yaml — para uma Release à qual a configuração atribui diretórios próprios em workspace.releases, os dessa Release no lugar deles —, depois o diretório catalog na raiz do workspace, que é lido quer algo o nomeie ou não. Um workspace cujo catalog_dirs está escrito como uma lista vazia não lê nenhum catálogo local. A pilha é first-win — o primeiro diretório a declarar uma identidade de entidade é dono dela; a cópia de um diretório posterior fica oculta. O ramo de catálogo resolve o identificador em relação a essa pilha em todos os tipos de entidade, em uma precedência fixa, e renderiza a primeira correspondência pela visão própria desse tipo; os ramos de arquivo e de release carregam dela as entidades de catálogo referenciadas quando um mapeamento do Manifest ou um pai extends: precisa ser resolvido. Um pai extends: que a pilha não contém é lido onde um build o lê: do cache de artefatos, sob o pin que o lockfile de uma Release registra para ele — o da Release indicada, ou o de cada Release que o workspace contém quando nenhuma é indicada. Assim, uma base publicada em um registry é resolvida aqui assim que aggrega pull a tiver buscado e fixado, e antes disso o comando é recusado indicando aggrega pull --release <release>. Nada é buscado.

Procurar um nome nos termos de uma Release

Um nome dado sozinho é procurado na pilha própria do workspace. Informe --release <release-path> ao lado dele e o nome é procurado, em vez disso, na pilha dessa Release — os diretórios que a configuração do workspace atribui a essa Release, com quaisquer --catalog antepostos —, que é o que um build dessa Release lê. Um workspace que mantém uma variante de catálogo por Release, cada uma declarando a mesma entidade, responde portanto a um nome com a variante com a qual essa Release é construída:

aggrega inspect core/datastore/mariadb --release release-helm-synth.yaml

Um nome que a pilha dessa Release não resolve é recusado, e a explicação de onde as entidades locais são lidas nomeia a entrada dessa Release em workspace.releases, já que foi essa entrada que a busca leu. --release escolhe a pilha em que um nome é procurado, então se aplica apenas a um nome sozinho: um caminho de arquivo e uma referência de registry são lidos como estão e o recusam. Um --release que nomeia um arquivo inexistente, ou que nomeia um diretório, é recusado antes que qualquer coisa seja procurada.

Ler uma entidade publicada

aggrega inspect oci://<host>/<repository>:<tag> lê a entidade publicada nessa coordenada; @<digest> no lugar de :<tag> nomeia exatamente um manifesto. É assim que você examina uma entidade que existe apenas em um registry — o repositório é o segmento do tipo seguido da identidade da entidade, como expõe o §6 de Catálogo e registry, e aggrega push imprime a referência em que publicou, que aqui é lida com oci:// na frente.

O que você vê é a entidade como foi publicada. Uma entidade publicada com os arquivos que declara — uma Recipe com seu chart local ou seu lock, um Component com um esquema que importa — é distribuída como um arquivo compactado, e a entidade é extraída dele: o documento na raiz do arquivo compactado que declara um tipo publicável, de modo que um template de chart ou um fragmento de compose distribuído ao lado não seja confundido com ela. Uma entidade que não declara nenhum arquivo é distribuída como seu documento inalterado, e a entidade de um Plugin é lida do seu manifesto em vez do executável publicado com ele. O documento é então renderizado pela mesma visão que um arquivo desse tipo recebe, com os mesmos níveis de detalhe e os mesmos --raw e --output yaml. Nenhuma herança é aplicada: a visão é do que o publicador colocou nessa coordenada. Os layouts legíveis terminam com o que foi lido: a coordenada, se ela continha a entidade como arquivo compactado ou como o próprio documento, o tipo de mídia que seu manifesto declara e o digest desse manifesto, que lê os mesmos bytes novamente quando escrito como @<digest> no lugar de :<tag>; --output yaml imprime o documento e nada depois dele.

O que ele verifica e o que não verifica. Os bytes obtidos são verificados em relação ao digest que o próprio manifesto do artefato registra para eles, o que estabelece que são os bytes que esse manifesto nomeia. É uma verificação em relação ao que o registry serviu, e não em relação a algo registrado previamente: nenhuma assinatura anexada ao artefato é verificada, e nenhuma retirada registrada contra ele é informada. Nada é gravado — nenhuma entrada de cache e nenhum lockfile —, então ler uma coordenada não muda nada do que um build posterior resolve.

Ele acessa a rede. O registry é contatado com as credenciais que esta máquina mantém para ele, do mesmo armazenamento que aggrega push e aggrega pull leem, e um registry nesta máquina é contatado por HTTP simples. Um workspace offline recusa a leitura antes de qualquer conexão.

Uma leitura que não consegue responder sai com código diferente de zero e não imprime nada na saída padrão. Cada falha abaixo nomeia sua condição junto com o que fazer a respeito; um registry que não pode ser alcançado de forma alguma é informado com o erro de rede que interrompeu a leitura:

O que aconteceuCondição
Nada está publicado sob a referênciaE0137
O registry recusou a credencial, ou nenhuma está armazenada para eleE0138
O workspace está offlineE0125
O artefato é um arquivo compactado que não pode ser extraídoE0300
O arquivo compactado não contém nenhum documento de entidade na sua raizE0298
O arquivo compactado contém mais de um documento de entidade na sua raizE0299
O documento não é uma entidade de um tipo que um registry publicaE0301

Cada código está listado na referência de erros. Uma referência que não nomeia nenhum repositório, ou nem uma tag nem um digest, é recusada com a forma a ser escrita no lugar. --ir-graph e --closure são recusados antes que qualquer coisa seja obtida, porque nenhum tipo que um registry publica é uma Release.

Avisos de obsolescência e de retirada

Um publicador pode registrar um marcador contra um artefato depois de publicá-lo, declarando que a versão publicada está obsoleta ou retirada. Quando o ramo de catálogo resolve uma entidade, inspect informa qualquer marcador desse tipo abaixo da visão própria da entidade — para cada tipo que resolve por nome, não apenas para um Component.

O aviso nomeia a severidade que o publicador registrou — warning, error ou retracted — junto com a versão em que o marcador foi registrado, o motivo, a substituta quando uma é indicada e a data de emissão. As três severidades são informadas. Isso é mais amplo do que o conjunto que muda aquilo para o qual um build é resolvido: uma versão marcada como retracted é excluída da seleção de versões, enquanto warning e error são consultivas e ainda são selecionadas. inspect mostra o que um publicador declarou; ele não decide o que você obtém.

O aviso é lido do índice local do registry a partir do qual a entidade é resolvida, que aggrega registry update constrói — então ele não precisa de rede e funciona em um workspace offline. Como o índice é um snapshot, o aviso termina informando quando esse snapshot foi tirado e nomeia o comando que o atualiza. Um workspace sem índice construído não informa nada, e um aviso ausente significa, portanto, “nada registrado neste snapshot” e não “nada registrado”.

Um marcador é informado apenas quando sua própria assinatura é verificada em relação aos signatários que a política de confiança do registry reconhece. Um marcador não assinado, ou um cuja assinatura não é verificada, não é informado: uma afirmação que não pode ser autenticada não é apresentada como fato.

O aviso acompanha as visões legíveis por pessoas. Nem --output yaml nem --ir-graph acrescentam um, então um consumidor que analisa qualquer um dos dois recebe um documento e nada mais.

Exemplos práticos

Consulta de um Component no catálogo

$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0
Schema:
|
values: { port?: int | *8080 }
Uses sockets:
db: selector="component.aggrega.ai/type=stateful-server"

A visualização padrão mostra a descrição do Component, quando ele define uma, depois o schema resolvido (após qualquer mesclagem de extends:) e os uses-sockets declarados. O Component acima não define nenhuma descrição, e é por isso que a transcrição começa direto no schema. --detail acrescenta os mecanismos de self-inject, as Features obrigatórias e os rótulos; --list mostra apenas o identificador do Component e os nomes dos seus sockets.

Feature

$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0
Schema:
|
values: { port?: int | *9090 }
Uses sockets:
backend: selector="component.aggrega.ai/type=stateful-server"
inject: [env]
Secret slots:
token (required)
Targeting:
appliesTo: component.aggrega.ai/type=server
Labels:
feature.aggrega.ai/category: observability

Recipe com --show-implements

A visualização padrão de uma Recipe mostra uma seção para cada modo de entrada que ela declara, sua capacidade e seu mapeamento de valores. --show-implements resolve a referência spec.implements em relação ao catálogo e renderiza o Component vinculado, junto com as vinculações que esse Component exige:

$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Synthesized
workload: inline
valuesMapping: (none)
Implements Component: core/api-server:1.0.0
requires attachment (observability): core/metrics

Recipe que declara vários modos de entrada

Os modos de entrada de uma Recipe se compõem por adição: um source: a renderizar, um workload: a sintetizar e um mapa artifacts: contribuem, cada um, com saída, e uma Recipe pode declarar qualquer combinação deles. inspect informa cada modo que a Recipe declara em vez de escolher um, de modo que o que você vê é o conjunto que você escreveu:

$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Sourced
source: oci://charts.example.com/api-server:2.1.0
## Synthesized
workload: inline
valuesMapping: inline template
Artifacts: 2
- servicemonitor.yaml
- networkpolicy.yaml

As seções são ordenadas source: → workload: → artifacts:, a mesma ordem que um build aplica quando resolve uma Recipe para um único nome de modo e quando informa qual modo declarado o provider vinculado não consegue atender — assim, esta visualização e os diagnósticos de um build nomeiam os modos na mesma ordem. Uma Recipe que não declara nem um source: nem um workload: é informada como somente artifacts, que é o único caso em que a visualização nomeia um único modo.

Manifest (resolvido por padrão)

$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings:
Type → Recipe
core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0
core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0
core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings:
Type → FeatureRecipe
core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings:
(none)

A visualização padrão aplica a cadeia extends: do Manifest e apresenta os mapeamentos resolvidos de componentes e funcionalidades, além das vinculações de anotações. --raw mostra o arquivo como foi escrito, antes da resolução de extends.

Aggregate (resolvido por padrão)

$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components:
backend (type: core/compute/api-server)
Values: (none)
Uses:
databases:
- data.main-db
frontend (type: core/compute/web-ui)
Values: (none)
Uses:
apis:
- my-api → backend
main-db (type: core/datastore/postgres)
Values:
database_name: app_production
Uses: (none)
Dependency Graph:
data.main-db
↑ backend
backend
↑ frontend

A visualização padrão constrói a topologia e mostra cada componente com seus valores e suas arestas uses, seguidos do grafo de dependências calculado. A árvore de subsistemas é renderizada com aninhamento; --flat renderiza uma seção por nó, cada uma identificada pelo seu caminho completo com pontos.

Uma conexão escrita na forma longa é seguida pelas vinculações que ela carrega, cada uma sob o nome que assume no componente consumidor — o alias da conexão e o slot unidos por um ponto —, com o tipo de Feature que nomeia e uma cláusula que indica o slot que preenche e se lida com material declarado sensível:

gateway (type: conn/gateway)
Values:
region: eu
Uses:
models:
- gpt → model
- gpt.credential (feature.conn/token) [slot: credential, sensitive]

O slot e a marca são os fatos que um build de uma Release que implanta este Aggregate registra para a vinculação, lidos da mesma forma que a visualização da Release os lê (veja Conexão, slot e cláusula de sensibilidade de uma vinculação); eles vêm da declaração de slot do socket e da declaração da própria Feature, portanto não dependem de qual Release implanta o Aggregate. Um Aggregate não nomeia nenhum Manifest, então a realização que o Manifest de uma Release escolhe para a vinculação não é mostrada aqui. Esta visualização lista as conexões de um componente e o que elas carregam; as vinculações do bloco próprio de um componente aparecem na visualização da Release.

Release (resolvida por padrão)

A visualização da Release é a inspeção de maior impacto. Ela executa o pipeline completo e renderiza, por fronteira, cada nó Component, suas arestas uses e cada Feature vinculada a esse nó — a que foi escrita em uma conexão, sob a aresta dessa conexão —, cada uma com o slot de vinculação que preenche, se lida com material declarado sensível e a FeatureRecipe que a realiza, além de um colchete de procedência que revela de onde veio a vinculação:

$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns
Directory: ./dist/backend
Annotations (provider-consumed):
aggrega.ai/namespace: backend-zone
Component: backend (type: core/compute/api-server:1.0.0)
Uses:
data.main-db → data.main-db [cross-boundary]
Features: (none)
Boundary: frontend-ns
Directory: ./dist/frontend
Annotations (provider-consumed):
aggrega.ai/namespace: frontend-zone
Component: frontend (type: core/compute/web-ui:1.0.0)
Uses:
my-api → backend [cross-boundary]
Features:
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns
Directory: ./dist/data
Annotations (provider-consumed):
aggrega.ai/namespace: database-zone
Component: data.main-db (type: core/datastore/postgres:1.0.0)
Features: (none)

Cada fronteira carrega seu diretório de saída e suas anotações consumidas pelo provider; cada componente sob uma fronteira carrega seu tipo de componente do Aggregate, suas arestas uses (com as arestas entre fronteiras marcadas), cada uma seguida das vinculações que essa conexão carrega, e suas próprias vinculações de Feature, cada vinculação com sua cláusula de fatos e seu colchete de procedência. --flat reduz a árvore de fronteiras a uma seção por fronteira, identificada pelo seu caminho completo. --raw emite o arquivo da Release literalmente, sem pipeline.

Saída YAML

$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
db:
selector: component.aggrega.ai/type=stateful-server
schema:
values:
port: {type: integer, default: 8080}

Um Component nomeado a partir do catálogo é impresso como a entidade que o catálogo resolveu, de modo que, após um merge extends:, você vê a entidade mesclada em vez do arquivo escrito; um arquivo de Component é impresso como foi escrito.

Saída legível por máquina

Duas flags produzem saída legível por máquina, e elas respondem a perguntas diferentes. --output escolhe um formato para o documento que este comando já renderiza; --ir-graph pede um documento diferente — o grafo compilado para o qual uma Release se resolve — além dele. Elas são independentes: passar ambas fornece o grafo e o YAML como escrito, cada um uma vez.

--output yaml emite a entidade como foi escrita, adequada para pipes e diffs. Essa saída é literal, e isso inclui valores que um autor declarou sensíveis — uma saída que afirma reproduzir a entrada não pode ocultar parte dela e continuar a reproduzi-la. Encaminhe, armazene e compartilhe essa saída como você faria com o arquivo de entidade de onde ela veio.

O grafo compilado: --ir-graph

aggrega inspect <release> --ir-graph grava na saída padrão, como JSON, o grafo para o qual a execução se resolveu, antes da visualização que o comando renderiza de qualquer forma. Um único documento JSON, uma única quebra de linha final, de modo que um consumidor que decodifica o fluxo lê o grafo e para.

Ela se aplica a uma Release, que é o único tipo que se resolve para um grafo. Se solicitada para qualquer outro tipo, ou para uma entidade do catálogo por nome, o comando recusa e informa isso, em vez de renderizar a visualização própria dessa entidade e descartar a solicitação silenciosamente.

Uma composição que as verificações do compilador rejeitam não produz nenhum grafo. A recusa descrita em Comportamento em caso de erro acontece antes que qualquer coisa seja gravada neste fluxo, de modo que um pipeline que o lê nunca recebe um grafo que um build dos mesmos documentos recusaria — ele recebe os mesmos achados que um build informaria, e um código de saída diferente de zero.

A mesma flag, com o mesmo significado, está em aggrega build e aggrega validate: cada um devolve o grafo que aquela execução calculou, além de tudo o mais que esse comando produz. Uma integração de editor lê o mesmo grafo pelo protocolo do daemon.

--output yaml não emite o grafo. Ele reproduz a Release escrita, exatamente como faz para qualquer outro tipo. Um pipeline que quer o grafo o lê de --ir-graph, e recebe JSON em vez de YAML.

O grafo oculta. Ele não é um arquivo que alguém escreveu — é o que a compilação calculou a partir do Aggregate, da Release e do catálogo —, então não há nenhum compromisso de fidelidade ao que foi escrito a cumprir, e as mesmas declarações que regem os layouts legíveis o regem também. Sempre que o grafo carrega uma folha que um autor declarou sensível, o valor é substituído por um objeto de chave única que o indica como ocultado:

"values": {
"secretName": "db-creds",
"vault": {
"token": { "aggrega_withheld": "declared" }
}
}

A chave permanece, então o grafo ainda responde quais folhas um nó e suas vinculações carregam; só o valor desaparece. Um irmão não declarado na mesma carga útil é emitido como foi escrito — secretName acima é um localizador público que seu autor deixou sem declarar, e ele é impresso. O motivo que acompanha o marcador diz por que o valor está ausente: declared para uma folha coberta por uma declaração, e unreadable quando a carga útil chegou em uma forma que este comando não conseguiu ler, caso em que a carga útil inteira é ocultada em vez de qualquer parte dela ser adivinhada.

A configuração própria de uma conexão é omitida da mesma forma. Os values por conexão que um Aggregate escreve em uma entrada uses e a infra por conexão que uma Release escreve em uma delas são regidos pelo socket do componente consumidor — o valueSchema e o infraSchema que ele declara, os contratos com base nos quais essa configuração é validada —, nunca pelas declarações do destino. Uma folha que qualquer um dos contratos declara sensitive: true é substituída pelo marcador nos values e na infra da aresta, e na entrada uses do nó consumidor, que traz os valores como o autor os escreveu; cada aresta lista as folhas que omite em sensitive_payload_leaves, o campo que um nó usa para as suas. Uma folha de mesmo nome em uma conexão cujo socket a declara legível é emitida como está escrita.

Passe --unredacted quando um pipeline realmente precisar dos valores, e trate o que ele produz como você trata os próprios arquivos de entidade. aggrega build e aggrega validate aceitam a mesma flag ao lado de --ir-graph, nas mesmas condições: o grafo que eles devolvem oculta os valores, a menos que ela seja passada.

O protocolo do daemon entrega o mesmo grafo sob a mesma regra. aggrega/irGraph responde com esses valores ocultados, e os devolve em texto claro apenas a uma solicitação que define seu campo unredacted — a forma desta flag no protocolo. Assim, o que um painel do editor desenha segue as mesmas declarações, e um cliente que mostra os valores o faz porque os pediu.

O fechamento de dependências: --closure

aggrega inspect <release> --closure informa o fechamento de dependências da Release: cada entidade do catálogo que ela alcança, na versão para a qual cada uma se resolveu, junto com as identidades do Aggregate e do Manifest para as quais seus dois ponteiros se resolveram e os documentos compartilhados em que essas entidades se baseiam. Nada é renderizado e nenhum artefato é produzido — o fechamento é resolvido, não construído, então nenhum provider é carregado para respondê-lo.

O fechamento e a visualização resolvida são documentos diferentes, e nenhum pode ser recuperado a partir do outro. A visualização resolvida — o que este comando renderiza por padrão para uma Release — diz como é a implantação: suas fronteiras, seus nós de componente, o que está ligado a quê e o que está vinculado a cada nó. O fechamento diz o que foi trazido para construí-la, e em quais versões. Uma entidade pode ser alcançada sem nunca aparecer como nó — a Recipe para a qual um Manifest mapeia um tipo de componente é alcançada por todo build e não é nó em nenhum deles —, e um nó registra o tipo de componente com o qual foi declarado, não a versão para a qual esse tipo se resolveu. Então, um leitor que pergunta “por que esta versão mudou?”, “o que mudar este documento compartilhado afetaria?” ou “do que esta implantação realmente depende?” está pedindo o fechamento, e um leitor que tem a visualização resolvida não o obtém lendo-a com mais atenção.

A mesma palavra pede o mesmo documento em todas as superfícies. --closure aqui, aggrega/releaseClosure pelo protocolo do daemon (veja aggrega serve, “Um fechamento não é o grafo”) e o modo release da ferramenta describe pelo protocolo de ferramentas do assistente respondem todos a esta pergunta sobre uma Release; um nome de Release em qualquer um deles chega à mesma resolução, de modo que os três não podem passar a divergir sobre aquilo de que uma Release depende. Sobre um lockfile que não corresponde mais àquilo para o que a Release é resolvida, este comando e a ferramenta describe recusam com a parada por desvio do build; o daemon, que atende um editor enquanto ele edita, responde.

É um único documento, então é pedido sozinho. --closure seleciona o fechamento no lugar da visualização resolvida, e não pode ser combinado com --raw, --resolved, --output ou --ir-graph — cada um deles pede um documento diferente sobre a mesma Release, e um comando que aceitasse duas solicitações teria que responder silenciosamente a apenas uma delas. A combinação é recusada, nomeando o par.

Ele se aplica a uma Release e a nada mais. Uma entidade do catálogo, um arquivo de Aggregate, um Manifest — nenhum deles resolve um fechamento, então a solicitação é recusada em vez de ser respondida com a renderização da visualização própria desse objeto e descartada. Uma solicitação descartada parece, para quem a fez, exatamente igual a um objeto cujo fechamento está vazio.

Cada resultado é diferenciado dos demais. Uma Release que se resolve é respondida com a listagem. Um caminho de Release que não nomeia nenhum arquivo é recusado, informando que o arquivo não existe. Uma Release que existe e cujo fechamento não pode ser resolvido é recusada com o que não pôde ser resolvido e de onde veio a referência, seguido de quaisquer arquivos que o carregamento do catálogo recusou — porque um arquivo recusado é o motivo habitual pelo qual uma entidade alcançada pela Release está faltando. Um registro de confiança de plugins ao lado da Release que existe e não pode ser lido é recusado com o que não pôde ser lido, porque uma listagem que o ignorasse não informaria nenhum plugin retirado onde nenhum pôde ser verificado. Uma Release cujo lockfile não corresponde mais àquilo para o que ela é resolvida é recusada com a parada por desvio que um build imprime, como descreve Comportamento em caso de erro, porque as versões listadas seriam versões que nenhum build dessa Release usa. Uma listagem vazia nunca é a resposta para nenhum deles: ela apresentaria um caminho digitado errado, ou um workspace quebrado, como uma Release que não depende de nada.

Os três níveis de detalhamento se aplicam como em qualquer tipo. --list imprime apenas as referências, uma por linha, para uso em pipes. O nível padrão acrescenta as identidades resolvidas, a versão para a qual cada referência se resolveu, os documentos compartilhados utilizados, qualquer mapeamento do Manifest cujo destino não implementa o tipo para o qual é mapeado e qualquer aviso de descontinuação ou retirada registrado sobre aquilo de que a Release depende — no seu lockfile, contra uma referência fixada, e no registro de confiança de plugins ao lado dela, contra um plugin vinculado em um papel que retorna um veredito de aceitação ou rejeição — nas palavras que aggrega build imprime para o mesmo marcador. --detail acrescenta o tipo de cada referência quando o local da referência registrou um — algumas posições em um documento dizem para qual tipo apontam e outras não, então ele é informado onde é conhecido em vez de ser adivinhado pela forma do nome.

$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0
Aggregate: fullstack-app
Manifest: prod-manifest
Environment: production
Entities (11):
./aggregate.yaml
./manifest.yaml
core/compute/api-server (1.0.0)
core/compute/web-ui (1.0.0)
core/datastore/postgres (1.0.0)
core/k8s-dns-resolver (1.0.0)
db-module (1.0.0)
helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0)
k8s-dns-patcher:1.0.0 (1.0.0)

Quando um workspace registrou para quais versões uma Release se resolve, esse registro serve de ponto de partida para a resolução, de modo que as versões informadas são aquelas a partir das quais esta implantação é construída, e não o que o catálogo por acaso contém hoje. Um workspace sem esse registro resolve sobre o catálogo como ele está.

Conexão, slot e cláusula de sensibilidade de uma vinculação

Cada vinculação de Feature na visualização da Release carrega uma cláusula que nomeia os fatos que o compilador registra sobre a própria vinculação: qual slot de vinculação ela preenche, se lida com material declarado sensível e a FeatureRecipe que a realiza — e, para uma vinculação escrita em uma das conexões do componente, a conexão em que foi escrita. A cláusula fica entre o nome da vinculação e seu colchete de procedência, e é lida de forma idêntica nas duas formas de procedência abaixo.

Uma vinculação escrita em uma conexão é listada sob a linha dessa conexão em Uses:, e não sob Features:, de modo que Features: contém apenas as vinculações próprias do componente. A linha acima dela nomeia a conexão pelo seu alias e pelo componente que ela alcança, e sua própria cláusula diz o resto:

  • [socket: <socket>] — o socket pelo qual a conexão passa, que a linha da conexão não nomeia. Ele abre a cláusula porque muda a forma como o resto é lido: a metade de slot que se segue nomeia um slot que o socket da conexão declara, e não um que o componente declara para suas próprias vinculações.
  • [connection: <alias> through socket <socket>] — o mesmo fato para uma vinculação cuja conexão não tem nenhuma linha no bloco Uses:, que então é listada sob Features: e nomeia sua conexão aqui. De qualquer forma, uma conexão é nomeada uma vez por vinculação, nunca duas.
  • [slot: <name>] — a vinculação preenche o slot chamado <name>. Um slot é preenchido vinculando uma Feature sob o próprio nome do slot, então <name> é o nome sob o qual a vinculação foi escrita, comparado com os slots declarados: o featuresSchema do Component hospedeiro para uma de suas próprias vinculações, e o featuresSchema que o socket da conexão declara para uma vinculação escrita em uma conexão.
  • [free] — a vinculação não preenche nenhum slot declarado: o Component resolvido não declara nenhum slot featuresSchema com esse nome. Isso é um achado, não um diagnóstico. Uma vinculação de forma livre é aceita, e um operador que queira proibi-la expressa isso como uma política de governança em vez de contar com a ferramenta para recusá-la.
  • [sensitive] — a vinculação lida com material que um autor declarou sensível, porque a Feature vinculada declara uma folha sensível, porque o slot que ela preenche declara sensitive: true, ou ambos.
  • [realization: <name>:<version>] — a FeatureRecipe que o Manifest da Release vincula para a vinculação: pelo nome próprio da vinculação, quando o Manifest mapeia esse nome — para uma vinculação escrita em uma conexão, o alias e o slot unidos por um ponto —, caso contrário pelo seu tipo de Feature. É a realização com a qual um build dos mesmos documentos renderiza a vinculação, e o mesmo valor que o grafo compilado carrega na vinculação como realization (veja --ir-graph), de modo que esta visualização e o grafo não podem nomear realizações diferentes. Ela vem por último na cláusula.

Quando vários fatos se aplicam, eles compartilham uma cláusula. core/storage/s3-object-store declara um slot secret_access_key marcado com sensitive: true, então uma credencial vinculada sob esse nome informa os dois fatos, enquanto uma Feature vinculada sob um nome para o qual o Component não declara nenhum slot não informa nem slot nem sensibilidade. Com um Manifest que mapeia cada tipo de Feature para uma FeatureRecipe, cada linha também nomeia sua realização:

Features:
- secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit]
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]

Um componente cujo socket models declara um slot credential marcado com sensitive: true, e que liga uma conexão sob o alias gpt que o preenche, lista essa vinculação sob a conexão — ao lado de uma credencial própria, que permanece sob Features::

Uses:
gpt → model
- gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit]
Features:
- db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]

Uma vinculação escrita em uma conexão nunca informa [free]: um socket admite apenas os slots que declara, e uma conexão que carrega qualquer outro nome é recusada quando o build é carregado.

A cláusula é omitida por completo quando nenhum dos fatos se aplica, e cada metade é omitida de forma independente:

  • Nenhuma metade de socket ou de conexão significa que a vinculação foi escrita no bloco próprio do componente, ou chegou a ele a partir de um escopo mais amplo ou por expansão orientada por anotações.
  • Nenhuma metade de slot significa que o conjunto de slots declarados do Component hospedeiro não pôde ser resolvido — por exemplo, seu tipo não corresponde a nenhuma entidade do catálogo. Isso é deliberadamente diferente de [free]: [free] responde “nenhum slot com esse nome está declarado”, enquanto uma metade ausente significa que a pergunta não pôde ser respondida de forma alguma.
  • Nenhum sensitive registra que nenhuma declaração marcou a vinculação. Isso é mais restrito do que um veredito de que a vinculação não carrega nada secreto; o eixo informa declarações, e nada é inferido a partir do nome de um campo ou do seu valor.
  • Nenhuma metade de realização significa que o Manifest não vincula a vinculação a nenhuma FeatureRecipe que o catálogo contenha.

Um slot cujo nome declarado é literalmente free também é renderizado como [free], indistinguível de uma vinculação de forma livre — nada reserva essa palavra no espaço de nomes dos slots.

Gramática do colchete de procedência da IR

Cada vinculação de Feature na visualização da Release carrega um colchete de procedência. O colchete pode assumir uma forma compacta (um colchete por Feature quando a procedência da vinculação é uniforme em todas as folhas) ou uma forma por folha (um colchete por folha quando as folhas da vinculação vêm de fontes heterogêneas). Existem três corpos de colchete; eles se aplicam de forma idêntica às duas formas.

Os três corpos de colchete

  • [explicit] — a vinculação de Feature é declarada pelo autor. O Aggregate ou a Release nomeou explicitamente a Feature no nó afetado. Vinculações explícitas são a fonte de maior prioridade; elas sempre prevalecem sobre contribuições orientadas por anotações na mesma folha.

  • [annotation: <key> from <source>] — a vinculação de Feature é orientada por anotações. O compilador a sintetizou porque uma anotação em <source> correspondeu a uma vinculação do Manifest que declara esta Feature. <key> é a chave de anotação que acionou a vinculação (por exemplo, business.aggrega.ai/team); <source> é a entidade que carregava a anotação (aggregate, release, component ou manifest). A vinculação sintetizada é estruturalmente idêntica a uma explícita — a renderização posterior trata as duas da mesma forma —, mas o colchete de procedência as distingue para que a depuração continue decidível.

  • [explicit; overrides annotation: <key> from <source>] — uma forma por folha que é acionada quando uma declaração explícita do autor em uma folha suprime uma contribuição de anotação que, de outra forma, teria definido a mesma folha. A composição entre lados produz esse caso: uma anotação do Aggregate pode fornecer o pilar values: de uma Feature, uma anotação da Release fornece seu pilar infra:, e uma declaração explícita da Release na mesma Feature sobrescreve uma folha de infra. O colchete da folha registra tanto o autor explícito quanto a anotação suprimida; a anotação suprimida não contribui para a saída renderizada, mas sua presença aparece na visualização do inspect, para que o operador possa ver qual anotação foi sobrescrita e onde.

Forma compacta e forma por folha

O compilador escolhe entre a renderização compacta e a por folha percorrendo a procedência por folha da vinculação e verificando sua uniformidade. A procedência de uma vinculação é uniforme quando cada folha preenchida (nos pilares values: e infra: da Feature) compartilha a mesma origem (explícita ou anotação), a mesma chave de anotação quando orientada por anotações, a mesma entidade de origem, e nenhuma folha carrega um marcador “overrides annotation”. Quando a procedência é uniforme, o compilador emite um colchete por vinculação:

- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]

Quando a procedência diverge — um caso típico é a composição entre lados, em que uma anotação do Aggregate fornece values: e uma anotação da Release fornece infra: na mesma Feature —, o compilador emite um colchete por folha preenchida:

- core/pii-redaction
values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate]
values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate]
infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]

A ordem do percurso é primeiro o pilar values (na ordem do autor), depois o pilar infra (com a mesma disciplina). O prefixo do pilar (values. / infra.) e o caminho com pontos dentro do pilar indicam exatamente qual folha cada colchete anota.

Valores declarados sensíveis

Uma folha cujo schema declara sensitive: true imprime o texto fixo <redacted> no lugar do seu valor. A chave, o prefixo do pilar e o colchete de procedência são todos mantidos — só o valor é substituído —, de modo que o layout ainda responde quais folhas uma entidade carrega e de onde cada uma veio. Duas superfícies legíveis são afetadas: o bloco Values: por nó de um Aggregate e o bloco de vinculações por folha de uma Release resolvida — incluindo uma vinculação escrita em uma conexão, impressa sob a linha dessa conexão, que oculta exatamente as folhas que a mesma Feature oculta quando o próprio componente a contém. O grafo compilado de uma Release com --ir-graph oculta as mesmas folhas na forma estruturada descrita em Saída legível por máquina.

Components:
app (type: core/app)
Values:
appName: demo
dbPassword: <redacted>
tuning.poolSize: 25
tuning.adminToken: <redacted>

Apenas uma folha declarada é ocultada, e a cláusula [sensitive] no nível da vinculação não é uma instrução de ocultação: ela diz que a vinculação lida com material secreto, não quais de suas folhas o carregam. Os localizadores publicados de uma Feature de credencial — o nome do recurso e a chave de dados — são públicos e são deliberadamente deixados sem declaração no catálogo da biblioteca padrão, então são impressos em texto claro ao lado do material que não é:

- credentials (feature.test/db-credential)
values.secretName: db-creds [explicit]
values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]

Nada é inferido a partir do nome de um campo: um campo chamado password que não carrega nenhuma declaração imprime seu valor, e um campo declarado chamado key não. A ocultação abrange o que a ferramenta imprime; ela nunca alcança um artefato renderizado, e dist/ é emitido exatamente como a renderização o produziu. A palavra-chave e o limite completo do que declará-la consegue estão em vocabulary/compact-form-authoring.md, “Declarar uma folha como sensível”.

Mostrar os valores ocultados

--unredacted imprime os valores declarados sensíveis em vez de ocultá-los, em todas as superfícies do inspect ao mesmo tempo — tanto os layouts legíveis acima quanto o grafo compilado de uma Release. Ela existe porque o valor ocultado às vezes é justamente o que está sendo investigado: uma credencial que chega da vinculação errada parece idêntica à correta quando ambas aparecem como ocultadas.

Seu escopo é o comando ao qual é passada. aggrega build e aggrega validate também a aceitam, onde ela alcança o grafo que --ir-graph devolve e nada mais, e a recusam quando nenhum grafo foi pedido. aggrega build --trace-unredacted é a mesma ideia aplicada aos arquivos de trace do build, e nenhuma das duas flags do build alcança a saída da outra; um artefato renderizado sob dist/ não é afetado por nenhuma delas, porque é emitido exatamente como a renderização o produziu, independentemente do que for passado.

Tudo o que a saída alcançar passa então a carregar esses valores em texto claro — um terminal, um pipe, um arquivo, uma gravação de tela, um relatório de bug colado. Ao contrário dos arquivos de trace, que abrem cada um com um cabeçalho dizendo que foram capturados sem ocultação, a saída em um terminal não carrega nenhuma marcação desse tipo: só a linha de comando indica que ela foi passada.

Quando recorrer ao inspect

  • Depurar “por que esta Feature está aqui?” — vinculações orientadas por anotações são invisíveis nos arquivos YAML do Aggregate e da Release (as anotações estão lá, mas as vinculações de Feature que elas sintetizam existem apenas na IR). O inspect as expõe com sua procedência.
  • Verificar a herança de schema — aggrega inspect <ComponentName> mostra o schema mesclado depois que a cadeia extends: é resolvida; o arquivo escrito, sozinho, mostra apenas o delta local.
  • Diagnosticar surpresas da composição entre lados — quando uma anotação do Aggregate e uma anotação da Release fornecem cargas úteis de pilar na mesma Feature, as folhas resolvidas podem ser difíceis de reconstruir mentalmente. A forma de colchete por folha torna a resolução explícita.
  • Verificação antes da implantação — aggrega inspect ./prod-release.yaml lista cada Feature em cada Component antes que aggrega build produza artefatos; o operador pode confirmar que a topologia corresponde à intenção antes de fazer commit dos manifestos renderizados no GitOps.

Para a mecânica subjacente — como as anotações se propagam em cascata, como a partição entre lado e pilar encaminha os valores das anotações para os pilares da Feature e como a disciplina de que a vinculação explícita prevalece interage com as contribuições orientadas por anotações —, veja providers/well-known-annotations.md e entities/manifest.md, “Vinculações de Feature orientadas por anotações”.

Sinopse

aggrega inspect [identifier] [flags]

Descrição

Render a readable view of any Aggrega entity — a catalog entity by name, an
authored entity file by path, an entity published in a registry, or a
fully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extend
which bases, which Recipe maps to each type, which Features attach to each node,
and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../
or /, or ending in .yaml or .yml — is read as a file and inspected by its own
kind: header. A registry reference — oci://<host>/<repository>:<tag>, or
@<digest> in place of :<tag> — is read from the registry that publishes it.
Anything else is looked up by name in the catalog search stack: the
workspace's own, or, with --release, the one the workspace configuration
gives that Release, so a name several catalog variants declare, one per
Release, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpacked
from the archive its kind is published as where it is one, and rendered by the
same view a file of that kind gets. Reading it reaches the network, using the
credentials this machine holds for that registry, and an offline workspace
refuses it. The fetched bytes are checked against the digest the artifact's
own manifest records for them, which establishes that they are the bytes that
manifest names and nothing more: no signature attached to the artifact is
verified, no withdrawal recorded against it is reported, and nothing is
written — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, the
default for a structured overview, and --detail for full field bodies. --list
and --detail are mutually exclusive. Resolution depth has its own pair, --raw
for the entity exactly as authored and --resolved for the kind's full depth,
also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declared
sensitive appears as authored. That is what as-authored means; handle such
output as you would the entity file itself. --output yaml reproduces the file
the same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag because
neither answer contains the other. --ir-graph asks for the IR graph a Release
resolves to — what the Release looks like, as JSON on stdout in addition to
whatever else this command produces. --closure asks for the Release's dependency
closure — every catalog entity it reaches and the version each resolved to,
which is what was pulled in to build the Release. An entity can be reached
without appearing as a node, and a node does not carry the version its type
resolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command's
own view. Values an author declared sensitive are withheld from the graph, as
they are from the readable layouts. Pass --unredacted to print them instead.

Flags

FlagPadrãoDescrição
--catalog[]Diretório de catálogo; repetível. Cada —catalog <dir> é colocado no início da pilha de busca do catálogo (a primeira correspondência vence): os catalog_dirs do workspace ou, para uma Release à qual a configuração do workspace atribui diretórios próprios em workspace.releases, os dessa Release; a pilha termina com o diretório chamado catalog na raiz do workspace, quando houver um. Uma lista catalog_dirs escrita vazia não lê nenhum catálogo local.
--closurefalseInforma o fechamento de dependências da Release — cada entidade do catálogo que ela alcança, na versão para a qual cada uma se resolveu — no lugar da visualização de nós resolvidos. Aplica-se a uma Release, que é o único tipo que resolve um fechamento; qualquer outro tipo recusa a solicitação em vez de descartá-la silenciosamente.
--colorautoColorir a saída: auto|always|never.
--detailfalseRenderizar o corpo completo dos campos.
--flatfalseRenderizar uma entidade em forma de árvore (Aggregate, Release) como uma lista plana, com cada nó prefixado pelo seu caminho completo com pontos. Sem efeito em tipos tabulares.
--ir-graphfalseGravar também no stdout, como JSON, o grafo IR que esta execução calculou, além de tudo o que este comando já produz. Os valores que um autor declarou sensíveis são ocultados nele; passe —unredacted para imprimi-los. Aplica-se a uma Release, o único tipo que se resolve para um grafo; qualquer outro tipo recusa a solicitação em vez de descartá-la silenciosamente
--listfalseRenderizar apenas os identificadores.
--no-colorfalseDesativar a saída colorida (alias de —color=never).
--output, -otextFormato de saída: text|yaml.
--plugin—Caminho no sistema de arquivos para um artefato <file.wasm> bruto; deriva e imprime as funções de host que ele importa, antes que aggrega plugin sync as registre em uma entidade Plugin. Não aceita nenhum argumento de identificador.
--rawfalseRenderizar a entidade como foi escrita, sem resolução.
--release—Consultar um nome do catálogo nos termos deste arquivo de Release: pelos diretórios de catálogo que a configuração do workspace atribui a essa Release, com —catalog adicionado à frente. Aplica-se a um nome; um arquivo ou uma referência de registry é inspecionado como está e o recusa. Um caminho relativo é resolvido em relação ao diretório em que você executa o comando, não em relação à raiz do workspace. Quando esse diretório não está em nenhum workspace e nenhuma raiz é indicada, um caminho absoluto encontra o workspace a partir da própria pasta da Release
--resolvedfalseRenderizar a entidade totalmente resolvida.
--show-implementsfalsePara uma Recipe ou FeatureRecipe, resolver spec.implements em relação ao catálogo e renderizar o Component ou a Feature vinculados.
--unredactedfalseImprimir os valores que um autor declarou sensíveis em vez de ocultá-los. Tudo o que a saída alcançar — um terminal, um pipe, um arquivo, uma gravação de tela — passa então a carregar esses valores em texto claro.