Pilares de dados
O enquadramento concetual das cinco palavras-chave estruturais da DSL — parameters, values, uses, infra, inject — encontra-se em architecture/06-data-taxonomy-and-composition.md. Esta página abrange a lista canónica de pilares de dados, a semântica de criação por pilar, a mecânica entre pilares e o vocabulário de valores predefinidos que os autores encontram nos vários pilares. A tríade topológica complementar (provides, inject, uses — palavras-chave que ligam as arestas do grafo) está documentada em topology-triad.md; o vocabulário de metadados distinto dos pilares de dados (etiquetas, anotações, campos da superfície de publicação) encontra-se em labels-and-annotations.md e publishing-surface.md.
Lista canónica de pilares
As entidades do Aggrega contêm sete pilares de dados com nome. Cinco participam no fluxo de dados da IR como estado vivo ao longo da renderização; dois são transitórios ou privados e existem apenas em fases específicas da compilação.
| Pilar | Reside em | Ciclo de vida | Papel |
|---|---|---|---|
values | Instâncias de componente / anexo do Aggregate | Vivo ao longo da renderização | Payload cognitivo escrito pelo programador |
infra | Entradas de componente, anexo e ligação da Release | Vivo ao longo da renderização | Dimensionamento físico escrito pelo operador |
provides | Bloco provides: da Recipe | Vivo ao longo da renderização (pilar derivado — ver 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 ao longo da 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 — ver «Features pillar (Pilar Features)» abaixo | Vivo ao longo da renderização | Pilar de anexos — uma única forma para cada família de anexos |
parameters | Raízes do Aggregate + Release | Legível até ao fim do pipeline, até que cada fase de renderização termine; acessível aos templates de caminho durante a renderização através 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 preenchidos 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 através de .values, .infra, .provides, .context.uses e .features, respetivamente. parameters e locals estão fora da lista de pilares vivos — parameters porque não sobrevive à resolução; locals porque é privado da Recipe e nunca atravessa as fronteiras das entidades.
Os pilares são sinalizações, não muros: o motor de templates permite leituras entre pilares em qualquer ponto, salvo quando regras de autocontenção as proíbem explicitamente (um bloco provides: de Recipe e um bloco source: de Recipe que leem .context.inject / .context.uses; documentado em templates/expansion-matrix.md). As fronteiras dos pilares são disciplina de criação, não uma imposição da linguagem.
Fronteiras dos pilares e disciplina de criação
As leituras entre pilares a partir de um template de Recipe não têm restrições em qualquer ponto que permita o contexto de template completo. A disciplina de criação espera que os autores:
- Leiam
.valuespara o payload cognitivo (intenção escrita pelo programador). - 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 interceçõesinjectMappingde FeatureRecipe).
A disciplina é feita de sinalizações, não de muros. Um template de Recipe que lê .infra.replicas para alimentar um campo values: funciona; o motor de templates não bloqueia a leitura. O enquadramento da arquitetura é que as fronteiras dos pilares descrevem a intenção de criação — quem detém os 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 programador 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 controlo destinado ao programador que o template valuesMapping: da Recipe canaliza para uma saída com a forma de infra: do lado de Ops, segundo vocabulary/inheritance-and-interface.md — a arquitetura trata a ponte como uma exceção sinalizada. Ver «Cross-pillar mechanics (Mecânica entre pilares)» abaixo.
Values
O pilar values: contém o payload cognitivo escrito pelo programador — os parâmetros com a forma da aplicação que o programador dita para cada instância de componente. O schema: do Component declara a forma dos valores; o Aggregate do programador preenche valores concretos por instância. Este é o domínio do programador.
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 do anexo, seja qual for a família a que pertence a Feature anexada (os parâmetros de consulta ao vault de um anexo 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; ver Parameters abaixo).
Validado por: o bloco values: do schema do Component (e o bloco values: do schema da Feature para anexos de Feature), resolvido para JSON Schema 2020-12 no carregamento do Component / da Feature segundo vocabulary/validation-surface.md, camada 2.
Consumido por: os templates valuesMapping: da Recipe através de .values. O contexto de template completo expõe o dicionário de valores resolvidos em cada ponto de template da renderização base.
Infra
O pilar infra: contém o dimensionamento físico escrito pelo operador — réplicas, pedidos de recursos, limites de IOPS, fixação de região, classe de máquina. Exprime 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 criação
Os autores encontram infra: em quatro superfícies distintas, cada uma com âmbito diferente e comportamento em cascata diferente:
| # | Superfície | Âmbito | Precedência de fusão |
|---|---|---|---|
| 1 | Fronteira da Release components.<id>.infra: (spec.components.<id>.infra: numa 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: | Um anexo de âmbito de fronteira, em cada componente da fronteira | A mais baixa para esse anexo — a superfície 3 substitui-a campo a campo |
| 3 | Fronteira da Release components.<id>.features.<name>.infra: | Um anexo num componente | Substitui a superfície 2 para esse anexo, campo a campo |
| 4 | Release components.<id>.uses.<socket>.<alias>.infra: | Uma ligação | Validado face ao 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 coloca. Uma fronteira não tem nenhum infra: próprio — o esquema da Release recusa-o —, pelo que um dimensionamento partilhado por vários componentes é escrito em cada um, ou herdado de uma Release pai através de extends: (abaixo). As superfícies 2 e 3 abrangem o dimensionamento de anexos de Feature — as Features têm o seu próprio payload infra, que a FeatureRecipe consome ao sintetizar sidecars ou recursos por Feature: um anexo de âmbito de fronteira é dimensionado uma vez, e um componente ajusta um único campo dele.
«Infra principalmente localizado» — a regra com exceções
O objetivo arquitetural para infra: é local ao componente: o dimensionamento de um componente aplica-se a essa instância de componente e não se propaga a outros componentes. É o mecanismo que permite a Ops aumentar os IOPS da base de dados sem afetar o pedido de CPU do servidor de API.
A regra: infra: está principalmente localizado na superfície que o escreveu. Existem exceções em cascata por conceção:
- Cascata de anotações da fronteira. As
annotations:de uma fronteira propagam-se em cascata pelas fronteiras aninhadas até aos componentes internos (superfície 5 da matriz de anotações em labels-and-annotations.md). As anotações consumidas pelas Recipes como entrada de encaminhamento tornam-se um alcance indireto deinfra— a anotação ao nível da fronteira flui através de.context.annotations.releasepara a saída renderizada da Recipe por nó. - Herança de Release através de
extends:. Uma Release que fazextends:de uma Release pai herda as declaraçõesinfrado pai em cada superfície que as contém, a menos que a filha as substitua por chave. O valor da filha prevalece chave a chave, até ao 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 atravessa deliberadamente a fronteira de cada Release; para a regra de fusão completa e o que mais viaja com ela, verentities/release.md. - Canalização entre pilares por ponte de esquema. O
schema:de um Component pode expor um controlovalues:destinado ao programador que o templatevaluesMapping:da Recipe canaliza para a saída do fornecedor com a forma deinfra:(ver «Cross-pillar mechanics — Schema-bridge cross-pillar piping (Mecânica entre pilares — Canalização entre pilares por ponte de esquema)» abaixo). Em rigor, o valor tem origem emvalues:e flui para a saída renderizada; a cascata é interna à instância, mas entre pilares.
A localização é a intenção de conceção, não um muro que o motor impõe: as cascatas acima são exceções deliberadas, cada uma documentada na superfície que a contém.
Partição entre lado e pilar para a expansão de Feature orientada por anotações. A invariante do Aggregate como superfície de criação estende-se ao caminho de expansão de Feature orientado por anotações: as anotações do lado do Aggregate (âmbito de subsistema e de instância de componente) só podem acionar subchaves maps.values; as anotações do lado da Release (âmbito 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 combina os contributos campo a campo no momento da compilação da IR. A partição preserva a separação de criação values-programador / infra-operador na superfície de anotações — a mesma separação que values: e infra: impõem nas superfícies de anexo explícito. Ver 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 declara-o, mas, ao contrário de values / infra, o programador não o escreve diretamente. As Recipes calculam as strings de saída públicas que o pipe topológico irá consumir.
O bloco provides: de uma Recipe é um mapa de pares <key>: <template>. Cada template é avaliado face à superfície autocontida da própria Recipe (.values, .infra, .context.instance_id, .context.rendered_name quando o fornecedor do nó comunica um, e os .locals resolvidos do nó) durante a avaliação dos provides. As strings resultantes são expostas através de .provides e consumidas pelos blocos uses[].inject dos chamadores através de referências from: "<key>". .locals está disponível porque os locals do nó são resolvidos no preâmbulo dessa fase, antes dos seus provides (ver 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 por qualquer ordem — fecham-se apenas sobre os dados do próprio nó, pelo que a ordem não importa. Referências entre nós acoplariam essa avaliação à ordem de iteração topológica, o que a conceção evita deliberadamente. Ver templates/expansion-matrix.md, linha 6, para a regra e a sua justificação.
Porque é que provides: é um pilar. As strings de saída são a superfície pública canónica de cada Recipe; os consumidores a jusante (uses[].inject do chamador, blocos injectMapping de FeatureRecipe que leem os provides resolvidos do destino através de .context.uses) tratam o dicionário como um contrato tipado. Designar provides: como pilar reconhece o seu estatuto 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 em que o componente participa — os sockets através dos quais consome destinos. A gramática completa está documentada em topology-triad.md; esta secção nomeia uses: como pilar por uma questão de completude.
uses: reside nas instâncias de componente do Aggregate + anexos de funcionalidade; o contexto de template em tempo de execução expõe uma entrada por ligação de saída, indexada pelo seu alias, como .context.uses. A projeção contém os metadados resolvidos do destino de cada aresta (os provides do destino, etiquetas, 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 os anexos escritos nessa ligação, em .context.uses.<alias>.features.<slot>.
Pilar Features
features: é o pilar dos anexos: uma palavra-chave, uma forma, todos os anexos. 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 os anexos do nó como .features.<name>, cada um com type, values, infra e os provides resolvidos do anexo. Um anexo escrito numa das ligações do componente é exposto nessa mesma forma sob a ligação, em .context.uses.<alias>.features.<slot>, e nunca sob .features — assim, uma Recipe que percorre .features encontra apenas os anexos do próprio componente (ver o contrato do contexto de template).
Um anexo cujo nome de instância corresponde a um slot que a entidade declara em featuresSchema preenche esse slot; qualquer outro nome de instância é um anexo livre. Preencher um slot é o que liga 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 lista de permissões de entrega (env / file / blackbox) e, opcionalmente, um seletor de etiquetas que o preenchimento tem de satisfazer |
Aggregate components.<id>.features.<slot>: | Instância de componente do Aggregate | Preenche o slot com um anexo; fornece os values: próprios do anexo 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 ligação declara — e dita a entrega por contentor do que o preencheu |
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:) | a FeatureRecipe associada | Produz a saída do anexo — um recurso emitido, uma reescrita da entrega, ou ambos |
O nome do slot é o identificador essencial nas quatro: a superfície 1 declara-o, as superfícies 2–4 referenciam-no, e o fluxo de dados segue um único sentido (declarar → preencher → referenciar → produzir).
Para a lista de verificação de criação, ver examples/04-secrets.md «The secret-delivery checklist (A lista de verificação da 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 face a 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 resto 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 pela 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 que a referência se resolva. 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. Numa Recipe cujo source: é um bloco estruturado, ambas as falhas são também recusadas enquanto o artefacto que ele nomeia é fixado, pelo que aggrega pull as comunica antes de qualquer compilação renderizar saída. A verificação lê o caminho para o qual uma referência se resolve em vez das teclas premidas, pelo que 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 não abrange: uma chave alcançada através 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 através do próprio index, que provoca uma interrupção nomeando a chave em cada superfície de template quando o mapa que 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 através da aresta. O que um chamador pode ler é o provides: do destino.
Casos de utilização:
- 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:como oprovides:da Recipe consomem, e que uma FeatureRecipe de credenciais anexada ao mesmo componente lê como.locals.secret_target_admin_password— os templates de um anexo veem os locals resolvidos da Recipe anfitriã combinados com os do próprio anexo. 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 carateres que um nome do Kubernetes admite, e um local não o pode ler, pelo que o local contém o sufixo e cada leitor junta os dois. - Aplicar DRY a valores calculados repetidos dentro de uma Recipe (um nome de anfitrião calculado uma vez, referenciado a partir de vários campos
valuesMapping:). - Valores intermédios 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 contêm uma separação deliberada de visibilidade que os autores devem ter presente:
provides:é a face pública. Cada chave é a superfície canónica do pipe topológico — os blocosuses[].injectdos chamadores a jusante consomem-nas através de referênciasfrom: "<key>". O dicionárioprovides:é um contrato tipado do qual os chamadores dependem; mudar o nome de uma chave ou removê-la é uma alteração incompatível para cada 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 mudar-lhes o nome é uma refatoração interna da Recipe sem efeito a jusante.
Os dois são também ordenados: locals: é resolvido primeiro, pelo que provides: pode ler .locals, mas locals: não pode ler .provides. Publicar o valor de um local através de provides: significa, portanto, acrescentar uma entrada provides que lê o local — a expressão fica num só sítio.
A separação é deliberada, segundo a separação arquitetural entre os internos da Recipe (privados) e a interface da Recipe (pública). Os autores que tratam provides: e locals: como um único espaço de nomes perdem a distinção de visibilidade e arriscam expor estado interno através do pipe topológico — cada chave declarada em provides: passa a fazer parte da superfície contratual da Recipe, quer o autor o tenha pretendido quer não. O objetivo da disciplina: declarar uma chave primeiro em locals:; promovê-la a provides: apenas quando um chamador a jusante precisar realmente dela.
A visibilidade é definida pelo pilar em que uma chave é declarada: não existe um marcador de visibilidade por chave, pelo que um valor simultaneamente privado e publicado é uma entrada locals: mais uma entrada provides: que a lê.
Parameters
Tanto o esquema Aggregate como o esquema Release contêm um dicionário parameters na sua raiz. Os programadores declaram as chaves que o Aggregate espera; Ops preenche os valores a partir de ficheiros de Release específicos de cada ambiente. Este 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 a fornecer 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 num ficheiro 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 ficheiro 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 é executado, e tem de levar a um ficheiro dentro do espaço de trabalho — ou, para uma Release indicada fora do espaço de trabalho, dentro do diretório que a contém. A sobreposição de vários ficheiros (combinar um ficheiro base com uma sobreposição específica do ambiente) exprime-se através de cadeias extends: de Release — a Release pai fornece os parâmetros base; a Release filha estende e substitui por chave.
Ciclo de vida dos parâmetros. O compilador resolve os parâmetros em três fases. (1) Preenchimento de predefinições — os slots com default: definido e sem valor da Release recebem a sua predefinição. (2) Validação do contrato de parâmetros — o contrato tipado parameters: valida cada valor face às suas restrições declaradas type / enum / min / max / pattern, incluindo uma predefinição preenchida, pelo que uma predefinição que viola o próprio contrato interrompe a compilação. (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 combinado continua depois legível durante a renderização, para que os templates de caminho (fronteira da Release directory: / subDirectory:) possam ler .parameters.<slot> diretamente, face à lista de permissões 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 — consomem os valores resolvidos escritos nas strings values: circundantes pela interpolação da fase 3.
A lista de verificação da elevação de parâmetros
Cada valor que varia entre ambientes passa em sequência por quatro pontos de contacto de criação. O modelo mental que os autores levam consigo: para qualquer valor que varie entre Dev / Staging / Production, é de esperar mexer no Aggregate (declarar), no template de values (referenciar), na Release (cumprir) e no template da Recipe (consumir).
| Passo | Superfície | Ação |
|---|---|---|
| 1 | Aggregate spec.parameters.<name> | Declarar o parâmetro como parte do contrato de criação tipado do Aggregate. Cada slot de parâmetro tem 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 | Referenciar o parâmetro através de {{ .parameters.<name> }} a partir do bloco values: de qualquer componente (ou funcionalidade, ou subagregado) que o consuma. A referência é uma expressão de template Go — o compilador avalia-a durante a fase de interpolação da resolução. |
| 3 | Release spec.parameters.<name> (inline ou parameters: { $import: ./path.yaml }) | Cumprir o parâmetro com o valor específico do ambiente na superfície da Release. Os ficheiros de Release por ambiente fornecem valores diferentes para a mesma chave de parâmetro sem modificar o Aggregate. |
| 4 | Template valuesMapping: da Recipe | Consumir o valor resolvido através de {{ .values.<key> }} — a Recipe é uma superfície de template de valor; o seu contexto de template não contém .parameters diretamente. A variação por ambiente chega à Recipe através do 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: leem .parameters.<slot> diretamente durante a renderização, segundo a concessão assimétrica.) |
Os quatro pontos de contacto são sequenciais e essenciais: omitir a declaração no Aggregate deixa a Release sem slot para cumprir; omitir a referência nos values deixa a Recipe sem valor para consumir; omitir o cumprimento na Release deixa o parâmetro vazio. O compilador valida a cadeia durante a resolução (validação do contrato de parâmetros face à declaração tipada parameters:, depois interpolação nas strings values: circundantes, depois validação com JSON Schema do dicionário values: resultante face ao schema: do Component ou da Feature); as divergências surgem como uma violação do contrato de parâmetros (detetada face à declaração tipada parameters:), um erro de template não preenchido (detetado na interpolação) ou uma violação de restrição de JSON Schema face ao esquema values: (detetada 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 a fornecer os seus próprios valores de parâmetros. Cada valor por ambiente que um autor pretenda variar pertence à cadeia de parâmetros, em vez de ficar incorporado diretamente no Aggregate.
Semântica de fusão 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 é fundido segundo regras específicas do pilar. A semântica difere entre pilares; a tabela abaixo é a referência canónica por pilar.
| Pilar | Comportamento de fusão numa cadeia extends: |
|---|---|
values (JSON Schema 2020-12) | Numa cadeia de Feature, os esquemas compõem-se através 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 numa cadeia de Feature, herdado por inteiro por um Component que estende. |
provides (mapa de templates da Recipe) | Substituição superficial de primeiro nível: a chave filha substitui totalmente a chave pai com o mesmo nome; as chaves irmãs são preservadas do pai. Os templates não são compostos; o template da filha detém totalmente o seu slot. |
uses (usesSchema) | Sobreposição da entrada inteira por socket, por nome de socket. Uma filha acrescenta sockets que a sua base não declara, e um socket que redeclara sob um nome existente substitui por completo essa entrada — os seus esquemas de valor e de infra e o seu selector em conjunto. 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 acrescenta slots livremente; um slot que redeclara substitui por completo a entrada da base em vez de se compor com ela. |
locals (mapa de templates da Recipe) | Substituição superficial de primeiro nível — igual a provides. |
parameters (mapa raiz do Aggregate) | Um Aggregate não tem campo extends:, pelo que nenhuma cadeia de Aggregate funde parâmetros. Numa cadeia extends: de Release, um parâmetro com valor de mapa é fundido 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 compõem-se segundo JSON Schema 2020-12. Os pilares de um Component que estende são herdados por inteiro — não escreve nenhum, pelo que o seu contrato é exatamente o da sua base, e uma restrição da base não pode, portanto, ser relaxada, por construção. As superfícies de forma fixa — usesSchema e featuresSchema — sobrepõem-se por nome em ambos os tipos: uma filha acrescenta entradas, e uma entrada que redeclara substitui por completo a da base. Os pilares escritos como template usam substituição superficial por chave, dando à filha a propriedade total de qualquer slot de template que declare.
Um Component que estende reforça uma restrição através de assertions: em vez de através de um pilar — um predicado que acrescenta, avaliado a par dos que herda. Ver inheritance-and-interface.md para esse mecanismo.
Para o mecanismo de herança em si, ver inheritance-and-interface.md «Inheritance via extends (Herança através de extends)», que abrange os tipos do catálogo. Uma Release não é uma entidade do catálogo e combina-se segundo a sua própria regra; essa regra está em entities/release.md «Composite Release and extends: inheritance (Release composta e herança extends:)».
Mecânica entre pilares
O enquadramento das sinalizações permite leituras entre pilares em qualquer ponto, exceto nas superfícies de autocontenção documentadas. Os padrões seguintes formalizam mecânicas comuns entre pilares; um sintoma de criação problemática é documentado para que os autores reconheçam o compromisso.
Canalização entre pilares por ponte de esquema — sinalizado, não murado
As fronteiras dos pilares são disciplina de criação: a arquitetura sinaliza o que vai para onde (values: para a intenção cognitiva do programador, 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 motor 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 âmbito 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 controlo values: destinado ao programador que o template valuesMapping: da Recipe canaliza para a saída renderizada com a forma de infra:. O programador dita a intenção através de um campo values: tipado; o template da Recipe canaliza o valor resultante para a camada de infraestrutura do fornecedor sem que o programador 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 controlo entre pilares declarado que a Recipe canaliza) tem uma única direção — values: do lado do programador a fluir para a saída renderizada do lado de Ops — e concretiza-se nos templates de mapeamento da Recipe, não no próprio esquema do Component. A fronteira dos pilares continua sinalizada: o programador vê values:, a Recipe vê tanto values: como infra:, e a saída renderizada combina-os.
Acumulador inject entre pilares
O pipe .context.inject é o ponto de fusão de três fontes que atravessam os pilares:
- Self-inject ao nível do Component (
component.inject) — obtém strings dosvaluese dosprovidesdo próprio componente. - Uses-inject (
uses[].inject) — obtém strings dosprovidesdo destino. - Interceçõ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 com origem em values, provides e infra fluem todas para o mesmo mapa .context.inject. As Recipes que consomem .context.inject veem o estado após a fusão sem precisarem de saber que pilar contribuiu com que entrada.
Para a gramática de inject e as regras de colisão, ver topology-triad.md.
Duplicação de restrições entre pilares
Um campo que vive em dois pilares com camadas de validação diferentes pode conter 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 fornecedor pode acrescentar uma regra min: 1024 para portas não privilegiadas. O spec.provider.workloadSchema de um Plugin de renderização do fornecedor documenta a forma como o fornecedor traduz um Workload e marca o fornecedor como capaz de sintetizar um; não valida nada. Todo o corpo de Workload é validado face ao esquema Workload da plataforma, seja qual for o fornecedor, pelo que uma restrição escrita apenas num workloadSchema — uma regra de porta min: 1024, por exemplo — não é aplicada; para recusar um valor desses, coloque-se a restrição no esquema do Component ou numa asserção.
Anexo de Feature / isolamento de pilares do Component
Um anexo de Feature não escreve nos pilares do Component pai. Cada Feature anexada tem 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 um anexo lê é seu, seja qual for o destino do que escreve. Onde o fornecedor do destino escreve documentos separados, a saída renderizada do anexo fica ao lado da saída do Component, num diretório próprio; onde o fornecedor reúne os contribuidores de uma fronteira num único documento, o anexo contribui para esse documento tal como o Component, e cada recurso continua a ter a identidade própria do anexo, para que continue legível o que veio de onde.
Duas consequências para os autores:
- Uma definição
values:num anexo 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 anexada tem o seu próprio dimensionamento físico, circunscrito 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 através do modelo em cebola de 5 níveis. Para as superfícies de anexo e a sua ordem, ver labels-and-annotations.md «Feature attachment — five surfaces (Anexo 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 criação problemática. Os dois pilares são espaços de nomes separados por conceção (o compilador aceita a sobreposição), pelo que o esquema é validado e a saída renderizada é bem formada. O sintoma é cognitivo: leitores e autores de templates deparam-se com o atrito «que pilar contém o foo que estou a ler?» sempre 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 }Os 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 implementação» em infra ("standalone" / "clustered") contém semânticas distintas, e os nomes coincidem por acaso. Os autores com sobreposição acidental (o caso mais comum) mudam o nome de 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 contêm o localizador de um chamador — core/referenced-secret, core/referenced-secret-set, core/secret-value e core/secret-provided — declaram-no em ambos os pilares com um único nome e uma única forma, de modo que o programador o escreve em values ou o operador em infra, e a asserção própria de cada Feature recusa um anexo que o escreva em ambos ou em nenhum. O aviso descrito abaixo nomeia essas quatro em cada carregamento que as alcança; para elas, comunica o contrato, não um lapso.
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 com o mesmo nome cuja sobreposição se resolve numa folha terminal em pelo menos um dos lados. As propriedades com o mesmo nome que existem como espaços de nomes organizacionais partilhados (ambos os pilares contêm um objeto chamado ingress com subpropriedades disjuntas) não geram advertência; apenas a sobreposição de folhas é comunicada. A advertência é um aviso — a compilação prossegue.
Níveis de validação dos pilares
Os pilares contêm validação em três níveis. Cada nível abrange uma preocupação diferente; o mesmo campo pode ser validado por mais de um nível (ver «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 (que chaves estão presentes, se os tipos correspondem às declarações dos campos) | Resolução, a cada carregamento de ficheiro |
2 — Esquema por pilar (schema / featuresSchema / usesSchema) | Conteúdo tipado por pilar, validado como JSON Schema 2020-12 | Resolução, depois de o envelope passar |
| 3 — verificação de capacidades do fornecedor | Conteúdo do Workload condicionado pela capacidade de modo sintetizado do fornecedor associado, documentada pelo spec.provider.workloadSchema do plugin de renderização do fornecedor | Renderização base, depois de valuesMapping ser resolvido |
Para a tabela de formas de erro em quatro camadas e os prefixos de erro por camada, ver validation-surface.md.
Mecanismos de valores predefinidos
Os valores predefinidos aparecem no corpus através 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 que mecanismo produz um valor quando o autor deixa um campo vazio.
| # | Mecanismo | Onde é escrito | Acionador |
|---|---|---|---|
| 1 | default: do JSON Schema (forma compacta { default: <value> }) | schema: de Component / Feature, parameters: do Aggregate | O campo é validado com o valor predefinido quando o programador omite a chave. Para os parâmetros do Aggregate, a fusão de parâmetros preenche o valor predefinido declarado antes de a validação do contrato ser executada (ver 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 — devolve <fallback> apenas quando a chave está ausente do mapa; um zero / vazio / false escrito na chave devolve esse valor escrito. A forma canónica, do lado do Aggrega, do valor alternativo para campo ausente. Ver templates/sprig-functions.md. |
| 3 | Template Go | default <expr> | valuesMapping: da Recipe, corpo do Workload, templates de FeatureRecipe | Pipeline inline que dispara perante 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 a uma semântica de substituição por ponto de chamada (o valor alternativo do binding difere do valor predefinido do campo ao 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, usar 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 predefinido que o resto da Recipe consome |
Orientação recomendada de colocação. Quando um valor predefinido faz realmente parte do contrato do tipo (por exemplo, «esta porta é 5432 por predefinição, a menos que o programador a substitua»), o default: do JSON Schema (mecanismo 1) é o canónico — o preenchimento automático do IDE mostra o valor predefinido; as ferramentas de validação respeitam-no; 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 — distingue um zero / vazio / false escrito da ausência. O | default do template Go (mecanismo 3) está reservado ao caso de substituição por ponto de chamada em que a confusão entre valores ausentes e falsy é aceitável; deve recorrer-se a ele apenas quando a semântica de substituição for a intenção explícita.
Referências cruzadas
inheritance-and-interface.md— mecanismoextends:, associaçã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 etiquetas / 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 lista de verificação da entrega de segredos em seis pontos de contacto.architecture/06-data-taxonomy-and-composition.md— enquadramento conceptual canónico das cinco palavras-chave estruturais da DSL.