Pilares de dados
O enquadramento conceitual das cinco palavras-chave estruturais da DSL — parameters, values, uses, infra, inject — fica em architecture/06-data-taxonomy-and-composition.md. Esta página cobre a lista canônica de pilares de dados, a semântica de autoria por pilar, a mecânica entre pilares e o vocabulário de valores padrão que os autores encontram nos diferentes pilares. A tríade topológica complementar (provides, inject, uses — palavras-chave que conectam as arestas do grafo) está documentada em topology-triad.md; o vocabulário de metadados distinto dos pilares de dados (rótulos, anotações, campos da superfície de publicação) fica em labels-and-annotations.md e publishing-surface.md.
Lista canônica de pilares
As entidades do Aggrega carregam sete pilares de dados nomeados. Cinco participam do fluxo de dados da IR como estado vivo durante toda a renderização; dois são transitórios ou privados e existem apenas em etapas específicas da compilação.
| Pilar | Fica em | Ciclo de vida | Papel |
|---|---|---|---|
values | Instâncias de componente / vinculação do Aggregate | Vivo durante toda a renderização | Payload cognitivo escrito pelo desenvolvedor |
infra | Entradas de componente, vinculação e conexão da Release | Vivo durante toda a renderização | Dimensionamento físico escrito pelo operador |
provides | Bloco provides: da Recipe | Vivo durante toda a renderização (pilar derivado — veja abaixo) | Strings de saída públicas calculadas pela Recipe que o pipe topológico consome |
uses | Instâncias de componente / funcionalidade do Aggregate | Vivo durante toda a renderização | Arestas topológicas para outros componentes / funcionalidades |
features | Instâncias de componente do Aggregate + Release; slots declarados no featuresSchema de uma entidade do catálogo — veja “Features pillar (Pilar Features)” abaixo | Vivo durante toda a renderização | Pilar de vinculações — uma única forma para cada família de vinculações |
parameters | Raízes do Aggregate + Release | Legível até o fim do pipeline, até que toda fase de renderização seja concluída; acessível aos templates de caminho durante a renderização por meio da concessão assimétrica; os contextos de template de valor consomem os literais pós-interpolação em vez de .parameters diretamente | Slots por ambiente atendidos pela Release |
locals | Bloco locals: da Recipe | Privado da Recipe — visível apenas dentro dos templates da própria Recipe | Estado de string calculado que as Recipes derivam no preâmbulo de locals |
values / infra / provides / uses / features são os cinco pilares vivos que o contexto de template em tempo de execução expõe por meio de .values, .infra, .provides, .context.uses e .features, respectivamente. parameters e locals ficam fora da lista de pilares vivos — parameters porque não sobrevive à resolução; locals porque é privado da Recipe e nunca cruza as fronteiras das entidades.
Os pilares são sinalizações, não muros: o mecanismo de templates permite leituras entre pilares em todo ponto, a menos que regras de autocontenção as proíbam explicitamente (um bloco provides: de Recipe e um bloco source: de Recipe lendo .context.inject / .context.uses; documentado em templates/expansion-matrix.md). As fronteiras dos pilares são disciplina de autoria, não uma imposição da linguagem.
Fronteiras dos pilares e disciplina de autoria
As leituras entre pilares a partir de um template de Recipe não têm restrições em todo ponto que permite o contexto de template completo. A disciplina de autoria espera que os autores:
- Leiam
.valuespara o payload cognitivo (intenção escrita pelo desenvolvedor). - Leiam
.infrapara o dimensionamento físico (dimensionamento escrito pelo operador). - Leiam
.context.uses[].provides.<key>para as strings de ponteiro entre componentes (o fluxo de dados da tríade topológica). - Leiam
.context.injectpara o pipe de entrega pós-hidratação (montado a partir das fontes de inject emcomponent.inject,uses[].injecte das interceptaçõesinjectMappingde FeatureRecipe).
A disciplina são sinalizações, não muros. Um template de Recipe que lê .infra.replicas para alimentar um campo values: funciona; o mecanismo de templates não bloqueia a leitura. O enquadramento da arquitetura é que as fronteiras dos pilares descrevem a intenção de autoria — quem é dono dos dados — em vez de uma restrição em tempo de execução. As convenções correspondem à divisão em quatro domínios: os valores escritos pelo desenvolvedor vêm de .values; o dimensionamento escrito pelo operador vem de .infra; as coordenadas entre componentes vêm do pipe topológico.
Quando é necessária uma ponte deliberada entre pilares — por exemplo, o schema: de um Component expõe um controle voltado ao desenvolvedor que o template valuesMapping: da Recipe canaliza para uma saída com a forma de infra: do lado de Ops, conforme vocabulary/inheritance-and-interface.md — a arquitetura trata a ponte como uma exceção sinalizada. Veja “Cross-pillar mechanics (Mecânica entre pilares)” abaixo.
Values
O pilar values: carrega o payload cognitivo escrito pelo desenvolvedor — os parâmetros com a forma da aplicação que o desenvolvedor dita para cada instância de componente. O schema: do Component declara a forma dos valores; o Aggregate do desenvolvedor preenche valores concretos por instância. Este é o domínio do desenvolvedor.
Escrito em:
- Aggregate
components.<id>.values:— payload cognitivo por instância de componente. - Aggregate
subsystems.<name>.components.<id>.values:— o mesmo, dentro de componentes agrupados em subsistemas. - Aggregate
components.<id>.features.<name>.values:efeatures.<name>.values:de um subsistema — payload de valores da vinculação, seja qual for a família a que pertence a Feature vinculada (os parâmetros de consulta ao vault de uma vinculação de credenciais são escritos aqui como qualquer outro).
Proibido em:
- Entidade Release (o esquema da Release proíbe um bloco
values:em qualquer nível de aninhamento — o Parameter Hoisting é o caminho suportado para a variação por ambiente; veja Parameters abaixo).
Validado por: o bloco values: do schema do Component (e o bloco values: do schema da Feature para vinculações de Feature), resolvido para JSON Schema 2020-12 no carregamento do Component / da Feature conforme vocabulary/validation-surface.md, camada 2.
Consumido por: os templates valuesMapping: da Recipe por meio de .values. O contexto de template completo expõe o dicionário de valores resolvidos em todo ponto de template da renderização base.
Infra
O pilar infra: carrega o dimensionamento físico escrito pelo operador — réplicas, solicitações de recursos, limites de IOPS, fixação de região, classe de máquina. Ele expressa o onde e de que tamanho, complementando o o quê e como se comporta dos values. Este é o domínio do operador.
Quatro superfícies de autoria
Os autores encontram infra: em quatro superfícies distintas, cada uma com escopo diferente e comportamento de cascata diferente:
| # | Superfície | Escopo | Precedência de mesclagem |
|---|---|---|---|
| 1 | Fronteira da Release components.<id>.infra: (spec.components.<id>.infra: em uma Release sem fronteiras) | Uma instância de componente | O dimensionamento próprio do componente; nenhuma outra superfície o escreve |
| 2 | Fronteira da Release features.<name>.infra: | Uma vinculação de escopo de fronteira, em cada componente da fronteira | A mais baixa para essa vinculação — a superfície 3 a sobrescreve campo a campo |
| 3 | Fronteira da Release components.<id>.features.<name>.infra: | Uma vinculação em um componente | Sobrescreve a superfície 2 para essa vinculação, campo a campo |
| 4 | Release components.<id>.uses.<socket>.<alias>.infra: | Uma conexão | Validado contra o infraSchema do socket; alcança apenas a renderização do componente consumidor |
A superfície 1 é a mais escrita: um operador dimensiona cada componente que a Release posiciona. Uma fronteira não carrega nenhum infra: próprio — o esquema da Release o recusa —, então um dimensionamento que vários componentes compartilham é escrito em cada um, ou herdado de uma Release pai por meio de extends: (abaixo). As superfícies 2 e 3 cobrem o dimensionamento de vinculações de Feature — as Features carregam o seu próprio payload infra, que a FeatureRecipe consome ao sintetizar sidecars ou recursos por Feature: uma vinculação de escopo de fronteira é dimensionada uma vez, e um componente ajusta um único campo dela.
“Infra principalmente localizado” — a regra com exceções
O objetivo arquitetural para infra: é local ao componente: o dimensionamento de um componente se aplica àquela instância de componente e não vaza para outros componentes. É o mecanismo que permite a Ops aumentar os IOPS do banco de dados sem afetar a solicitação de CPU do servidor de API.
A regra: infra: é principalmente localizado na superfície que o escreveu. Exceções em cascata existem por design:
- Cascata de anotações da fronteira. As
annotations:de uma fronteira se propagam em cascata pelas fronteiras aninhadas até os componentes internos (superfície 5 da matriz de anotações em labels-and-annotations.md). As anotações consumidas pelas Recipes como entrada de roteamento se tornam um alcance indireto deinfra— a anotação no nível da fronteira flui por.context.annotations.releasepara a saída renderizada da Recipe por nó. - Herança de Release via
extends:. Uma Release que fazextends:de uma Release pai herda as declaraçõesinfrado pai em toda superfície que as carrega, a menos que a filha as sobrescreva por chave. O valor da filha vence chave a chave, até o primeiro valor indivisível — um escalar, uma lista, um template —, que é substituído por inteiro, e uma chave que a filha escreve comonullé removida em vez de definida como nada. A herança cruza deliberadamente a fronteira de cada Release; para a regra de mesclagem completa e o que mais viaja com ela, vejaentities/release.md. - Canalização entre pilares por ponte de esquema. O
schema:de um Component pode expor um controlevalues:voltado ao desenvolvedor que o templatevaluesMapping:da Recipe canaliza para a saída do provedor com a forma deinfra:(veja “Cross-pillar mechanics — Schema-bridge cross-pillar piping (Mecânica entre pilares — Canalização entre pilares por ponte de esquema)” abaixo). A rigor, o valor se origina emvalues:e flui para a saída renderizada; a cascata é interna à instância, mas entre pilares.
A localização é a intenção de design, não um muro que o mecanismo impõe: as cascatas acima são exceções deliberadas, cada uma documentada na superfície que a carrega.
Partição entre lado e pilar para a expansão de Feature orientada por anotações. A invariante do Aggregate como superfície de autoria se estende ao caminho de expansão de Feature orientado por anotações: as anotações do lado do Aggregate (escopo de subsistema e de instância de componente) só podem acionar subchaves maps.values; as anotações do lado da Release (escopo de fronteira e de instância de componente) só podem acionar subchaves maps.infra. Um binding de Manifest pode declarar caminhos em ambos os pilares; cada lado aciona apenas o seu subconjunto compatível, e a composição entre lados mescla as contribuições campo a campo no momento do build da IR. A partição preserva a separação de autoria values-desenvolvedor / infra-operador na superfície de anotações — a mesma separação que values: e infra: impõem nas superfícies de vinculação explícita. Veja providers/well-known-annotations.md §“Side-vs-pillar partition per subkey (Partição entre lado e pilar por subchave)” para a explicação por subchave e o padrão de composição entre lados.
Provides
O pilar provides: é derivado — uma Recipe o declara, mas, ao contrário de values / infra, o desenvolvedor não o escreve diretamente. As Recipes calculam as strings de saída públicas que o pipe topológico vai consumir.
O bloco provides: de uma Recipe é um mapa de pares <key>: <template>. Cada template é avaliado contra a superfície autocontida da própria Recipe (.values, .infra, .context.instance_id, .context.rendered_name quando o provedor do nó informa um, e os .locals resolvidos do nó) durante a avaliação dos provides. As strings resultantes são expostas por meio de .provides e consumidas pelos blocos uses[].inject dos chamadores por meio de referências from: "<key>". .locals está disponível porque os locals do nó são resolvidos no preâmbulo dessa etapa, antes dos seus provides (veja Locals abaixo); nomear uma chave que o bloco locals não declara provoca uma interrupção.
Invariante de autocontenção. Os templates provides: de uma Recipe não devem referenciar .context.inject nem .context.uses. A avaliação dos provides executa esses templates em qualquer ordem — eles se fecham apenas sobre os dados do próprio nó, então a ordem não importa. Referências entre nós acoplariam essa avaliação à ordem de iteração topológica, o que o design evita deliberadamente. Veja templates/expansion-matrix.md, linha 6, para a regra e a sua justificativa.
Por que provides: é um pilar. As strings de saída são a superfície pública canônica de toda Recipe; os consumidores a jusante (uses[].inject do chamador, blocos injectMapping de FeatureRecipe que leem os provides resolvidos do destino por meio de .context.uses) tratam o dicionário como um contrato tipado. Nomear provides: como pilar reconhece o seu status de primeira classe ao lado de values / infra / uses / features. Tratá-lo como “apenas um detalhe interno da Recipe” subestima o seu papel como principal fonte de dados do pipe topológico.
Uses
O pilar uses: é a declaração das arestas topológicas. O bloco uses: de uma instância de componente nomeia as arestas das quais o componente participa — os sockets por meio dos quais ele consome destinos. A gramática completa está documentada em topology-triad.md; esta seção nomeia uses: como pilar por completude.
uses: fica nas instâncias de componente do Aggregate + vinculações de funcionalidade; o contexto de template em tempo de execução expõe uma entrada por conexão de saída, indexada pelo seu alias, como .context.uses. A projeção carrega os metadados resolvidos do destino de cada aresta (os provides do destino, rótulos, anotações) para que as Recipes dos chamadores possam ler strings de ponteiro entre componentes na avaliação de templates da renderização base, e as vinculações escritas nessa conexão, em .context.uses.<alias>.features.<slot>.
Pilar Features
features: é o pilar de vinculações: uma palavra-chave, uma forma, toda vinculação. Uma Feature operacional, uma Feature de credenciais e uma Feature de identidade são todas declaradas aqui sob o nome de instância que o autor escolhe. O contexto de template em tempo de execução expõe as vinculações do nó como .features.<name>, cada uma com type, values, infra e os provides resolvidos da vinculação. Uma vinculação escrita em uma das conexões do componente é exposta nessa mesma forma sob a conexão, em .context.uses.<alias>.features.<slot>, e nunca sob .features — assim, uma Recipe que percorre .features encontra apenas as vinculações do próprio componente (veja o contrato do contexto de templates).
Uma vinculação cujo nome de instância corresponde a um slot que a entidade declara em featuresSchema preenche esse slot; qualquer outro nome de instância é uma vinculação livre. Preencher um slot é o que conecta as quatro superfícies que uma credencial baseada em slot percorre:
| Superfície | Onde é escrito | Papel |
|---|---|---|
Component / Feature featuresSchema: | entidade do catálogo | Declara os slots que a entidade espera; por slot, delimita a allowlist de entrega (env / file / blackbox) e, opcionalmente, um seletor de rótulos que o preenchimento deve satisfazer |
Aggregate components.<id>.features.<slot>: | Instância de componente do Aggregate | Preenche o slot com uma vinculação; fornece os values: próprios da vinculação e, para um slot transparente, o seu mapeamento inject: |
Workload containers.<name>.attachments.<KEY>.from/as: | Corpo de Workload da Recipe | Referencia um slot declarado — ou, ao lado de connection: <alias>, um slot que o socket dessa conexão declara — e dita a entrega por contêiner do que o preencheu |
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:) | a FeatureRecipe associada | Produz a saída da vinculação — um recurso emitido, uma reescrita da entrega, ou ambos |
O nome do slot é o identificador essencial nas quatro: a superfície 1 o declara, as superfícies 2–4 o referenciam, e o fluxo de dados segue uma única direção (declarar → preencher → referenciar → produzir).
Para a checklist de autoria, veja examples/04-secrets.md “The secret-delivery checklist (A checklist de entrega de segredos)”.
Locals
O pilar locals: é estado privado da Recipe. O bloco inteiro é resolvido no preâmbulo de locals, antes do provides: desse nó; as strings resultantes ficam visíveis para cada um dos templates posteriores da própria Recipe — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Um template provides: que nomeia uma chave que o bloco não declara provoca uma interrupção.
Escrito em: bloco spec.locals: da Recipe — um mapa de pares <key>: <template> avaliados contra uma superfície autocontida local ao nó: .context.instance_id, .values, .infra e as entradas do mesmo bloco já resolvidas. Nada mais está nela: .provides, .metadata e o restante de .context.* não estão, e uma referência a qualquer um deles provoca uma interrupção.
A ordem é essencial. As entradas são resolvidas na ordem escrita e uma entrada pode ler uma entrada irmã definida acima dela, recebendo o seu valor resolvido. O encadeamento corre apenas para baixo — quando uma entrada lê outra, mover a definição para baixo do seu leitor é recusado, e o compilador nunca reordena o bloco para fazer a referência se resolver. Uma referência a uma entrada posterior provoca uma interrupção que nomeia a falha de ordem; uma referência a uma chave não declarada provoca uma interrupção que nomeia a chave. Em uma Recipe cujo source: é um bloco estruturado, ambas as falhas também são recusadas enquanto o artefato que ele nomeia é fixado, de modo que aggrega pull as informa antes que qualquer build renderize saída. A verificação lê o caminho para o qual uma referência se resolve em vez das teclas digitadas, então alcança igualmente a forma direta, um bloco with .locals, uma variável ligada a .locals e o bloco entre parênteses, (.locals).<key> ou ($.locals).<key>. Uma grafia que ela não cobre: uma chave alcançada por meio de uma função, como index .locals ou (default dict .locals).<key>. Uma chave ausente alcançada dessa forma não provoca interrupção, e renderiza o texto literal <no value> em vez de nada — exceto por meio do próprio index, que provoca uma interrupção nomeando a chave em toda superfície de template quando o mapa que ele lê não a contém.
Visibilidade: privado da Recipe. Não existe um campo .context.uses[].locals — um chamador não pode ler os locals do seu destino pela aresta. O que um chamador pode ler é o provides: do destino.
Casos de uso:
- Calcular strings de ponteiro internas da Recipe (por exemplo,
secret_target_admin_password: "redis-auth", o sufixo do nome de um Secret) que tanto ovaluesMapping:quanto oprovides:da Recipe consomem, e que uma FeatureRecipe de credenciais vinculada ao mesmo componente lê como.locals.secret_target_admin_password— os templates de uma vinculação veem os locals resolvidos da Recipe hospedeira mesclados com os próprios da vinculação. No destinohelm, cada um deles escreve o nome completo como{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}: o nome renderizado é o nome do componente escrito nos caracteres que um nome do Kubernetes permite, e um local não pode lê-lo, então o local carrega o sufixo e cada leitor junta os dois. - Aplicar DRY a valores calculados repetidos dentro de uma Recipe (um hostname calculado uma vez, referenciado a partir de vários campos
valuesMapping:). - Valores intermediários para lógica de template complexa que seria ilegível inline.
provides: e locals: — face pública versus face privada
Os dois pilares do lado da Recipe carregam uma separação deliberada de visibilidade que os autores devem ter em mente:
provides:é a face pública. Cada chave é a superfície canônica do pipe topológico — os blocosuses[].injectdos chamadores a jusante as consomem por meio de referênciasfrom: "<key>". O dicionárioprovides:é um contrato tipado do qual os chamadores dependem; renomear ou remover uma chave é uma alteração incompatível para toda Recipe cujas declaraçõesuses[].injecta referenciam.locals:é a face privada. Cada chave é estado interno da Recipe, visível apenas dentro dos templates subsequentes da própria Recipe. Nenhum chamador pode ler os locals de uma Recipe; os nomes emlocals:não fazem parte de nenhuma interface publicada, e renomeá-los é uma refatoração interna da Recipe sem efeito a jusante.
Os dois também são ordenados: locals: é resolvido primeiro, então provides: pode ler .locals, mas locals: não pode ler .provides. Publicar o valor de um local por meio de provides: significa, portanto, adicionar uma entrada provides que lê o local — a expressão fica em um só lugar.
A separação é deliberada, conforme a separação arquitetural entre os internos da Recipe (privados) e a interface da Recipe (pública). Autores que tratam provides: e locals: como um único namespace perdem a distinção de visibilidade e correm o risco de expor estado interno pelo pipe topológico — toda chave declarada em provides: passa a fazer parte da superfície contratual da Recipe, quer o autor tenha pretendido isso ou não. O objetivo da disciplina: declarar uma chave primeiro em locals:; promovê-la a provides: somente quando um chamador a jusante realmente precisar dela.
A visibilidade é definida pelo pilar em que uma chave é declarada: não há um marcador de visibilidade por chave, então um valor ao mesmo tempo privado e publicado é uma entrada locals: mais uma entrada provides: que a lê.
Parameters
Tanto o esquema Aggregate quanto o esquema Release carregam um dicionário parameters na sua raiz. Os desenvolvedores declaram as chaves que o Aggregate espera; Ops preenche os valores a partir de arquivos de Release específicos de cada ambiente. Esse desacoplamento é o mecanismo da promoção GitOps: um único Aggregate.yaml imutável passa pelos ambientes Dev, Staging e Production, com a Release de cada ambiente fornecendo os seus próprios valores de parâmetros.
spec: parameters: corp_db_name: type: string required: true env_workers: type: integer required: true region: type: string required: true enable_debug: type: boolean required: true components: my-backend: type: core/python-worker:1.0.0 values: workers: {{ .parameters.env_workers }} region: "{{ .parameters.region }}"# release-prod.yaml — inline parameter valuesspec: aggregate: my-app manifest: prod-manifest parameters: corp_db_name: "enterprise_data" env_workers: 10 region: "eu-west-1" enable_debug: falsePara fluxos de CI/CD que mantêm os valores dos parâmetros em um arquivo separado (por exemplo, um .yaml por ambiente versionado ao lado da Release), a Release usa a forma $import:: parameters: { $import: ./prod-values.yaml }. O conteúdo do arquivo substitui o mapa inline na superfície da Release. O caminho é resolvido a partir do diretório que contém a Release, seja de onde for que um comando seja executado, e deve levar a um arquivo dentro do workspace — ou, para uma Release indicada fora do workspace, dentro do diretório que a contém. A sobreposição de vários arquivos (combinar um arquivo base com um overlay específico do ambiente) é expressa por cadeias extends: de Release — a Release pai fornece os parâmetros base; a Release filha estende e sobrescreve por chave.
Ciclo de vida dos parâmetros. O compilador resolve os parâmetros em três fases. (1) Preenchimento de padrões — os slots com default: definido e sem valor da Release recebem o seu padrão. (2) Validação do contrato de parâmetros — o contrato tipado parameters: valida cada valor contra as suas restrições declaradas type / enum / min / max / pattern, incluindo um padrão preenchido, de modo que um padrão que viola o próprio contrato interrompe o build. (3) Interpolação — o compilador avalia todo o texto do Aggregate como um template e substitui cada referência {{ .parameters.<slot> }} pelo valor resolvido. O mapa mesclado continua então legível durante a renderização, para que os templates de caminho (fronteira da Release directory: / subDirectory:) possam ler .parameters.<slot> diretamente, contra a allowlist fechada documentada em ../path-template-variables.md. As superfícies de template de valor (Recipe valuesMapping, FeatureRecipe injectMapping / provides / pipeline.with, corpos de Workload) NÃO recebem .parameters no seu contexto de template — elas consomem os valores resolvidos escritos nas strings values: circundantes pela interpolação da fase 3.
A checklist da elevação de parâmetros
Todo valor que varia entre ambientes passa em sequência por quatro pontos de contato de autoria. O modelo mental que os autores carregam: para qualquer valor que varie entre Dev / Staging / Production, espere mexer no Aggregate (declarar), no template de values (referenciar), na Release (atender) e no template da Recipe (consumir).
| Etapa | Superfície | Ação |
|---|---|---|
| 1 | Aggregate spec.parameters.<name> | Declare o parâmetro como parte do contrato de autoria tipado do Aggregate. Cada slot de parâmetro carrega um type declarado (string, integer, number, boolean, array, object), uma description opcional, um default opcional, restrições opcionais do espaço de valores (enum, min, max, pattern, minLength, maxLength) e uma estrutura aninhada opcional para slots do tipo objeto. O contrato valida cada valor fornecido pela Release antes da interpolação. |
| 2 | Template values: do Component dentro do mesmo Aggregate | Referencie o parâmetro por meio de {{ .parameters.<name> }} de dentro do bloco values: de qualquer componente (ou funcionalidade, ou subagregado) que o consome. A referência é uma expressão de template Go — o compilador a avalia durante a fase de interpolação da resolução. |
| 3 | Release spec.parameters.<name> (inline ou parameters: { $import: ./path.yaml }) | Atenda o parâmetro com o valor específico do ambiente na superfície da Release. Arquivos de Release por ambiente fornecem valores diferentes para a mesma chave de parâmetro sem modificar o Aggregate. |
| 4 | Template valuesMapping: da Recipe | Consuma o valor resolvido por meio de {{ .values.<key> }} — a Recipe é uma superfície de template de valor; o seu contexto de template não carrega .parameters diretamente. A variação por ambiente chega à Recipe pelo dicionário values: pós-interpolação que a fase de interpolação acima escreve. (Os templates de caminho nas fronteiras da Release são a exceção: eles leem .parameters.<slot> diretamente durante a renderização, conforme a concessão assimétrica.) |
Os quatro pontos de contato são sequenciais e essenciais: pular a declaração no Aggregate deixa a Release sem slot para atender; pular a referência nos values deixa a Recipe sem valor para consumir; pular o atendimento na Release deixa o parâmetro vazio. O compilador valida a cadeia durante a resolução (validação do contrato de parâmetros contra a declaração tipada parameters:, depois interpolação nas strings values: circundantes, depois validação com JSON Schema do dicionário values: resultante contra o schema: do Component ou da Feature); as divergências aparecem como uma violação do contrato de parâmetros (detectada contra a declaração tipada parameters:), um erro de template não preenchido (detectado na interpolação) ou uma violação de restrição de JSON Schema contra o esquema values: (detectada na validação de esquema).
O padrão é o mecanismo canônico da promoção GitOps: um único Aggregate imutável passa pelos ambientes, com a Release de cada ambiente fornecendo os seus próprios valores de parâmetros. Todo valor por ambiente que um autor queira variar pertence à cadeia de parâmetros, em vez de ficar embutido diretamente no Aggregate.
Semântica de mesclagem de extends: por pilar
Quando uma entidade do catálogo declara extends: e o compilador percorre a cadeia de herança, o conteúdo de cada pilar é mesclado segundo regras específicas do pilar. A semântica difere entre os pilares; a tabela abaixo é a referência canônica por pilar.
| Pilar | Comportamento de mesclagem em uma cadeia extends: |
|---|---|
values (JSON Schema 2020-12) | Em uma cadeia de Feature, os esquemas se compõem por meio da composição de JSON Schema 2020-12. Um Component que estende não escreve nenhum conteúdo de pilar e recebe o bloco da sua base exatamente como a base o escreveu, em qualquer profundidade de uma cadeia. |
infra (fragmento de JSON Schema 2020-12) | Igual a values — composto em uma cadeia de Feature, herdado por inteiro por um Component que estende. |
provides (mapa de templates da Recipe) | Substituição rasa de primeiro nível: a chave filha substitui totalmente a chave pai de mesmo nome; as chaves irmãs são preservadas do pai. Os templates não são compostos; o template da filha é totalmente dono do seu slot. |
uses (usesSchema) | Sobreposição da entrada inteira por socket, por nome de socket. Uma filha adiciona sockets que a sua base não declara, e um socket que ela redeclara sob um nome existente substitui essa entrada por completo — os seus esquemas de valor e de infra e o seu selector juntos. As entradas de socket não são compostas, e nada compara um selector redeclarado com o da base. |
features (esquema por slot de featuresSchema) | Sobreposição da entrada inteira por slot, por nome de slot, nos mesmos termos de usesSchema. Uma filha adiciona slots livremente; um slot que ela redeclara substitui por completo a entrada da base em vez de se compor com ela. |
locals (mapa de templates da Recipe) | Substituição rasa de primeiro nível — igual a provides. |
parameters (mapa raiz do Aggregate) | Um Aggregate não tem campo extends:, então nenhuma cadeia de Aggregate mescla parâmetros. Em uma cadeia extends: de Release, um parâmetro com valor de mapa é mesclado em profundidade com prevalência da chave filha, um com valor escalar é substituído pela filha, e uma chave que a filha escreve como null é removida. |
O padrão geral depende do tipo e da superfície. Os pilares validados por esquema de uma Feature se compõem sob JSON Schema 2020-12. Os pilares de um Component que estende são herdados por inteiro — ele não escreve nenhum, então o seu contrato é exatamente o da sua base, e uma restrição da base, portanto, não pode ser relaxada, por construção. As superfícies de forma fixa — usesSchema e featuresSchema — se sobrepõem por nome em ambos os tipos: uma filha adiciona entradas, e uma entrada que ela redeclara substitui por completo a da base. Os pilares escritos como template usam substituição rasa por chave, dando à filha a propriedade total de qualquer slot de template que ela declare.
Um Component que estende reforça uma restrição por meio de assertions: em vez de um pilar — um predicado que ele adiciona, avaliado junto com os que herda. Veja inheritance-and-interface.md para esse mecanismo.
Para o mecanismo de herança em si, veja inheritance-and-interface.md “Inheritance via extends (Herança via extends)”, que cobre os tipos do catálogo. Uma Release não é uma entidade do catálogo e é combinada pela sua própria regra; essa regra está em entities/release.md “Composite Release and extends: inheritance (Release composta e herança com extends:)”.
Mecânica entre pilares
O enquadramento de sinalizações permite leituras entre pilares em todo lugar, exceto nas superfícies de autocontenção documentadas. Os padrões a seguir formalizam mecânicas comuns entre pilares; um sintoma de autoria problemática é documentado para que os autores reconheçam a troca envolvida.
Canalização entre pilares por ponte de esquema — sinalizado, não murado
As fronteiras dos pilares são disciplina de autoria: a arquitetura sinaliza o que vai onde (values: para a intenção cognitiva do desenvolvedor, infra: para o dimensionamento físico de Ops, provides: para as strings emitidas pela Recipe, e assim por diante) e o revisor do catálogo faz cumprir a convenção. O próprio mecanismo de templates permite leituras entre pilares, a menos que as regras de autocontenção documentadas as proíbam (o provides: de uma Recipe não vê .context.inject; o provides: de escopo de fronteira de uma FeatureRecipe não vê campos por consumidor). Os muros dos pilares são sinalizações, não imposições.
Uma exceção sinalizada canônica: o schema: de um Component pode declarar um controle values: voltado ao desenvolvedor que o template valuesMapping: da Recipe canaliza para a saída renderizada com a forma de infra:. O desenvolvedor dita a intenção por meio de um campo values: tipado; o template da Recipe canaliza o valor resultante para a camada de infraestrutura do provedor sem que o desenvolvedor escreva código de infraestrutura. Um exemplo completo:
# Component schema declares a developer-facing dial in valuesspec: schema: values: required_iops: { type: integer, min: 100 }# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knobvaluesMapping: iops_limit: "{{ .values.required_iops }}"A ponte está documentada em inheritance-and-interface.md com exemplos completos. A intenção arquitetural (um controle entre pilares declarado que a Recipe canaliza) tem uma única direção — values: do lado do desenvolvedor fluindo para a saída renderizada do lado de Ops — e se concretiza nos templates de mapeamento da Recipe, não no próprio esquema do Component. A fronteira dos pilares continua sinalizada: o desenvolvedor vê values:, a Recipe vê tanto values: quanto infra:, e a saída renderizada os combina.
Acumulador inject entre pilares
O pipe .context.inject é o ponto de mesclagem de três fontes que atravessam os pilares:
- Self-inject no nível do Component (
component.inject) — obtém strings dosvaluese dosprovidesdo próprio componente. - Uses-inject (
uses[].inject) — obtém strings dosprovidesdo destino. - Interceptações
injectMapping:da FeatureRecipe — obtêm strings de qualquer uma das fontes acima, além do payloadinfra:da própria FeatureRecipe.
Quando a renderização base é executada, .context.inject.<mechanism>.<key> já acumulou entradas das três fontes. O acumulador é entre pilares por construção — entradas originadas em values, provides e infra fluem todas para o mesmo mapa .context.inject. As Recipes que consomem .context.inject veem o estado pós-mesclagem sem precisar saber qual pilar contribuiu com qual entrada.
Para a gramática de inject e as regras de colisão, veja topology-triad.md.
Duplicação de restrições entre pilares
Um campo que vive em dois pilares com camadas de validação diferentes pode carregar restrições duplicadas. O exemplo canônico: um número de porta declarado no usesSchema de um Component (validado por JSON Schema, intervalo min: 1, max: 65535) e o mesmo número de porta consumido no campo services.<name>.ports.<port> de um Workload, para o qual o spec.provider.workloadSchema do plugin de renderização do provedor pode adicionar uma regra min: 1024 para portas não privilegiadas. O spec.provider.workloadSchema de um Plugin de renderização do provedor documenta como o provedor traduz um Workload e marca o provedor como capaz de sintetizar um; ele não valida nada. Todo corpo de Workload é validado contra o esquema Workload da plataforma, seja qual for o provedor, então uma restrição escrita apenas em um workloadSchema — uma regra de porta min: 1024, por exemplo — não é aplicada; para recusar um valor assim, coloque a restrição no esquema do Component ou em uma asserção.
Vinculação de Feature / isolamento de pilares do Component
Uma vinculação de Feature não escreve nos pilares do Component pai. Cada Feature vinculada carrega o seu próprio payload de pilar (o seu próprio bloco values: e o seu próprio bloco infra:). A FeatureRecipe que sintetiza os recursos da Feature lê o seu próprio payload de pilar independentemente do payload do Component. O isolamento é das entradas: o que uma vinculação lê é dela, seja qual for o destino do que ela escreve. Onde o provedor do destino escreve documentos separados, a saída renderizada da vinculação fica ao lado da saída do Component, em um diretório próprio; onde o provedor reúne os contribuidores de uma fronteira em um único documento, a vinculação contribui para esse documento como o Component faz, e cada recurso continua carregando a identidade própria da vinculação, para que continue legível o que veio de onde.
Duas consequências para os autores:
- Uma definição
values:em uma vinculação de Feature não aparece em.valuesdo templatevaluesMapping:do Component. O Component vê apenas os seus próprios valores. - O payload
infra:de uma Feature não flui para oinfra:do Component. Cada Feature vinculada tem o seu próprio dimensionamento físico, restrito aos recursos da Feature.
O isolamento é explícito segundo a separação de responsabilidades da arquitetura: as Features são contribuidores independentes sobrepostos aos Components por meio do modelo de cebola de 5 camadas. Para as superfícies de vinculação e a sua ordem, veja labels-and-annotations.md “Feature attachment — five surfaces (Vinculação de Feature — cinco superfícies)”.
O mesmo nome de propriedade em ambos os pilares
Um Component ou uma Feature cujos spec.schema.values: e spec.schema.infra: declaram o mesmo nome de propriedade — na raiz, em qualquer profundidade de aninhamento, ou em ambos — é um sintoma frequente de autoria problemática. Os dois pilares são namespaces separados por design (o compilador aceita a sobreposição), então o esquema é validado e a saída renderizada é bem formada. O sintoma é cognitivo: leitores e autores de templates esbarram no atrito “qual pilar contém o foo que estou lendo?” toda vez que percorrem o esquema ou escrevem um template baseado nele.
# Smell — both pillars declare `mode`. A reader of the schema or a# template against the Feature has to disambiguate every reference.spec: schema: values: mode: { type: string } infra: mode: { type: string }Autores com sobreposição intencional têm um motivo real para manter ambos — por exemplo, um mode que significa “modo operacional da aplicação” em values ("debug" / "production") e “modo de topologia da implantação” em infra ("standalone" / "clustered") carrega semânticas distintas, e os nomes coincidem por acaso. Autores com sobreposição acidental (o caso mais comum) renomeiam uma das entradas.
Uma segunda forma intencional é um único dado que qualquer um dos dois autores pode fornecer. As Features de credenciais da biblioteca padrão que carregam o localizador de um chamador — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — o declaram em ambos os pilares com um único nome e uma única forma, de modo que o desenvolvedor o escreve em values ou o operador em infra, e a asserção própria de cada Feature recusa uma vinculação que o escreva em ambos ou em nenhum. O aviso descrito abaixo nomeia essas quatro a cada carregamento que as alcança; para elas, ele reporta o contrato, não um deslize.
O carregamento do catálogo emite um aviso notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) para cada propriedade de mesmo nome cuja sobreposição se resolve em uma folha terminal em pelo menos um lado. Propriedades de mesmo nome que existem como namespaces organizacionais compartilhados (ambos os pilares carregam um objeto chamado ingress com subpropriedades disjuntas) não geram alerta; apenas a sobreposição de folhas é reportada. O alerta é um aviso — o build prossegue.
Níveis de validação dos pilares
Os pilares carregam validação em três níveis. Cada nível cobre uma preocupação diferente; o mesmo campo pode ser validado por mais de um nível (veja “Cross-pillar constraint duplication (Duplicação de restrições entre pilares)” acima).
| Nível | O que valida | Onde é executado |
|---|---|---|
| 1 — Envelope de JSON Schema | Forma estrutural (quais chaves estão presentes, se os tipos correspondem às declarações dos campos) | Resolução, a cada carregamento de arquivo |
2 — Esquema por pilar (schema / featuresSchema / usesSchema) | Conteúdo tipado por pilar, validado como JSON Schema 2020-12 | Resolução, depois que o envelope passa |
| 3 — verificação de capacidades do provedor | Conteúdo do Workload condicionado à capacidade de modo sintetizado do provedor associado, documentada pelo spec.provider.workloadSchema do plugin de renderização do provedor | Renderização base, depois que valuesMapping é resolvido |
Para a tabela de formas de erro em quatro camadas e os prefixos de erro por camada, veja validation-surface.md.
Mecanismos de valores padrão
Valores padrão aparecem no corpus por meio de vários mecanismos distintos. Os autores encontram a palavra “default” em mais de cinco contextos; a tabela abaixo é a referência canônica sobre qual mecanismo produz um valor quando o autor deixa um campo vazio.
| # | Mecanismo | Onde é escrito | Gatilho |
|---|---|---|---|
| 1 | default: do JSON Schema (forma compacta { default: <value> }) | schema: de Component / Feature, parameters: do Aggregate | O campo é validado com o valor padrão quando o desenvolvedor omite a chave. Para parâmetros do Aggregate, a mesclagem de parâmetros preenche o valor padrão declarado antes que a validação do contrato seja executada (veja templates/parameters-context.md). |
| 2 | Template Go optional .X `Y` <fallback> | valuesMapping: da Recipe, corpo do Workload, templates de FeatureRecipe, o avaliador de asserções | Valor alternativo sensível à presença — retorna <fallback> apenas quando a chave está ausente do mapa; um zero / vazio / false escrito na chave retorna esse valor escrito. A forma canônica, do lado do Aggrega, do valor alternativo para campo ausente. Veja templates/sprig-functions.md. |
| 3 | Template Go | default <expr> | valuesMapping: da Recipe, corpo do Workload, templates de FeatureRecipe | Pipeline inline que dispara com o “vazio” (a verificação de vacuidade do Sprig — zero, string vazia, false, nil). Confunde a ausência no mapa com a presença de um valor zero/vazio/false. Adequada para uma semântica de sobrescrita por ponto de chamada (o valor alternativo do binding difere do valor padrão do campo no nível do esquema) quando a confusão é aceitável. Não é adequada como valor alternativo para campo ausente quando um zero / vazio / false escrito é uma intenção legítima — nesse caso, use optional (mecanismo 2). |
| 4 | Função default do Sprig ({{ default <expr> .field }}) | Igual a 3 | Forma de função do mecanismo 3, com a mesma confusão de vacuidade. |
| 5 | Valor alternativo em locals: da Recipe | Template locals: da Recipe | Uma entrada de locals calcula uma string portadora de um valor padrão que o restante da Recipe consome |
Orientação recomendada de posicionamento. Quando um valor padrão faz realmente parte do contrato do tipo (por exemplo, “esta porta é 5432 por padrão, a menos que o desenvolvedor a sobrescreva”), o default: do JSON Schema (mecanismo 1) é o canônico — o preenchimento automático da IDE mostra o valor padrão; as ferramentas de validação o respeitam; o contrato acompanha a entidade de catálogo Component / Feature OU a declaração do parâmetro do Aggregate. Quando um template de Recipe precisa de um valor alternativo para uma chave de mapa opcional, o helper optional (mecanismo 2) é a forma canônica do valor alternativo para campo ausente — ele distingue um zero / vazio / false escrito da ausência. O | default do template Go (mecanismo 3) é reservado ao caso de sobrescrita por ponto de chamada em que a confusão entre valores ausentes e falsy é aceitável; recorra a ele apenas quando a semântica de sobrescrita for a intenção explícita.
Referências cruzadas
inheritance-and-interface.md— mecanismoextends:, ligação de interfaceimplements:, canalização entre pilares por ponte de esquema.topology-triad.md— mecânica topológica deprovides,inject,uses.labels-and-annotations.md— vocabulário de metadados do lado do conteúdo, distinto dos pilares de dados (a lista canônica de pilares acima não inclui rótulos / anotações / campos de publicação — esses são vocabulário de metadados).publishing-surface.md— vocabulário de metadados do lado da publicação, distinto dos pilares de dados.validation-surface.md— quatro camadas de validação de esquema, incluindo os três níveis de validação de pilares acima.templates/expansion-matrix.md— disponibilidade por ponto de template das leituras entre pilares + regras de autocontenção emprovides:esource:da Recipe.examples/04-secrets.md— a checklist da entrega de segredos em seis pontos de contato.architecture/06-data-taxonomy-and-composition.md— enquadramento conceitual canônico das cinco palavras-chave estruturais da DSL.