aggrega inspect
aggrega inspect apresenta uma vista legível por humanos de qualquer entidade Aggrega — um Component de catálogo, um ficheiro de entidade escrito, uma entidade publicada num registo ou uma Release totalmente resolvida. É a superfície de depuração canónica para compreender o que o compilador vai produzir: que Components estendem que bases, que Recipe corresponde a cada tipo, que Features se anexam a cada nó e exatamente de onde vieram as contribuições de cada Feature.
Cada tipo de entidade tem uma vista de «contrato» natural. inspect mostra esse contrato — o esquema que um Component publica, os mapeamentos que um Manifest declara, a topologia que um Aggregate constrói, as anexações de Feature por nó em que uma Release se resolve. O material tutorial e conceptual está noutro local; inspect responde a «em que se resolve realmente esta entidade?»
Um único argumento posicional é encaminhado segundo a forma do conteúdo; não é necessário nenhum subcomando. O comando despacha segundo a seguinte heurística:
| Forma do identificador | Despacho | Saída |
|---|---|---|
Começa por ./, ../ ou /, ou termina em .yaml / .yml | Ramo de ficheiro | Inspeção por ficheiro com base no cabeçalho kind: do ficheiro. |
Começa por oci:// | Ramo de registo | A entidade publicada nessa coordenada, lida a partir do seu registo e apresentada pela vista que um ficheiro do seu tipo recebe. Consulte Ler uma entidade publicada. |
| Qualquer outra coisa | Ramo de catálogo | Procurar o identificador na pilha de pesquisa de catálogos em todos os tipos de entidade; resolver as cadeias extends:; apresentar a vista própria do tipo encontrado. |
Três níveis de detalhe
--list, a predefinição e --detail formam uma disciplina uniforme de verbosidade em três níveis que todos os tipos respeitam. --list e --detail são mutuamente exclusivas — passar ambas é recusado em vez de resolvido silenciosamente.
--list— apenas identificadores. Um Component lista o 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 os respetivos tipos.- predefinição — uma visão geral estruturada, ajustada para uso interativo. Começa com a identidade da entidade e, para todos os tipos exceto um Manifest e uma Release, com a sua descrição, quando a entidade escreve uma; uma entidade sem descrição não imprime nenhuma, em vez de uma linha vazia. O resto da forma é por tipo: um Component mostra o seu esquema e sockets; um Aggregate mostra os componentes, os seus valores e arestas com as anexações que cada ligação contém, e o grafo de dependências; uma Release mostra a árvore de nós por fronteira com as anexações de Feature, cada uma escrita numa ligação listada sob essa ligação.
--detail— corpos completos dos campos. Tudo o que o tipo contém: um Component acrescenta os seus mecanismos de autoinjeção, as Features obrigatórias e as etiquetas; uma MappingLibrary expande o corpo completo do template de cada mapeamento; uma Recipe acrescenta o seu corpo de workload, provides e asserções.
Alguns tipos usam os níveis para mostrar progressivamente mais de um corpo escrito. Uma MappingLibrary com --list mostra os nomes dos mapeamentos; no nível predefinido acrescenta o exemplo de utilização sintetizado de cada mapeamento; com --detail expande o corpo completo do template.
Resolução: --raw e --resolved
Cada tipo tem uma profundidade de resolução predefinida natural (consulte a tabela abaixo). --raw e --resolved são substituições sempre disponíveis e mutuamente exclusivas — passar ambas é recusado em vez de resolvido silenciosamente:
--rawdesativa toda a resolução — a entidade é emitida tal como foi escrita, diretamente a partir do ficheiro.--resolvedativa a profundidade de resolução completa do tipo.
Para os tipos cuja predefinição é a forma escrita, --raw é uma operação nula e --resolved desencadeia a resolução que o tipo suporta. Para os tipos cuja predefinição é a forma resolvida, --raw é o desvio para a forma escrita.
--raw reproduz o ficheiro, pelo que um valor que um autor declarou sensível aparece nele exatamente como foi escrito. É esse o contrato, não uma lacuna — uma vista da forma escrita que ocultasse discretamente parte de si própria não seria a forma escrita. Trate a saída de --raw da mesma forma que o ficheiro de entidade de onde veio. --output yaml reproduz o ficheiro da mesma forma, para todos os tipos, incluindo uma Release.
Uma Release responde a mais duas perguntas, e cada uma é um documento diferente com a sua própria flag. O grafo compilado em que uma Release se resolve é --ir-graph; o seu fecho de dependências é --closure. Consulte Saída legível por máquina e O fecho de dependências: --closure abaixo.
Predefinições por tipo
inspect conhece os tipos inspecionáveis de forma autónoma da tabela abaixo. Os tipos de catálogo são apresentados por predefinição tal como foram escritos — os seus ficheiros são contratos autocontidos. Os tipos de instância têm por predefinição uma vista resolvida, porque o seu YAML escrito é apenas o ponto de partida para uma cascata ou um pipeline.
| Tipo | Predefinição | O que significa «resolvido» |
|---|---|---|
| Component | tal como escrito | O ficheiro é um contrato autocontido; a resolução é feita contra uma associação do Manifest, apresentada através de --show-implements. |
| Feature | tal como escrito | Igual a Component. |
| Recipe | tal como escrito | --show-implements resolve a referência de Component spec.implements. |
| FeatureRecipe | tal como escrito | --show-implements resolve a referência de Feature spec.implements. |
| MappingLibrary | tal como escrito | As entradas são cadeias de template Go opacas; a renderização acontece no momento do consumo. |
| SchemaLibrary | tal como escrito | As entradas são definições reutilizáveis de esquema e de template resolvidas no momento do consumo. |
| WorkloadLibrary | tal como escrito | As entradas são corpos de Workload reutilizáveis que uma Recipe importa, avaliados no momento do consumo. |
| ArtifactLibrary | tal como escrito | As entradas são pacotes de artefactos reutilizáveis que uma Recipe importa, renderizados no momento do consumo. |
| Plugin | tal como escrito | O ficheiro é um contrato de plugin autocontido: tipos de socket, capacidades por exportação, restrições de tempo de execução e ponteiro de assinatura. Endereçável pelo caminho do ficheiro ou pela sua coordenada <pluginType>/<name> no catálogo. |
| Manifest | resolvido | A cadeia extends: é aplicada; os mapeamentos resolvidos de componentes e de features são apresentados. |
| Aggregate | resolvido | A topologia é construída — o grafo de uses e a ordenação são calculados. |
| Release | resolvido | O pipeline completo é executado: resolver, expandir anotações, executar guardas, construir a topologia, construir o IR. |
Um ficheiro cujo kind: seja Workload é rejeitado: um Workload só existe incorporado numa Recipe e não é uma entidade inspecionável autónoma. Inspecione uma Recipe para ver o seu Workload.
Profundidade de resolução por tipo
A maioria dos tipos não tem pipeline — inspect lê o ficheiro e apresenta-o. Três tipos de instância têm uma resolução significativa:
- Manifest aplica a sua cadeia
extends:— seguindo as importações de ficheiros — e apresenta os mapeamentos fundidos de componentes e de features.--rawmostra o ficheiro tal como foi escrito. - Aggregate constrói a sua topologia: o grafo de uses é construído e a ordenação de dependências é calculada. A vista predefinida mostra os componentes com os seus valores e arestas, seguidos do grafo de dependências.
--rawmostra a árvore de subsistemas escrita. - Release executa todo o pipeline de compilação até ao IR — resolver, expandir anotações, executar guardas, construir a topologia, construir o IR — e apresenta a árvore de nós por fronteira com as anexações de Feature de cada nó e a sua proveniência. As anexações de governação que moldam o grafo são executadas nesse pipeline em vez de serem ignoradas para uma vista, pelo que o que se lê reflete o que decidiram: as etiquetas de uma anexação
label-transformestão em vigor antes de algo ser comparado com elas, e as anotações injetadas por uma anexaçãoannotation-transformexpandem-se em anexações de Feature exatamente como uma anotação escrita pelo utilizador. Uma anexação cujo plugin este comando não consegue resolver fá-lo parar, em vez de deixar um grafo desenhado sem as decisões desse plugin. Uma Release que estende outra é desenhada, nesta vista e em--ir-graph, como a Release que a sua cadeiaextends:compõe — aquela que uma compilação dela lê —, pelo que uma Release que nomeia apenas a sua Release mãe mostra o Aggregate, o Manifest e as fronteiras dessa mãe sob o seu próprio nome. O Manifest que uma Release nomeia é também composto através da sua própria cadeiaextends:, quer a Release estenda algo quer não, pelo que uma anexação cujo mapeamento esse Manifest herda mostra a realização que uma compilação usa.--rawemite literalmente o ficheiro da Release sem pipeline.--closurefaz uma pergunta diferente sobre a mesma Release e não executa nenhum pipeline; consulte O fecho de dependências:--closure.
Não há nenhuma flag de profundidade separada; o par --raw / --resolved é o único controlo de resolução, aplicado sobre a predefinição natural de cada tipo.
Comportamento em caso de erro
Um ficheiro irmão referenciado que não consegue ser carregado para o comando de imediato — uma Release que aponta para um Aggregate em falta, uma entidade de catálogo danificada na pilha de pesquisa. Para com uma mensagem clara em vez de apresentar uma saída parcial, e não há nenhum modo de continuar em caso de erro para uma falha de carregamento: quando um documento de que a resolução precisa é ilegível, não há mais nada a resolver. Quando a resolução de um nome para num documento de catálogo que o carregamento recusa, a mensagem indica essa recusa uma vez: um cabeçalho com a categoria e, quando a recusa nomeia uma condição, o seu código curto, depois o documento e depois o que está errado nele — para um documento que o esquema do seu tipo recusa, a linha e a restrição que viola. Não contém nenhuma sugestão para mover o ficheiro — o catálogo leu-o, e é por isso que foi recusado.
Uma Release cuja composição as verificações do compilador rejeitam é recusada em vez de apresentada. Resolver uma Release constrói o grafo, e as verificações que uma compilação faz sobre o grafo terminado — uma aresta uses: cujo alvo não satisfaz o selector: do seu socket, uma Feature anexada a um componente que o seu appliesTo: não admite, e as restantes — são também feitas aqui, com o diagnóstico que uma compilação dos mesmos documentos imprime. A recusa nomeia todas as conclusões numa única execução em vez de parar na primeira, pelo que uma passagem mostra a lista completa a corrigir e não apenas a sua primeira entrada. É isso que mantém este comando honesto quanto a uma implementação: uma vista que apresentasse uma composição que a compilação recusa reportaria um espaço de trabalho como correto quando não 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 foi escrito 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 existir um lockfile ao lado da Release, cada seleção que resolve a Release — a vista predefinida, --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 um 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, por si sós, 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 ficheiro cujo kind: não seja reconhecido reporta o tipo desconhecido e o ficheiro de onde veio. Um ficheiro Workload reporta que o tipo é apenas incorporado e nomeia a entidade sob a qual é incorporado. Um identificador oci:// que não possa ser lido é recusado com a condição que indica porquê; Ler uma entidade publicada lista-as.
Resolução do catálogo
A pilha de pesquisa de catálogos é montada com uma precedência em camadas: as flags --catalog (colocadas no início, pela ordem dada) vêm primeiro, depois os catalog_dirs do espaço de trabalho de .aggrega-config.yaml — para uma Release à qual a configuração atribui diretórios próprios em workspace.releases, os dessa Release em seu lugar — e depois o diretório catalog na raiz do espaço de trabalho, que é lido quer algo o nomeie quer não. Um espaço de trabalho cujo catalog_dirs está escrito como lista vazia não lê nenhum catálogo local. A pilha segue a regra da primeira correspondência — o primeiro diretório a declarar uma identidade de entidade é o seu proprietário; a cópia de um diretório posterior fica oculta. O ramo de catálogo resolve o identificador contra esta pilha em todos os tipos de entidade, por uma precedência fixa, e apresenta a primeira correspondência através da vista própria desse tipo; os ramos de ficheiro e de Release carregam a partir dela as entidades de catálogo referenciadas quando é necessário resolver um mapeamento do Manifest ou um pai extends:. Um pai extends: que a pilha não contém é lido onde uma compilação o lê: a partir da cache de artefactos, sob a fixação que o lockfile de uma Release regista para ele — o da Release indicada, ou o de cada Release que o espaço de trabalho contém quando nenhuma é indicada. Assim, uma base publicada num registo é resolvida aqui assim que aggrega pull a tiver obtido e fixado, e até lá o comando é recusado com a indicação de aggrega pull --release <release>. Nada é obtido.
Procurar um nome nos termos de uma Release
Um nome dado isoladamente é procurado na própria pilha do espaço de trabalho. Dê --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 espaço de trabalho atribui a essa Release, com qualquer --catalog colocado no início —, que é o que uma compilação dessa Release lê. Um espaço de trabalho 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 que essa Release compila:
aggrega inspect core/datastore/mariadb --release release-helm-synth.yamlUm nome que a pilha dessa Release não resolve é recusado, e a indicação de onde as entidades locais são lidas nomeia a entrada dessa Release em workspace.releases, já que essa entrada é o que a procura leu. --release escolhe a pilha em que um nome é procurado, pelo que se aplica apenas a um nome: um caminho de ficheiro e uma referência de registo são lidos tal como estão e recusam-na. Um --release que nomeie um ficheiro inexistente, ou que nomeie um diretório, é recusado antes de qualquer procura.
Ler uma entidade publicada
aggrega inspect oci://<host>/<repository>:<tag> lê a entidade publicada nessa coordenada; @<digest> em vez de :<tag> nomeia exatamente um manifesto. É assim que se examina uma entidade que só existe num registo — o repositório é o segmento do tipo seguido da identidade da entidade, como expõe a §6 de Catálogo e registo, e aggrega push imprime a referência em que publicou, que aqui se lê com oci:// à frente.
O que se vê é a entidade tal como foi publicada. Uma entidade publicada com os ficheiros que declara — uma Recipe com o seu chart local ou o seu lock, um Component com um esquema que importa — é distribuída como um arquivo, e a entidade é extraída dele: o documento na raiz do arquivo que declara um tipo publicável, para que um template de chart ou um fragmento compose distribuído ao lado não seja confundido com ela. Uma entidade que não declara nenhum ficheiro é distribuída como o seu documento inalterado, e a entidade de um Plugin é lida a partir do seu manifesto e não do executável publicado com ela. O documento é depois apresentado pela mesma vista que um ficheiro desse tipo recebe, com os mesmos níveis de detalhe e os mesmos --raw e --output yaml. Não é aplicada nenhuma herança: a vista é do que o publicador colocou nessa coordenada. As disposições legíveis terminam com o que foi lido: a coordenada, se continha a entidade como arquivo ou como o próprio documento, o tipo de media que o seu manifesto declara e o digest desse manifesto, que volta a ler os mesmos bytes quando escrito como @<digest> em vez de :<tag>; --output yaml imprime o documento e nada depois dele.
O que verifica e o que não verifica. Os bytes obtidos são verificados contra o digest que o próprio manifesto do artefacto regista para eles, o que estabelece que são os bytes que esse manifesto nomeia. É uma verificação contra o que o registo serviu e não contra algo registado previamente: nenhuma assinatura anexada ao artefacto é verificada, e nenhuma retirada registada contra ele é reportada. Nada é escrito — nenhuma entrada de cache e nenhum lockfile — pelo que ler uma coordenada não altera nada do que uma compilação posterior resolve.
Acede à rede. O registo é contactado com as credenciais que esta máquina detém para ele, a partir do mesmo armazenamento que aggrega push e aggrega pull leem, e um registo nesta máquina é contactado através de HTTP simples. Um espaço de trabalho offline recusa a leitura antes de qualquer ligação ser estabelecida.
Uma leitura que não consegue responder sai com um código diferente de zero e não imprime nada na saída padrão. Cada falha abaixo nomeia a sua condição juntamente com o que fazer a respeito; um registo que não possa de todo ser alcançado é reportado com o erro de rede que interrompeu a leitura:
| O que aconteceu | Condição |
|---|---|
| Nada está publicado sob a referência | E0137 |
| O registo recusou a credencial, ou nenhuma está guardada para ele | E0138 |
| O espaço de trabalho está offline | E0125 |
| O artefacto é um arquivo que não pode ser extraído | E0300 |
| O arquivo não contém nenhum documento de entidade na sua raiz | E0298 |
| O arquivo contém mais do que um documento de entidade na sua raiz | E0299 |
| O documento não é uma entidade de um tipo que um registo publique | E0301 |
Cada código está listado na referência de erros. Uma referência que não nomeie nenhum repositório, ou nem uma tag nem um digest, é recusada com a forma a escrever em alternativa. --ir-graph e --closure são recusadas antes de qualquer obtenção, porque nenhum tipo que um registo publica é uma Release.
Avisos de descontinuação e de retirada
Um publicador pode registar um marcador contra um artefacto depois de o publicar, indicando que a versão publicada está descontinuada ou retirada. Quando o ramo de catálogo resolve uma entidade, inspect reporta qualquer marcador desse tipo sob a vista própria da entidade — para todos os tipos que resolve por nome, não apenas para um Component.
O aviso nomeia a severidade que o publicador registou — warning, error ou retracted — juntamente com a versão em que o marcador foi registado, o motivo, a substituição quando é nomeada e a data em que foi emitido. As três severidades são reportadas. Isso é mais amplo do que o conjunto que altera aquilo em que uma compilação se resolve: uma versão marcada como retracted é excluída da seleção de versões, enquanto warning e error são consultivas e continuam a ser selecionadas. inspect mostra o que um publicador disse; não decide o que se obtém.
O aviso é lido a partir do índice local do registo a partir do qual a entidade é resolvida, que aggrega registry update constrói — pelo que não precisa de rede e funciona num espaço de trabalho offline. Como o índice é um instantâneo, o aviso termina indicando quando esse instantâneo foi tirado e nomeia o comando que o atualiza. Um espaço de trabalho sem índice construído não reporta nada, e a ausência de aviso significa portanto «nada registado neste instantâneo» e não «nada registado».
Um marcador só é reportado quando a sua própria assinatura é verificada contra os signatários que a política de confiança do registo reconhece. Um marcador não assinado, ou cuja assinatura não é verificada, não é reportado: uma afirmação que não pode ser autenticada não é apresentada como facto.
O aviso acompanha as vistas legíveis por humanos. Nem --output yaml nem --ir-graph acrescentam um, pelo que um consumidor que analise qualquer uma delas recebe um documento e nada mais.
Exemplos práticos
Procura de um Component de catálogo
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"A vista predefinida mostra a descrição do Component quando escreve uma, depois o esquema resolvido (após qualquer fusão extends:) e os sockets uses declarados. O Component acima não escreve nenhuma descrição, e é por isso que a transcrição começa diretamente pelo esquema. --detail acrescenta os mecanismos de autoinjeção, as Features obrigatórias e as etiquetas; --list mostra apenas o identificador do Component e os nomes dos seus sockets.
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | 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=serverLabels: feature.aggrega.ai/category: observabilityRecipe com --show-implements
A vista predefinida de uma Recipe mostra uma secção por cada modo de entrada que declara, a sua capacidade e o seu mapeamento de valores. --show-implements resolve a referência spec.implements contra o catálogo e apresenta o Component associado, juntamente com as anexações que esse Component exige:
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metricsRecipe que declara vários modos de entrada
Os modos de entrada de uma Recipe compõem-se 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 reporta todos os modos que a Recipe declara em vez de escolher um, pelo que o que se vê é o conjunto que foi escrito:
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yamlAs secções são ordenadas source: → workload: → artifacts:, a mesma ordem que uma compilação aplica quando resolve uma Recipe para um único nome de modo e quando reporta que modo declarado o fornecedor associado não consegue respeitar — pelo que esta vista e os diagnósticos de uma compilação nomeiam os modos pela mesma ordem. Uma Recipe que não declara nem um source: nem um workload: é reportada como só de artefactos, que é o único caso em que a vista nomeia um único modo.
Manifest (resolvido por predefiniçã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 vista predefinida aplica a cadeia extends: do Manifest e apresenta os mapeamentos resolvidos de componentes e de features, bem como as associações de anotações. --raw mostra o ficheiro tal como foi escrito, antes da resolução de extends.
Aggregate (resolvido por predefiniçã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 ↑ frontendA vista predefinida constrói a topologia e mostra cada componente com os seus valores e arestas uses, seguidos do grafo de dependências calculado. A árvore de subsistemas é apresentada com aninhamento; --flat apresenta uma secção por nó, cada uma identificada pelo seu caminho completo com pontos.
Uma ligação escrita na forma longa é seguida das anexações que contém, cada uma sob o nome que assume no componente consumidor — o alias da ligação e a posição unidos por um ponto — com o tipo de Feature que nomeia e uma cláusula que indica a posição 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]A posição e a marca são os factos que uma compilação de uma Release que implementa este Aggregate regista para a anexação, lidos da mesma forma que a vista da Release os lê (consulte Cláusula de ligação, posição e sensibilidade da anexação); vêm da declaração de posição do socket e da da própria Feature, pelo que não dependem da Release que implementa o Aggregate. Um Aggregate não nomeia nenhum Manifest, pelo que a realização que o Manifest de uma Release escolhe para a anexação não é aqui mostrada. Esta vista lista as ligações de um componente e o que contêm; as anexações do bloco próprio de um componente aparecem na vista da Release.
Release (resolvida por predefinição)
A vista da Release é a inspeção mais crítica. Executa o pipeline completo e apresenta, por fronteira, cada nó de Component, as suas arestas uses e cada Feature anexada a esse nó — uma escrita numa ligação sob a aresta dessa ligação —, cada uma com a posição de anexação que preenche, se lida com material declarado sensível e a FeatureRecipe que a realiza, além de um parêntese de proveniência que revela de onde veio a anexaçã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 contém o seu diretório de saída e as anotações consumidas pelo fornecedor; cada componente sob uma fronteira contém o seu tipo de componente do Aggregate, as suas arestas uses (com as arestas entre fronteiras marcadas), cada uma seguida das anexações que essa ligação contém, e as suas próprias anexações de Feature, cada anexação com a sua cláusula de factos e o seu parêntese de proveniência. --flat reduz a árvore de fronteiras a uma secção por fronteira identificada pelo seu caminho completo. --raw emite literalmente o ficheiro da Release sem pipeline.
Saída YAML
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: 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, pelo que, após uma fusão extends:, vê-se a entidade fundida em vez do ficheiro escrito; um ficheiro de Component é impresso tal como foi escrito.
Saída legível por máquina
Duas flags produzem saída legível por máquina, e respondem a perguntas diferentes. --output escolhe um formato para o documento que este comando já apresenta; --ir-graph pede um documento diferente — o grafo compilado em que uma Release se resolve — além dele. São independentes: passar ambas dá o grafo e o YAML tal como escrito, cada um uma vez.
--output yaml emite a entidade tal como foi escrita, adequada para encaminhar por pipe e para comparar. Essa saída é literal, e isso inclui os 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-a, guarde-a e partilhe-a da mesma forma que o ficheiro de entidade de onde veio.
O grafo compilado: --ir-graph
aggrega inspect <release> --ir-graph escreve no stdout, em JSON, o grafo que a execução resolveu, antes da vista que o comando apresenta de qualquer forma. Um documento JSON, uma quebra de linha final, pelo que um consumidor que descodifique o fluxo lê o grafo e para.
Aplica-se a uma Release, que é o único tipo que se resolve num grafo. Pedida para qualquer outro tipo, ou para uma entidade de catálogo por nome, o comando recusa e indica-o em vez de apresentar a vista própria dessa entidade e descartar discretamente o pedido.
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 de algo ser escrito neste fluxo, pelo que um pipeline que o lê nunca recebe um grafo que uma compilação dos mesmos documentos recusaria — recebe as mesmas conclusões que uma compilação reportaria, e um código de saída diferente de zero.
A mesma flag, com o mesmo significado, existe em aggrega build e aggrega validate: cada um devolve o grafo que essa execução calculou, além de tudo o resto que esse comando produz. Uma integração de editor lê o mesmo grafo através do protocolo do daemon.
--output yaml não emite o grafo. Reproduz a Release escrita, exatamente como faz para todos os outros tipos. Um pipeline que queira o grafo lê-o a partir de --ir-graph, e recebe JSON em vez de YAML.
O grafo oculta. Não é um ficheiro que alguém tenha escrito — é o que a compilação calculou a partir do Aggregate, da Release e do catálogo — pelo que não há nenhum contrato de forma escrita a manter, e as mesmas declarações que regem as disposições legíveis regem-no. Sempre que o grafo contém uma folha que um autor declarou sensível, o valor é substituído por um objeto de chave única que o identifica como ocultado:
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}A chave sobrevive, pelo que o grafo continua a responder a que folhas um nó e as suas anexações contêm; só o valor desaparece. Um irmão não declarado no mesmo conteúdo é emitido tal como foi escrito — secretName acima é um localizador público que o seu autor deixou sem declaração, e é impresso. O motivo que acompanha o marcador indica porque o valor está ausente: declared para uma folha abrangida por uma declaração, e unreadable quando o conteúdo chegou numa forma que este comando não conseguiu ler, caso em que todo o conteúdo é ocultado em vez de se tentar adivinhar qualquer parte dele.
A configuração própria de uma ligação é retida da mesma forma. Os values por ligação que um Aggregate escreve numa entrada uses e a infra por ligação que uma Release escreve numa delas são regidos pelo socket do componente consumidor — o valueSchema e o infraSchema que este declara, os contratos com base nos quais essa configuração é validada —, nunca pelas declarações do destino. Uma folha que qualquer um dos contratos declare sensitive: true é substituída pelo marcador nos values e na infra da aresta, e na entrada uses do nó consumidor, que contém os valores tal como o autor os escreveu; cada aresta lista as folhas que retém em sensitive_payload_leaves, o campo que um nó usa para as suas. Uma folha com o mesmo nome numa ligação cujo socket a declara legível é emitida tal como está escrita.
Passe --unredacted quando um pipeline precisar realmente dos valores, e trate o que produz da mesma forma que os próprios ficheiros de entidade. aggrega build e aggrega validate aceitam a mesma flag ao lado de --ir-graph, nos mesmos termos: o grafo que devolvem oculta, a menos que seja passada.
O protocolo do daemon fornece o mesmo grafo segundo a mesma regra. aggrega/irGraph responde com estes valores ocultados, e só os devolve em claro a um pedido que defina o seu campo unredacted — a forma desta flag no protocolo. Assim, o que um painel de editor desenha segue as mesmas declarações, e um cliente que mostra os valores fá-lo porque os pediu.
O fecho de dependências: --closure
aggrega inspect <release> --closure reporta o fecho de dependências da Release: todas as entidades de catálogo que alcança, na versão em que cada uma foi resolvida, juntamente com as identidades de Aggregate e de Manifest em que os seus dois ponteiros se resolveram e os documentos partilhados em que essas entidades se baseiam. Nada é renderizado e nenhum artefacto é produzido — o fecho é resolvido, não compilado, pelo que nenhum fornecedor é carregado para responder.
O fecho e a vista resolvida são documentos diferentes, e nenhum pode ser obtido a partir do outro. A vista resolvida — o que este comando apresenta por predefinição para uma Release — diz qual é o aspeto da implementação: as suas fronteiras, os seus nós de componente, o que está ligado a quê e o que está anexado a cada nó. O fecho diz o que foi incluído para a construir, e em que 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 todas as compilações e não é um nó em nenhuma delas — e um nó regista o tipo de componente com que foi declarado, não a versão em que esse tipo se resolveu. Assim, um leitor que pergunte «porque mudou esta versão?», «o que afetaria alterar este documento partilhado?» ou «de que depende realmente esta implementação?» está a pedir o fecho, e um leitor que tenha a vista resolvida não o obtém por a ler com mais atenção.
A mesma palavra pede o mesmo documento em todas as superfícies. --closure aqui, aggrega/releaseClosure através do protocolo do daemon (consulte aggrega serve, «Um fecho não é o grafo») e o modo release da ferramenta describe através do protocolo de ferramentas do assistente respondem todos a esta pergunta sobre uma Release; um nome de Release através de qualquer um deles chega à mesma resolução, pelo que os três não podem divergir quanto àquilo de que uma Release depende. Perante um lockfile que já não corresponde àquilo para que a Release resolve, este comando e a ferramenta describe recusam com a paragem por desvio do build; o daemon, que serve um editor enquanto este edita, responde.
É um único documento, por isso é pedido isoladamente. --closure seleciona o fecho em vez da vista resolvida, e não pode ser combinada com --raw, --resolved, --output ou --ir-graph — cada uma delas pede um documento diferente sobre a mesma Release, e um comando que aceitasse dois pedidos teria de responder silenciosamente a um deles. Combiná-las é recusado, nomeando o par.
Aplica-se a uma Release e a nada mais. Uma entidade de catálogo, um ficheiro de Aggregate, um Manifest — nenhum deles resolve um fecho, pelo que o pedido é recusado em vez de respondido apresentando a vista própria desse objeto e descartando-o. Um pedido descartado parece, a quem chama, exatamente igual a um objeto cujo fecho está vazio.
Cada resultado é distinguido dos restantes. Uma Release que se resolve recebe como resposta a listagem. Um caminho de Release que não nomeia nenhum ficheiro é recusado, indicando que o ficheiro não existe. Uma Release que existe e cujo fecho não pode ser resolvido é recusada com o que não pôde ser resolvido e a origem da referência, seguidos de quaisquer ficheiros que o carregamento do catálogo recusou — porque um ficheiro recusado é a razão habitual pela qual uma entidade que a Release alcança desapareceu. Um registo de confiança dos 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 reportaria nenhum plugin retirado onde nenhum pôde ser verificado. Uma Release cujo lockfile já não corresponde àquilo para que resolve é recusada com a paragem 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 utiliza. Uma listagem vazia nunca é a resposta a nenhum deles: reportaria um caminho mal escrito, ou um espaço de trabalho danificado, como uma Release que não depende de nada.
Os três níveis de verbosidade aplicam-se como a todos os tipos. --list imprime apenas as referências, uma por linha, para encaminhamento por pipe. A predefinição acrescenta as identidades resolvidas, a versão em que cada referência se resolveu, os documentos partilhados usados, qualquer mapeamento do Manifest cujo alvo não implementa o tipo para o qual é mapeado e qualquer aviso de descontinuação ou retirada registado contra aquilo de que a Release depende — no seu lockfile, contra uma referência fixada, e no registo de confiança dos plugins ao lado dela, contra um plugin anexado num papel que devolve um veredicto 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 registou um — algumas posições num documento indicam para que tipo apontam e outras não, pelo que é reportado quando é conhecido em vez de adivinhado a partir da 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 espaço de trabalho registou as versões em que uma Release se resolve, esse registo serve de base à resolução, pelo que as versões reportadas são aquelas a partir das quais esta implementação é construída e não as que o catálogo contenha hoje. Um espaço de trabalho sem esse registo resolve sobre o catálogo tal como está.
Cláusula de ligação, posição e sensibilidade da anexação
Cada anexação de Feature na vista da Release contém uma cláusula que nomeia os factos que o compilador regista sobre a própria anexação: que posição de anexação preenche, se lida com material declarado sensível e a FeatureRecipe que a realiza — e, para uma anexação escrita numa das ligações do componente, a ligação em que foi escrita. A cláusula fica entre o nome da anexação e o seu parêntese de proveniência, e lê-se da mesma forma em ambas as formas de proveniência abaixo.
Uma anexação escrita numa ligação é listada sob a linha dessa ligação em Uses:, não em Features:, pelo que Features: contém apenas as anexações próprias do componente. A linha acima nomeia a ligação pelo seu alias e pelo componente que alcança, e a sua própria cláusula indica o resto:
[socket: <socket>]— o socket através do qual a ligação é estabelecida, que a linha da ligação não nomeia. Abre a cláusula porque altera a forma como o resto se lê: a metade da posição que se segue nomeia uma posição que o socket da ligação declara, não uma que o componente declara para as suas próprias anexações.[connection: <alias> through socket <socket>]— o mesmo facto para uma anexação cuja ligação não tem nenhuma linha no blocoUses:, que é então listada emFeatures:e nomeia aqui a sua ligação. Em qualquer dos casos, uma ligação é nomeada uma vez por anexação, nunca duas.[slot: <name>]— a anexação preenche a posição chamada<name>. Uma posição é preenchida anexando uma Feature sob o próprio nome da posição, pelo que<name>é o nome sob o qual a anexação foi escrita, comparado com as posições declaradas: ofeaturesSchemado Component anfitrião para uma das suas próprias anexações, e ofeaturesSchemaque o socket da ligação declara para uma anexação escrita numa ligação.[free]— a anexação não preenche nenhuma posição declarada: o Component resolvido não declara nenhuma posiçãofeaturesSchemacom esse nome. Isto é uma constatação, não um diagnóstico. Uma anexação de forma livre é aceite, e um operador que a queira proibir exprime-o como política de governação em vez de contar com a ferramenta para a recusar.[sensitive]— a anexação lida com material que um autor declarou sensível, porque a Feature anexada declara uma folha sensível, porque a posição que preenche declarasensitive: true, ou ambos.[realization: <name>:<version>]— a FeatureRecipe que o Manifest da Release associa à anexação: pelo próprio nome da anexação quando o Manifest mapeia esse nome — para uma anexação escrita numa ligação, o alias e a posição unidos por um ponto — ou, caso contrário, pelo seu tipo de Feature. É a realização com que uma compilação dos mesmos documentos renderiza a anexação, e o mesmo valor que o grafo compilado contém na anexação comorealization(consulte--ir-graph), pelo que esta vista e o grafo não podem nomear realizações diferentes. Vem em último lugar na cláusula.
Quando se aplicam vários factos, partilham uma única cláusula. core/storage/s3-object-store declara uma posição secret_access_key marcada com sensitive: true, pelo que uma credencial anexada sob esse nome reporta ambos os factos, enquanto uma Feature anexada sob um nome para o qual o Component não declara nenhuma posição não reporta nem posição nem sensibilidade. Com um Manifest que mapeia cada tipo de Feature para uma FeatureRecipe, cada linha nomeia também a 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 uma posição credential marcada com sensitive: true, e que estabelece uma ligação sob o alias gpt que a preenche, lista essa anexação sob a ligação — ao lado de uma credencial própria, que permanece em 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 anexação escrita numa ligação nunca reporta [free]: um socket só admite as posições que declara, e uma ligação com qualquer outro nome é recusada quando a compilação carrega.
A cláusula é totalmente omitida quando nenhum dos factos se aplica, e cada metade é omitida de forma independente:
- A ausência da metade de socket ou de ligação significa que a anexação foi escrita no bloco próprio do componente, ou chegou a ele a partir de um âmbito mais amplo ou por expansão orientada por anotações.
- A ausência da metade de posição significa que o conjunto de posições declaradas do Component anfitrião não pôde ser resolvido — por exemplo, o seu tipo não corresponde a nenhuma entidade de catálogo. Isto é deliberadamente distinto de
[free]:[free]responde «não está declarada nenhuma posição com esse nome», enquanto uma metade ausente significa que a pergunta não pôde de todo ser respondida. - A ausência de
sensitiveregista que nenhuma declaração marcou a anexação. Isto é mais restrito do que um veredicto de que a anexação não contém nada secreto; o eixo reporta declarações, e nada é deduzido do nome de um campo nem do seu valor. - A ausência da metade de realização significa que o Manifest não associa a anexação a nenhuma FeatureRecipe que o catálogo contenha.
Uma posição cujo nome declarado seja literalmente free é também apresentada como [free], indistinguível de uma anexação de forma livre — nada reserva essa palavra no espaço de nomes das posições.
Gramática dos parênteses de proveniência do IR
Cada anexação de Feature na vista da Release contém um parêntese de proveniência. O parêntese pode assumir uma forma compacta (um parêntese por Feature quando a proveniência da anexação é uniforme em todas as folhas) ou uma forma por folha (um parêntese por folha quando as folhas da anexação vêm de origens heterogéneas). Existem três corpos de parêntese; aplicam-se da mesma forma a ambas as formas.
Os três corpos de parêntese
-
[explicit]— a anexação de Feature é declarada pelo autor. O Aggregate ou a Release nomeou explicitamente a Feature no nó afetado. As anexações explícitas são a origem de maior prioridade; prevalecem sempre sobre as contribuições orientadas por anotações na mesma folha. -
[annotation: <key> from <source>]— a anexação de Feature é orientada por anotações. O compilador sintetizou-a porque uma anotação em<source>correspondeu a uma associação do Manifest que declara esta Feature.<key>é a chave de anotação que ativou a associação (p. ex.,business.aggrega.ai/team);<source>é a entidade que continha a anotação (aggregate,release,componentoumanifest). A anexação sintetizada é estruturalmente idêntica a uma explícita — a renderização a jusante trata ambas da mesma forma — mas o parêntese de proveniência distingue-as para que a depuração continue a ser decidível. -
[explicit; overrides annotation: <key> from <source>]— uma forma por folha que surge quando uma declaração explícita do autor numa folha está a suprimir uma contribuição de anotação que de outro modo teria definido a mesma folha. A composição entre lados produz este caso: uma anotação do Aggregate pode fornecer o pilarvalues:de uma Feature, uma anotação da Release fornece o seu pilarinfra:, e uma declaração explícita da Release na mesma Feature substitui uma folha de infra. O parêntese da folha regista tanto o autor explícito como a anotação que foi suprimida; a anotação suprimida não contribui para a saída renderizada, mas a sua presença aparece na vista de inspect para que o operador possa ver que anotação foi substituída e onde.
Forma compacta vs. forma por folha
O compilador escolhe entre a apresentação compacta e a por folha percorrendo a proveniência por folha da anexação e verificando a uniformidade. A proveniência de uma anexação é uniforme quando todas as folhas preenchidas (nos pilares values: e infra: da Feature) partilham a mesma origem (explícita vs. anotação), a mesma chave de anotação quando orientada por anotações e a mesma entidade de origem, e nenhuma folha contém um marcador «overrides annotation». Quando a proveniência é uniforme, o compilador emite um parêntese por anexação:
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]Quando a proveniê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 parêntese 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 de percurso é primeiro o pilar values (pela ordem do autor) e depois o pilar infra (com a mesma disciplina). O prefixo do pilar (values. / infra.) e o caminho com pontos dentro do pilar indicam exatamente que folha cada parêntese anota.
Valores declarados sensíveis
Uma folha cujo esquema declara sensitive: true imprime o texto fixo <redacted> em vez do seu valor. A chave, o prefixo do pilar e o parêntese de proveniência são todos mantidos — só o valor é substituído — pelo que a disposição continua a responder a que folhas uma entidade contém e de onde veio cada uma. São afetadas duas superfícies legíveis: o bloco Values: por nó de um Aggregate, e o bloco de anexações por folha de uma Release resolvida — incluindo uma anexação escrita numa ligação, impressa sob a linha dessa ligação, que oculta exatamente as folhas que a mesma Feature oculta quando o próprio componente a deté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>Só uma folha declarada é ocultada, e a cláusula [sensitive] ao nível da anexação não é uma instrução de ocultação: indica que a anexação lida com material secreto, não quais das suas folhas o contêm. Os localizadores publicados de uma Feature de credenciais — 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, pelo que são impressos em claro ao lado do material que não 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 é deduzido do nome de um campo: um campo chamado password sem declaração imprime o seu valor, e um campo declarado chamado key não. A ocultação abrange o que a ferramenta imprime; nunca chega a um artefacto 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 os ocultar, em todas as superfícies de inspect ao mesmo tempo — tanto nas disposições legíveis acima como no grafo compilado de uma Release. Existe porque o valor ocultado é por vezes precisamente o que está a ser investigado: uma credencial vinda da anexação errada parece idêntica à correta quando ambas aparecem como ocultadas.
Está circunscrita ao comando a que é passada. aggrega build e aggrega validate também a aceitam, onde chega ao grafo que --ir-graph devolve e a nada mais, e recusam-na quando nenhum grafo foi pedido. aggrega build --trace-unredacted é a mesma ideia nos ficheiros de rastreio da compilação, e nenhuma das duas flags da compilação chega à saída da outra; um artefacto renderizado em dist/ não é afetado por nenhuma delas, porque é emitido exatamente como a renderização o produziu, seja o que for que se passe.
Tudo aquilo a que a saída chegue passa então a transportar esses valores em claro — um terminal, um pipe, um ficheiro, uma gravação de ecrã, um relatório de erro colado. Ao contrário dos ficheiros de rastreio, que começam cada um com um cabeçalho a indicar que foram capturados sem ocultação, a saída num terminal não contém nenhuma marcação desse tipo: só a linha de comandos indica que foi passada.
Quando recorrer a inspect
- Depurar «porque está esta Feature aqui?» — as anexações orientadas por anotações são invisíveis nos ficheiros YAML do Aggregate e da Release (as anotações estão lá, mas as anexações de Feature que sintetizam existem apenas no IR). Inspect apresenta-as com a sua proveniência.
- Verificar a herança de esquemas —
aggrega inspect <ComponentName>mostra o esquema fundido depois de a cadeiaextends:ser resolvida; o ficheiro escrito por si só mostra apenas a diferença local. - Diagnosticar surpresas da composição entre lados — quando uma anotação do Aggregate e uma anotação da Release fornecem ambas conteúdos de pilar na mesma Feature, as folhas resolvidas podem ser difíceis de reconstruir mentalmente. A forma de parêntese por folha torna a resolução explícita.
- Verificação antes da implementação —
aggrega inspect ./prod-release.yamllista todas as Features em todos os Components antes deaggrega buildproduzir artefactos; o operador pode confirmar que a topologia corresponde à intenção antes de confirmar os 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 das Features e como a disciplina de prevalência da anexação explícita interage com as contribuições orientadas por anotações — consulte providers/well-known-annotations.md e entities/manifest.md, «Associaçõ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, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich 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 ownkind: 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: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor 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 declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — 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 reachedwithout appearing as a node, and a node does not carry the version its typeresolved 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'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.Flags
| Flag | Predefinição | Descrição |
|---|---|---|
--catalog | [] | Diretório de catálogo; repetível. Cada —catalog <dir> é colocado no início da pilha de pesquisa de catálogos (a primeira correspondência prevalece): os catalog_dirs do espaço de trabalho ou, para uma Release à qual a configuração do espaço de trabalho atribui diretórios próprios em workspace.releases, os dessa Release; a pilha termina com o diretório chamado catalog na raiz do espaço de trabalho, quando existe. Uma lista catalog_dirs escrita vazia não lê nenhum catálogo local. |
--closure | false | Reportar o fecho de dependências da Release — todas as entidades de catálogo que alcança, na versão em que cada uma foi resolvida — em vez da vista de nós resolvidos. Aplica-se a uma Release, que é o único tipo que resolve um fecho; qualquer outro tipo recusa o pedido em vez de o descartar silenciosamente. |
--color | auto | Colorir a saída: auto|always|never. |
--detail | false | Apresentar os corpos completos dos campos. |
--flat | false | Apresentar uma entidade em forma de árvore (Aggregate, Release) como lista plana, com cada nó precedido do seu caminho completo com pontos. Sem efeito nos tipos tabulares. |
--ir-graph | false | Escrever também no stdout, em 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-lhe ocultados; passe —unredacted para os imprimir em vez disso. Aplica-se a uma Release, o único tipo que se resolve num grafo; qualquer outro tipo recusa o pedido em vez de o descartar silenciosamente |
--list | false | Apresentar apenas os identificadores. |
--no-color | false | Desativar a saída colorida (alias de —color=never). |
--output, -o | text | Formato de saída: text|yaml. |
--plugin | — | Caminho no sistema de ficheiros para um artefacto <file.wasm> em bruto; deriva e imprime as funções do anfitrião que importa, antes de aggrega plugin sync as registar numa entidade Plugin. Não aceita nenhum argumento identificador. |
--raw | false | Apresentar a entidade tal como foi escrita, sem resolução. |
--release | — | Procurar um nome de catálogo nos termos deste ficheiro de Release: através dos diretórios de catálogo que a configuração do espaço de trabalho atribui a essa Release, com —catalog colocado no início. Aplica-se a um nome; um ficheiro ou uma referência de registo é inspecionado tal como está e recusa-a. Um caminho relativo é resolvido em relação ao diretório em que o comando é executado, não em relação à raiz do espaço de trabalho. Quando esse diretório não está em nenhum espaço de trabalho e nenhuma raiz é nomeada, um caminho absoluto encontra o espaço de trabalho a partir da própria pasta da Release |
--resolved | false | Apresentar a entidade totalmente resolvida. |
--show-implements | false | Para uma Recipe ou FeatureRecipe, resolver spec.implements contra o catálogo e apresentar o Component ou a Feature associados. |
--unredacted | false | Imprimir os valores que um autor declarou sensíveis em vez de os ocultar. Tudo aquilo a que a saída chegue — um terminal, um pipe, um ficheiro, uma gravação de ecrã — passa então a transportar esses valores em claro. |