Contrato do contexto de template
Esta página documenta a vista de execução que o compilador injeta nos templates Go de Recipe e FeatureRecipe: a forma do contexto de template, a disponibilidade por campo ao longo do pipeline de compilação e o contrato canónico de que os autores avançados precisam ao escrever templates que consomem estado entre componentes. A disponibilidade por local de template (que campos estão presentes em que local de avaliação) encontra-se em expansion-matrix.md; esta página documenta as formas dos campos e a sua semântica.
Visão geral
O compilador monta um contexto de template por nó durante a renderização e injeta-o em cada template Go que o renderizador avalia para esse nó. O contexto existe apenas em memória — nunca é persistido em disco e nunca atravessa a ABI Wasm como uma única carga útil. Cada local de template recebe uma vista do mesmo objeto de contexto; alguns campos são preenchidos tardiamente (.workload chega na síntese do workload; .source, na resolução da origem; .steps é preenchido pela execução de pipeline: à medida que cada passo é concluído, consulte Estado da linguagem → Fases do pipeline de compilação).
O esquema da forma de execução é template-context-v1beta1.schema.json (distribuído com a distribuição de esquemas do Aggrega).
Campos de nível superior
Os campos de nível superior ficam na raiz do contexto de template — acede-se a eles como .field a partir do interior de um template.
.values(mapa). Carga útil cognitiva escrita pelo programador, proveniente do Aggregate. Os valores por componente fluem até à Recipe renderizada neste campo. Validado peloschema:do catálogo (a declaração JSON Schema 2020-12 do Component ou da Feature) na resolução. Quando o zero / vazio / falso escrito para um campo é semanticamente distinto da ausência do campo, deve usar-seoptional(consultesprig-functions.md) em vez dedefault..infra(mapa). Dimensionamento físico escrito por Ops, proveniente da Release. Validado peloschema:do catálogo (a declaração JSON Schema 2020-12 do Component ou da Feature) na resolução. Aplica-se a mesma orientaçãooptional-vs-defaultdada para.values— deve preferir-seoptionalquando um zero ou um falso escrito pelo autor é uma intenção legítima (scale-to-zero, sem novas tentativas, feature flag desligada)..locals(mapa com valores de string). Estado privado da Recipe — nomes declarados no blocolocals:da Recipe, resolvidos no preâmbulo de locals e publicados neste pilar na resolução da origem. As entradas resolvem-se pela ordem do autor e uma entrada pode ler uma entrada irmã definida acima dela, pelo que a ordem é determinante sempre que uma entrada lê outra. Acessível apenas dentro dos templates da própria Recipe; nunca exposto aos chamadores..provides(mapa com valores de string). As strings de saída públicas da Recipe — o contrato contra o qual os blocosinject:dos chamadores resolvem as referênciasfrom:. Preenchido na avaliação de provides..features(mapa de anexos). Itera as Features anexadas a este Component (nível do Aggregate + nível do subsistema + nível da Release + orientadas por anotações do Manifest, segundo o modelo em cebola de 5 níveis), tendo como chave o nome de instância que o autor deu ao anexo. Cada entrada transporta os mesmos campos — consulte a forma do anexo abaixo. Um anexo escrito numa das ligações do Component não está entre eles: é lido sob essa ligação, em.context.uses.<alias>.features.<slot>, pelo que um template que percorre.featuresencontra apenas os anexos próprios do Component..metadata(struct). Identidade da Release para uma nomeação determinística:release_name,release_version,environment,aggregate_name. Preenchido em todas as renderizações; os valores provêm do blocometadata:da Release..source. Osource:da Recipe, resolvido pela avaliação de template da resolução da origem.nilpara Recipes sem origem;nilantes de a resolução da origem ser executada. Nos templates de uma FeatureRecipe, é o própriosource:dessa FeatureRecipe, nunca o do componente host — ver Superfície da FeatureRecipe de um anexo..workload. O objeto Workload analisado, preenchido depois de o documentoworkload:renderizado ter sido descodificado e ter passado a validação que o condiciona: o esquema do Workload, ofeaturesSchemado Component para cada anexo que os seus contentores declaram e a resolubilidade daquilo que cada anexo referencia.nilpara Recipes não sintetizadas;nilantes de a síntese do workload ser executada..steps(mapa de saídas de passos). Preenchido pela execução depipeline:à medida que os plugins Wasm são executados, expondo as saídas devolvidas por um passo concluído aos passos seguintes através de.steps.<id>.outputs. Um passo lê as saídas de um passo anterior a partir do seu próprio templatewith; osoutputsde um passo só ficam visíveis para os passos declarados depois dele. Vazio quando o nó não declara nenhum pipeline, e antes de o primeiro passo do nó ser concluído.
Um campo de nível superior que não contém nada para este nó — .workload numa Recipe que não sintetiza nenhum, .source numa Recipe sem origem, .features num Component sem anexos — é lido como vazio num template de valor, exatamente como uma chave não definida em .values: {{ .workload }} não renderiza nada, um default sobre ele fornece o seu valor alternativo, e um if ou with sobre ele segue o seu ramo falso. Um range sobre ele não itera nada. Uma leitura abaixo dele — {{ .workload.containers }} — interrompe mesmo assim, porque não há nada em que descer. E um template que tanto imprime esse campo onde é sempre executado — fora de todos os if, with e range — como o percorre interrompe nomeando o campo, como faz com qualquer caminho que não contém nada e é lido das duas formas, porque nenhum valor único é impresso como nada e itera como nada: consulte A template reads and iterates a path that holds nothing (Um template lê e itera um caminho que não contém nada).
A forma do anexo
.features.<name> e .features.<slot> têm a mesma forma — um anexo, lido de uma única maneira:
.type(string). O URI de catálogo da Feature anexada..resolved_version(string). A versão da Feature anexada após a resolução do Manifest — a versão efetivamente associada a esta compilação, em vez de uma versão fixada repetida do lado consumidor. Espelha.context.uses.<alias>.resolved_version. Vazio quando otypedo anexo não se resolve em nenhuma entidade de catálogo..labels(mapa com valores de string). As etiquetas de catálogo da Feature anexada, transmitidas literalmente pela ordem em que a Feature as declara — nada é filtrado, renomeado ou despojado de prefixo, pelo que um template lê exatamente o que o autor da Feature escreveu. Espelha.context.uses.<alias>.labels. Ausente quando a Feature não declara etiquetas, e quando otypedo anexo não se resolve em nenhuma entidade de catálogo..values(mapa). O pilar próprio da intenção do programador do anexo, escrito na declaração do anexo no Aggregate. Distinto do.valuesde nível superior do componente host..infra(mapa). O pilar próprio do dimensionamento operacional do anexo, escrito na declaração do anexo na Release. Distinto do.infrade nível superior do componente host..provides(mapa com valores de string). O contrato público resolvido da FeatureRecipe associada a este anexo — o nome do recurso emitido, a sua chave de dados, uma identidade de nuvem e quaisquer chaves adicionais que a FeatureRecipe publique. Lê-se como.features.<name>.provides.<key>, espelhando.context.uses.<alias>.provides: o consumidor lê o que o produtor publicou em vez de o derivar novamente. Um anexo cuja FeatureRecipe associada não publica nada não contém nenhuma chaveprovides, em vez de um mapa vazio, pelo que deve verificar antes de aceder a uma chave individual.
.provides é o que torna um anexo consumível, e não apenas presente. Uma Feature que declara um contrato schema.provides tem esse contrato aplicado à FeatureRecipe que a realiza — a FeatureRecipe tem de publicar cada chave declarada — e o consumidor lê aqui o resultado. Assim, uma Feature de identidade que emite uma ServiceAccount e publica o seu nome permite que a Recipe consumidora se associe a ela:
workload: | serviceAccount: "{{ .features.identity.provides.name }}"O nome emitido é declarado uma única vez, pelo produtor, e consumido — nunca repetido do lado consumidor, onde os dois poderiam divergir. O exemplo workload-identity-binding renderiza isto de ponta a ponta.
.labels é o que permite a um template adaptar-se ao que um anexo é sem comparar o seu nome nem analisar o seu URI. O compilador não lê nenhuma delas — transporta as strings, e o autor do template decide o que significam.
Uma Feature que não declara etiquetas não contém nenhum .labels, em vez de um mapa vazio, pelo que deve verificar antes de aceder a uma etiqueta individual — aceder através de uma chave que não existe interrompe a compilação. Uma etiqueta que a Feature pode não declarar lê-se através de optional, porque index interrompe a compilação nomeando a chave quando o mapa não a contém:
{{ if .features.db.labels }}{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}{{ end }}Como as etiquetas chegam literalmente, o namespace próprio do autor de um catálogo chega ao template inalterado, e uma Recipe lê a mesma chave que a Feature declara.
O bloco .context
.context é o contexto de execução montado pelo compilador para um único nó — os dados de identidade, de topologia e do pipe de entrega que o renderizador faz passar por cada ponto de template. Os seus campos:
.context.instance_id(string). A identidade do nó como nome — o valor que a própria compilação usa para nomear e etiquetar o que emite, pelo que um template que compõe a partir dele um nome de recurso ou um endereço interno do cluster prevê o nome que a compilação realmente produz. É o nome que escreveu para um nó que o seu próprio Aggregate declara. Para um nó que um Aggregate importado contribui, é a identidade achatada com o separador de módulo escrito por extenso (data-layer.main-dbpassa adata-layer-zdmain-db), porque um ponto não é um carácter que um nome de recurso possa conter e, dentro de um endereço de cluster, separa um serviço do seu namespace. A forma com pontos é a que os seus documentos e os diagnósticos da compilação usam para endereçar esse nó; consulte Convenções de nomenclatura..context.rendered_name(string). O nome que o fornecedor do nó dá aos recursos que renderiza para o nó — a partir da fonte fornecida, como o nome da release que um chart lê, e a partir de um workload que sintetiza quando nomeia os recursos desse workload segundo um nome próprio, comohelmfaz com o mesmo nome da release. Presente apenas onde esse fornecedor deriva um. Nos templates de um anexo de Feature, é o nome do componente host, tal como.context.instance_idé aí a identidade do host; consulte Atribuir um nome a um recurso renderizado..context.labels(mapa com valores de string). Etiquetas escritas no catálogo mais quaisquer adições delabel-transformfeitas na construção da topologia..context.annotations(três contentores, ver abaixo). Anotações em cascata, agrupadas por origem..context.inject(mapa de mecanismos, ver abaixo). O pipe de entrega pré-hidratado e intercetado — a superfície habitual que os templates de Recipe leem para valores entre componentes..context.uses(mapa de ligações, ver abaixo). A projeção JOIN sobre as arestas topológicas de saída..context.self_inject(mapa de mecanismos, ver abaixo). Para cada nome que o programador escreveu no próprio blocoinject:do componente, a chave provides própria que essa entrada entrega ou o único valor próprio que o seu template lê..context.used_by(lista, ver abaixo). Os componentes cujas entradasusesapontam para este. Lido por uma FeatureRecipe anexada ao componente, nos templates que produzem os recursos próprios do anexo; vazio em qualquer outro lugar..context.render_facts(mapa de listas, ver abaixo). O que o fornecedor do componente comunicou sobre a saída que renderizou, indexado pelo nome do facto. Lido por uma FeatureRecipe anexada ao componente, em cada um dos seus templates que é executado depois de o componente ter sido renderizado; ausente em qualquer outro lugar.
.context.annotations — três contentores
As anotações propagam-se em cascata para três contentores indexados por origem:
.context.annotations.release— anotações da fronteira da Release (Domínio 4). Usadas para governar realidades físicas; os renderizadores encaminham-nas para camposinfra:quando apropriado. As anotações conhecidasaggrega.ai/*residem neste contentor..context.annotations.catalog— anotações de metadados do Component do Domínio 2. Traços intrínsecos imutáveis escritos pelo Architect; consumidos principalmente por plugins de política Wasm..context.annotations.aggregate— anotações de subsistema do Aggregate do Domínio 1. Metadados cognitivos; os renderizadores encaminham-nas para payloadsvalues:quando apropriado.
Cada contentor é um mapa plano de string para string. Segundo as regras de separação da arquitetura, os contentores destinam-se a usos distintos; o motor não impõe a separação, pelo que é a disciplina de autoria que mantém os contentores alinhados com a semântica pretendida. Consulte capítulo 6 §2 Fluxo 5 para o design das anotações em cascata.
.context.inject — o pipe de entrega
O pipe é o mapa de entrega pré-resolvido do compilador. Quando um template de Recipe é executado na renderização base, cada fonte de inject (literais self-inject escritos pelo programador, referências from: self-inject resolvidas face aos próprios provides, referências uses[].inject entre componentes resolvidas face aos provides do destino, interceções injectMapping de FeatureRecipe) já foi resolvida num valor string final e fundida neste mapa.
Campos:
.context.inject.env— mapa com valores de string de nome de variável de ambiente → valor resolvido..context.inject.file— mapa com valores de string de caminho de ficheiro → valor resolvido..context.inject.arg— mapa com valores de string de flag de argumento → valor resolvido..context.inject.all— mapa com valores de string que combina os mecanismosenv/file/arg/personalizados num único dicionário plano; útil para serializar o pipe inteiro ({{ toJson .context.inject.all }}).
Um mecanismo só está no pipe quando algo entrega através dele. Um template que lê um através do qual nada entrega — .context.inject.file sem nenhuma entrega de ficheiro — lê-o como vazio, tal como um template de valor lê qualquer chave ausente, e um range sobre ele não renderiza nada; essa leitura fornece o valor vazio para o template inteiro, pelo que um {{ toJson .context.inject }} no mesmo template mostra "file": "". hasKey .context.inject "file" indica se algo entrega através dele.
- Mecanismos personalizados (por ex.,
ssm_param) — legíveis sob o seu próprio nome de campo,.context.inject.<mechanism>.<key>, exatamente como os três principais. Os valores de um mecanismo personalizado chegam ao pipe a partir do self-inject ao nível do componente, de uma arestauses[].inject, do mapeamentoinject:de um anexo de Feature e da saídainjectMappingde uma FeatureRecipe. Para o self-inject ao nível do componente, a allowlistspec.injectdo Component tem de nomear o mecanismo, e um mecanismo que a allowlist não nomeia interrompe a compilação. As entradas de um mecanismo personalizado também aparecem em.context.inject.allao lado dos três principais. Um mecanismo personalizado pode ter qualquer nome, excetoall: esse nome é a própria vista combinada, pelo que um mecanismo com esse nome nunca poderia ser lido isoladamente. Um bloco inject que nomeie um mecanismoall, e uma allowlist de um Component ou de uma Feature (spec.inject, oinjectde um socket) que o liste, interrompem a compilação quando o documento é carregado, e a recusa explica que o nome pertence a esta vista combinada. Os nomes distinguem maiúsculas de minúsculas, pelo queALLé um mecanismo personalizado comum.
O pipe é o estado posterior à interceção — os blocos injectMapping de FeatureRecipe já fundiram em profundidade as suas substituições sobre este pipe durante o mapeamento de inject, quando os templates de Recipe o leem. Um mapeamento pode substituir uma chave que o próprio bloco inject: do componente, um dos blocos inject: das suas ligações ou o bloco inject: do seu próprio anexo entregou; uma chave que duas Features anexadas entregam ambas, através dos seus blocos inject: ou dos seus mapeamentos, interrompe a compilação em vez de chegar a este pipe com um dos dois valores. Uma Feature anexada a uma fronteira da Release chega ao componente da mesma forma, através do injectMapping da sua FeatureRecipe, que é executado no próprio contexto do componente, qualquer que seja o executionScope da FeatureRecipe — a reescrita, pela bridge do compose, da variável de host de um consumidor é um desses mapeamentos, sujeito à mesma regra.
.context.self_inject — que valor próprio entrega cada um dos nomes do programador
Quando um Component declara spec.inject, o programador pode escrever um bloco inject: no próprio componente e escolher os nomes sob os quais os valores e os provides próprios do componente são entregues. .context.inject contém aquilo em que essas entradas foram resolvidas e .inject_raw contém-nas tal como foram escritas; .context.self_inject indica, para cada uma, a chave provides própria do componente que entrega ou o único valor próprio que o seu template lê. Tem a forma que tem o .context.uses.<alias>.inject de uma ligação — mecanismo, depois o nome do programador, depois uma chave —, com a chave a nomear um dos provides ou dos valores próprios do componente:
provides.<key>— uma entrada escrita comfrom: <key>, que entrega um dos provides próprios do componente.values.<key>— uma entrada cujo templatevalue:lê exatamente um dos valores próprios do componente e nada mais, sendo<key>a chave de nível superior desse valor. O texto ou as funções em torno da leitura não importam, nem a profundidade com que o template lê dentro do valor:'{{ .values.role }}','role={{ .values.role | upper }}'e'{{ with .values.role }}{{ . }}{{ end }}'correspondem todos avalues.role, e'{{ .values.config.port }}','{{ index .values.config "port" }}'e'{{ (default dict .values.config).port }}'correspondem todos avalues.config.- uma cadeia vazia — qualquer outra entrada: um literal, um template que lê dois valores, um template que lê algo além dos valores (
.infra,.metadata,.context), e um template cuja leitura dos valores o texto não atribui a uma única chave de nível superior — os valores passados a uma função pela sua raiz (index .values "role"), os valores lidos na totalidade (toJson .values, ou um campo lido dentro de{{ with .values }}ou através de uma variável associada a.values), ou o contexto inteiro passado adiante (toJson .).
# The developer's block on the component, in the Aggregateinject: env: - { in: SERVICE_HOST, from: host } - { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' } - { in: MODE, value: batch } - { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' } ssm_param: - { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_injectenv: SERVICE_HOST: provides.host AGENT_ROLE: values.role MODE: "" ROLE_AND_GOAL: ""ssm_param: /app/goal: values.goalNo Aggregate, cada template value: começa com {{"{{"}} em vez de {{, porque todo o texto do Aggregate é lido uma vez como template, para a interpolação de parâmetros, antes de os templates do próprio bloco serem avaliados; os templates citados na lista acima são apresentados tal como ficam após esse escape. Ver Texto que contém as suas próprias chavetas duplas.
É isto que permite a uma Recipe que executa a imagem do próprio programador tratar os seus próprios nomes de variáveis para os valores próprios do componente como predefinições — a convenção do catálogo da biblioteca padrão, que um catálogo empresarial pode escolher de outra forma. Antes de entregar um valor próprio sob um nome seu, uma Recipe deste tipo verifica se o bloco do programador já entrega esse valor e, em caso afirmativo, ignora a sua predefinição — assim, um programador que muda o nome de um valor mantém todas as outras predefinições:
workload: | containers: main: variables: {{- range $name, $value := .context.inject.env }} {{ $name }}: {{ $value | quote }} {{- end }} {{- $named := dict }} {{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }} {{- if not (hasKey $named "values.role") }} APP_ROLE: {{ .values.role | quote }} {{- end }}.context.self_inject está presente em todas as renderizações e vazio onde o programador não escreveu nenhum bloco. Um mecanismo só aparece quando o bloco o nomeia, pelo que deve proteger-se a leitura de um mecanismo que o bloco possa não nomear, como faz o with acima. Um template encontra os nomes ordenados, seja qual for a forma como os lê, tal como encontra qualquer mapa. O mapa é lido a partir do texto que o programador escreveu; nada nele é um valor resolvido, e o compilador não atribui qualquer significado aos nomes nem às chaves.
.context.uses — projeção JOIN
.context.uses é a vista enriquecida do compilador sobre cada aresta topológica de saída do nó atual. Cada entrada do mapa é indexada pelo alias local do socket (por ex., databases.primary passa a .context.uses.primary quando o Aggregate escreveu uses: { databases: { primary: { target: ... } } }) e contém uma projeção JOIN do estado resolvido do destino mais o contrato de entrega do lado do chamador:
.target(string) — ID de instância do nó de destino..socket(string) — nome do socket do lado do chamador (a chaveusesSchema)..provides(mapa com valores de string) — as chavesprovides:resolvidas do destino (as strings de saída públicas que a Recipe de destino exportou na avaliação dos provides)..inject(mapa de mecanismo → mapa de chave → valor) — diretivas de inject do lado do chamador para esta aresta (o blocoinject:na declaraçãouses[].inject). As chaves de mecanismo sãoenv/file/arg/personalizadas; as entradas do mapa por mecanismo são referências chave local → chave de provides do destino..labels(mapa com valores de string) — as etiquetas do destino, nunca as do componente consumidor: o conjunto que o próprio.context.labelsdo destino contém, as suas etiquetas escritas no catálogo mais quaisquer adições delabel-transformfeitas na construção da topologia..annotations(três contentores) — os contentores de anotaçõesrelease/catalog/aggregatedo destino..component(string) — URI do tipo de Component do destino..resolved_version(string) — versão do Component do destino após a resolução do Manifest..boundary_path(string) — caminho da fronteira da Release do destino, definido quer o destino esteja na fronteira do chamador, quer noutra..origin_feature(string) — definido quando a aresta foi sintetizada por um anexo de Feature (por ex., uma Feature sidecar que contribui com uma arestausespara uma Feature de credenciais)..values(mapa) — configuração do programador por aresta, resolvida, para esta ligação, escrita na entradausesdo Aggregate. Presente apenas quando a aresta contém valores por aresta..infra(mapa) — configuração do operador por aresta, resolvida, para esta ligação, escrita na entradausesda Release. Presente apenas quando a aresta contém infra por aresta..origin_release(booleano) —truequando foi a Release a estabelecer esta ligação, em vez de o Aggregate a declarar; ausente para uma ligação que o Aggregate declara..features(mapa de anexos) — os anexos escritos nesta ligação, indexados pelo nome do slot que o socket declara; consulte abaixo. Presente apenas quando a ligação contém um..render_facts(mapa de listas) — o que as renderizações do destino comunicaram sobre a saída que emitiram, indexado pelo nome do facto, na mesma forma que o.render_factsde um chamador em.context.used_by: cada facto é uma lista, primeiro as chamadas do próprio fornecedor do destino e depois cada uma das suas Features pela ordem em que renderizaram, e as listas que um nome recebe de cada um são unidas numa só. Presente apenas para uma FeatureRecipe que definereadsTargetRenderFacts: true— os seus anexos são renderizados depois de todos os componentes terem sido renderizados, pelo que a renderização de cada destino está completa — e então em cada ligação, vazio para um destino cujos fornecedores não comunicam nada. Lido apenas emvaluesMapping:,workload:eartifacts:dessa FeatureRecipe; ausente dos próprios templates de Recipe do componente, de uminjectMapping:, dewith:ewhen:de um passo depipeline:e de qualquer FeatureRecipe que não defina a chave — um template de uma delas que o lê interrompe a compilação antes de qualquer coisa ser renderizada.
Ambos os mapas de configuração por aresta têm âmbito de consumidor: chegam apenas ao contexto de renderização do nó consumidor, nunca ao do destino.
Um valor fornecido lê-se em .provides.<name> — os nomes fornecidos ficam aninhados sob .provides em vez de estarem diretamente na aresta, pelo que .context.uses.<alias>.<name> não endereça nenhum campo e não devolve nada.
Numa ligação cujas duas pontas são renderizadas em saídas diferentes, .provides contém substitutos em vez dos valores. Onde o fornecedor estabelece essa ligação com uma referência própria depois de ambas as saídas estarem montadas — uma stack do CloudFormation a ler um valor de outra stack, por exemplo —, cada valor que .context.uses.<alias>.provides contém é um marcador de posição que o fornecedor substitui mais tarde, por uma referência entre stacks ou pelo próprio valor, como descreve a sua própria página. Esse valor deve ser copiado, não comparado — a mesma regra seguida pelo valor que essa ligação entrega no pipe de inject, que é um marcador de posição do mesmo tipo. Deve escrevê-lo inteiro, dentro de uma string maior, ou através de uma função que o deixe como está, como quote. Um template que compara um valor que lê de .provides, ramifica com base nele, o mede ou o altera estaria a decidir com base no marcador de posição, pelo que a compilação é interrompida em vez disso, nomeando o template e cada valor que leu; a ramificação deve basear-se num valor próprio do componente consumidor. A interrupção abrange todos os templates que leem os .provides da ligação, incluindo o injectMapping: de uma FeatureRecipe anexada, e uma FeatureRecipe de âmbito de fronteira que lê as mesmas ligações sob .boundary. Uma ligação cujas duas pontas são renderizadas numa única saída contém os seus valores tal como são.
Um alias nomeia uma ligação, pelo que o mapa contém uma entrada para cada ligação que o componente estabelece. O mapa é indexado apenas pelo alias, qualquer que seja o socket em que uma ligação está estabelecida, e duas ligações de um mesmo componente nunca partilham um alias — nem num socket nem em dois, qualquer que seja o documento ou o anexo que traçou cada uma. A compilação recusa um par assim, nomeando ambas as ligações e onde cada uma foi escrita, antes de qualquer coisa ser renderizada. Uma lista que nomeia o mesmo destino duas vezes é um par assim, já que o alias de uma entrada de lista é o seu destino; também o é uma ligação local num socket models ao lado de uma ligação local num socket databases.
Os templates de Recipe consomem esta projeção para consultar o estado do lado do destino sem percorrer o grafo IR. Os templates injectMapping de FeatureRecipe usam-na para aceder às anotações do destino em decisões de encaminhamento entre fronteiras (o padrão do resolvedor de DNS do K8s documentado em entities/featurerecipe.md é o exemplo canónico desenvolvido).
Um template que itera sobre .context.uses vê as ligações por ordem de chave — ordenadas por alias —, não pela ordem em que o Aggregate as escreveu. Todos os mapas sobre os quais um template itera são percorridos dessa forma, incluindo .features e os .features de uma ligação, pelo que um template nunca recupera a ordem escrita iterando sobre um mapa; onde a ordem tem significado, a superfície de autoria modela-a como uma lista. Em qualquer caso, a saída renderizada é idêntica byte a byte entre compilações da mesma entrada.
Os anexos de uma ligação — .context.uses.<alias>.features
Um anexo escrito numa ligação — sob features: na entrada uses de um componente no Aggregate, ou na entrada da Release para essa ligação — preenche um slot que o socket declara. É um anexo do componente consumidor para tudo o que a compilação faz com ele: o Manifest associa a sua realização, a sua FeatureRecipe é renderizada do lado do consumidor, o seu contrato de provides é aplicado. Um template lê-o sob a ligação em que foi escrito:
{{- range $alias, $edge := .context.uses }}- name: {{ $alias }} api_base: {{ $edge.provides.endpoint }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} api_key_key: {{ .provides.key }} {{- end }}{{ end }}{{- end }}- Indexados por slot.
.context.uses.<alias>.features.<slot>nomeia o slot que o socket da ligação declara —credentialacima —, pelo que um consumidor que alcança vários destinos lê a credencial própria de cada destino sob o alias desse destino. Uma ligação que não contém nenhum anexo não tem.features, e é por isso que a leitura é protegida. - A forma do anexo. Cada entrada contém exatamente o que
.features.<name>contém para um dos anexos próprios do componente —.type,.resolved_version,.labels,.values,.infrae os.providesresolvidos da FeatureRecipe associada a ele —; consulte a forma do anexo. Os provides lidos aqui são aqueles com base nos quais a própria FeatureRecipe do anexo é renderizada, pelo que o nome que um consumidor referencia e o nome do recurso que essa FeatureRecipe emite são um único valor avaliado. - Nunca em
.features. Os.featurespróprios do componente contêm apenas os anexos escritos no seu próprio bloco. Uma Recipe que itera sobre.featurese seleciona anexos por tipo —{{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}…— nunca encontra, portanto, a credencial de uma ligação, nem mesmo uma da mesma Feature: um template chega ao anexo de uma ligação através da sua ligação, nunca através de.features. O mesmo se aplica a todas as superfícies que mostram os anexos de um componente, incluindo o contextoassertions.
Os componentes que usam este — .context.used_by
.context.uses olha para fora, para as ligações que um componente estabelece. .context.used_by olha para dentro, para os componentes cujas entradas uses apontam para este. Uma FeatureRecipe anexada ao componente lê-o, e é aí que cabe um recurso que descreve ou restringe essas ligações — uma network policy que admite apenas os componentes declarados como chamadores deste, por exemplo:
artifacts: callers.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: {{ .context.rendered_name }}-{{ .attachment_name }} data: callers: | {{- range .context.used_by }} - component: {{ .component_id }} socket: {{ .socket }} selector: {{ .provides.selector }} {{- with .source_namespace }} namespace: {{ . }} {{- end }} {{- end }}Cada entrada contém:
.component_id(string) — o ID de instância do componente que se liga na sua forma achatada (frontend,data-layer.etl), o valor que um template de caminhosubDirectory:lê como.component_id..socket(string) — o socket que a ligação preenche no componente que se liga (a sua chaveusesSchema)..provides(mapa com valores de string) — o que o componente que se liga publica, restrito às chaves que o seu Component declara: os mesmos valores que um consumidor desse componente lê em.context.uses.<alias>.provides. Uma chave que a Recipe do componente publica sem que o seu Component a declare não está entre eles..source_namespace(string) — o namespace em que o componente que se liga está colocado: a anotaçãoaggrega.ai/namespaceque se lhe aplica, propagada em cascata ao longo das suas fronteiras, com precedência para a sua própria entrada na Release. Um componente cuja entrada na Release define o namespace, ou o limpa comnull, contém a sua própria definição em vez da da sua fronteira, pelo que o valor nomeia o namespace em que os recursos próprios do componente são renderizados. Ausente quando nenhum namespace se aplica ao componente; deve lê-lo através dewithouif, como faz o exemplo, em vez de o imprimir diretamente..source_boundary_path(string) — o caminho da fronteira da Release que contém o componente que se liga, com as fronteiras aninhadas unidas por/(edge,edge/inner)..render_facts(mapa de listas) — o que as renderizações do componente que se liga comunicaram sobre a saída que emitiram, indexado pelo nome do facto, na mesma forma que.context.render_facts. Cada facto é uma lista, pelo que um template itera sempre sobre ele, mesmo quando contém uma única entrada. As suas entradas podem vir da própria renderização do componente que se liga e das renderizações das Features anexadas a ele: as listas que um nome recebe de cada um são unidas numa só, primeiro as chamadas do próprio fornecedor do componente, depois cada uma das suas Features pela ordem em que renderizaram. Presente apenas para uma FeatureRecipe que definereadsCallerRenderFacts: true— os seus anexos são renderizados depois de todos os componentes terem sido renderizados, pelo que a renderização de cada chamador está completa — e então em cada entrada, vazio para um chamador cujos fornecedores não comunicam nada. Uma FeatureRecipe que não define a chave não vê nenhum.render_factsem nenhuma entrada, e um template dela que os lê interrompe a compilação antes de qualquer coisa ser renderizada.
Os dois valores de colocação são os que uma FeatureRecipe de âmbito de fronteira lê como source_namespace e source_boundary_path na entrada da mesma ligação nas suas listas de arestas .boundary: ambas as vistas leem da mesma forma onde um componente está colocado, pelo que nunca divergem a esse respeito. Uma aresta nessas listas contém também o caminho de montagem de cada ponta — source_assembly_path e target_assembly_path, o diretório sob o diretório de saída da compilação no qual o fornecedor da ponta a monta —, que uma entrada de .context.used_by não contém.
Uma FeatureRecipe que define readsCallerRenderFacts: true lê os factos de cada chamador da mesma forma que lê os do host. Para um fornecedor que documenta um facto chamado ports cujas entradas contêm cada uma um port:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Um chamador cujo fornecedor não comunica nenhum ports renderiza um ports: vazio em vez de falhar, porque um nome que ninguém comunicou lê-se como nada.
Como a lista se comporta:
- Pela ordem escrita. As entradas seguem a ordem em que os componentes que se ligam estão escritos, depois a ordem das entradas
usespróprias de cada um. Um componente que se liga duas vezes aparece duas vezes, uma por ligação. Como é uma lista e não um mapa, umrangeencontra os chamadores por essa ordem — nada é ordenado. - Apenas onde o anexo renderiza os seus próprios recursos.
valuesMapping:,workload:eartifacts:da FeatureRecipe leem-na. Está vazia nos próprios templates de Recipe do componente, numinjectMapping:e emwith:ewhen:de um passo depipeline:, porque o que cada um deles produz pode acabar na própria saída renderizada do componente: uminjectMapping:escreve o pipe de entrega do componente, e um passo de pipeline pode reescrever os documentos do componente. É isso que mantém igual a própria saída de um componente, seja quem for que o use — ligar mais um chamador a um componente altera a saída de uma Feature anexada a ele que lê os seus chamadores, e nada do que o próprio componente renderiza. - Nada sobre a ligação em si. Uma entrada não contém
valuesneminfrapor ligação nem nenhum dos anexos da ligação; esses ficam com o componente consumidor, sob o seu.context.uses.<alias>. - Vazia quando nada usa o componente. Um
rangesobre ela não renderiza então nada. - Transmitido, nunca interpretado. A identidade, o socket, os valores publicados e a colocação são strings que o compilador deixa passar, e os factos de renderização são o que os fornecedores de cada chamador comunicaram, indexados por nome. Não infere nada de um nome, não obtém nada e não decide nada sobre quais chamadores um recurso deve admitir; o template decide.
O que foi comunicado por um fornecedor sobre uma renderização — .context.render_facts
O fornecedor de um componente pode comunicar factos sobre a saída que renderizou — propriedades dos documentos que escreveu que apenas o seu próprio conhecimento do seu formato consegue ver. Que factos um fornecedor comunica, sob que nomes e com que conteúdo em cada entrada, é o contrato documentado próprio desse fornecedor; consulte Comunicar factos sobre aquilo que um guest emitiu para o lado do fornecedor. O fornecedor helm, por exemplo, comunica as etiquetas dos templates de pod que emitiu, os seletores dos seus controladores e Services e as portas dos seus contentores — consulte os seus factos de renderização. Uma FeatureRecipe anexada ao componente lê o que o fornecedor do componente comunicou em .context.render_facts, indexado pelo nome do facto. Para um fornecedor que documenta um facto chamado ports cujas entradas contêm cada uma um name e um port:
artifacts: ports.yaml: | ports: {{- range .context.render_facts.ports }} - name: {{ .name }} port: {{ .port }} {{- end }}- Cada facto é uma lista. Um fornecedor comunica cada facto como uma lista, mesmo quando contém uma única entrada, pelo que um template itera sempre sobre ele — não há um valor único para ler isoladamente.
- Uma lista por nome, unida ao longo da renderização do componente. Renderizar um componente pode exigir mais do que uma chamada do seu fornecedor — uma renderização de chart e uma colocação de artifacts, por exemplo — e cada chamada comunica por si. As listas que um nome recebe dessas chamadas são unidas numa só, pela ordem em que as chamadas foram executadas. O que as Features anexadas ao componente renderizaram não está entre elas aqui: uma Feature lê apenas a própria renderização do componente em
.context.render_facts, seja o que for que as outras Features do componente tenham emitido. - Em todos os templates de uma FeatureRecipe anexada. Os seus
valuesMapping:,workload:eartifacts:leem-no, tal comowith:ewhen:dos seus passos depipeline:— os factos vêm da própria renderização do componente, pelo que lê-los não torna nada dependente de quem se liga ao componente. Está ausente dos próprios templates de Recipe do componente e de uminjectMapping:, que são executados antes de o componente ter sido renderizado. - Vazio em vez de ausente. Onde o fornecedor do componente não comunica nada,
.context.render_factsé um mapa vazio, e um nome que ninguém comunicou lê-se como nada, pelo que umrangesobre ele não renderiza nada em vez de falhar. - Ordem. Uma lista mantém as suas entradas pela ordem em que o fornecedor as comunicou. Uma entrada de objeto é um mapa com chaves como qualquer outro no contexto, pelo que um template que itera sobre um encontra as suas chaves por ordem de chave.
- Transmitido, nunca interpretado. O compilador verifica apenas que o valor de cada facto é uma lista. Não lê nada do que um nome ou uma entrada significa; o template decide o que fazer com isso.
O .uses de uma asserção — indexado por socket e depois por alias
Um template assertions: lê as mesmas ligações através de uma vista própria mais restrita: .uses na raiz em vez de sob .context, e sem nada do que o destino de uma ligação publicou, porque ambas as fases de asserção são avaliadas antes da renderização. Espelha a forma de autoria uses: <socket>: <alias>: { target: … } — indexado por socket e, sob cada socket, pelo alias de cada ligação nele, sendo que uma ligação escrita como entrada de lista toma o seu destino como alias. A entrada de cada ligação contém target, alias e, para uma ligação que um anexo de Feature traçou, origin_feature, além de três dos factos que .context.uses contém, com os mesmos nomes e os mesmos valores: .labels, as etiquetas do destino; .values, os valores escritos na ligação; e .features, os anexos escritos nela, indexados por slot. Cada um dos três está presente em todas as entradas, vazio onde a ligação não contém nenhum. Um anexo sob .features contém apenas o seu type, o seu resolved_version e os seus values — a forma em que uma asserção lê todos os anexos, incluindo os próprios de um componente, já que a FeatureRecipe de um anexo ainda não resolveu os seus provides quando uma asserção é executada.
Um socket que contém uma ligação e um socket que contém várias têm a mesma forma, pelo que uma asserção lê qualquer um deles da mesma forma. Para um componente cuja entrada no Aggregate escreve uses: { models: { local: { target: llama }, fast: { target: turbo } } }:
assertions: two-models-wired: | {{- if lt (len (optional .uses "models" dict)) 2 -}} {{- fail "wire two models to the models socket" -}} {{- end -}} local-is-llama: | {{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}} {{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}} {{- end -}}hasKey .uses "models" pergunta se o socket está ligado, len conta as suas ligações, um range sobre ele visita cada uma por ordem alfabética dos seus aliases, e .uses.models.local.target lê uma ligação. .uses.models.target não endereça nenhuma ligação e interrompe a compilação sob o missingkey=error da superfície de asserções. Cada ligação tem uma entrada própria, pela mesma razão que o mapa do contexto de renderização: duas ligações de um mesmo componente nunca partilham um alias, porque a compilação recusa isso antes de qualquer asserção ser executada. O contexto completo de asserções está documentado em assertions-block.md.
As superfícies relacionadas com inject
O contexto de template contém estes campos com forma de inject, cada um com a sua própria semântica. Os autores de Recipe e de FeatureRecipe devem saber que superfície ler.
| Superfície | Tipo | Preenchido quando | Utilização |
|---|---|---|---|
.context.inject | mapa de mecanismos (sempre presente) | Todas as renderizações | O pipe de entrega habitual pré-hidratado — deve ser lido nos templates valuesMapping:/workload:/artifacts: e em qualquer ponto de template de uma FeatureRecipe. |
.inject (nível superior) | mapa de mecanismos (pode ser nulo) | Ao renderizar a FeatureRecipe de um anexo, quando o anexo escreve um bloco inject: | As entradas inject: próprias do anexo, sob cada mecanismo que o seu bloco nomeia — env, file, arg ou um personalizado, como vault_ref —, com cada nome local associado à chave que o seu from: nomeia. Essa chave é uma que a FeatureRecipe publica nos seus provides:, que o compilador também entrega no .context.inject do componente, ou uma chave que uma FeatureRecipe que lê .inject consome ela própria: uma entrada que nomeie uma chave que a FeatureRecipe não publica interrompe a compilação, a menos que um template que a FeatureRecipe avalia em relação a este contexto — o seu valuesMapping:, workload:, artifacts:, omits: ou o with: ou o when: de um passo do pipeline — leia .inject através de um caminho que o template nomeia: .inject, .inject.env, {{ with .inject }} e semelhantes, e não uma passagem do contexto inteiro como toJson .. O seu injectMapping: não conta, porque é avaliado em relação ao contexto do componente, onde .inject está ausente. O bloco de um anexo não transporta literais: uma entrada value: aí interrompe a compilação, e um literal de que o componente precise é escrito no próprio bloco inject: do componente. Um mecanismo personalizado é lido em .inject.<mechanism> exatamente como .inject.env, e as suas entradas aparecem em .inject.all ao lado dos três principais. Uma leitura com pontos de um mecanismo que o anexo não escreve é interrompida como chave desconhecida, mesmo dentro de um if ou de um with, onde .context.inject.<mechanism> é lido como vazio; um mecanismo que o anexo possa não escrever deve ler-se através de {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, que compila quer o anexo escreva ou não o mecanismo ou algum bloco inject:. Ausente dos templates de uma Recipe base e de um anexo que não escreva nenhum bloco inject:. |
.inject_raw (nível superior) | mapa de mecanismos (pode ser nulo) | Definido quando o programador escreveu um bloco inject: no componente pai | A intenção do programador sem modificações, antes de qualquer interceção de inject-mapping. Cada mecanismo que o bloco indica — env, file, arg ou um personalizado, como ssm_param — fica sob o seu próprio nome, contendo as entradas exatamente como escritas (in com from ou value), pela ordem em que foram escritas: .inject_raw.ssm_param lê um mecanismo personalizado da mesma forma que .inject_raw.env lê o mecanismo nativo. Usa-se para verificações lógicas do tipo «o programador pediu originalmente esta chave de entrega?»; imune à reescrita pelo injectMapping de uma FeatureRecipe. nil se o programador omitiu o bloco inject:. |
.context.self_inject | mapa de mecanismos (sempre presente) | Todas as renderizações; vazio onde o programador não escreveu nenhum bloco inject: no componente | Cada nome no próprio bloco inject: do componente, associado à chave própria que a sua entrada entrega — provides.<key>, values.<key> ou vazio. Serve para ignorar um nome predefinido para um valor próprio que o programador já entrega; ver acima. |
Os autores que precisam da entrega resolvida após a interceção devem ler .context.inject. Os autores que precisam da intenção original imutável (por ex., para detetar uma interceção ou para emitir um comportamento alternativo quando o programador omitiu um bloco inject) devem ler .inject_raw. Os autores que precisam de saber quais dos valores próprios do componente o programador já nomeou devem ler .context.self_inject.
Superfície da FeatureRecipe de um anexo
Quando o renderizador avalia os templates da FeatureRecipe de um anexo, é definido um campo adicional de nível superior:
.attachment_name(string) — o nome de instância do anexo: o slot que preenche nofeaturesSchemada entidade proprietária, ou o nome livre que o autor lhe deu.locals:,provides:,injectMapping:,valuesMapping:eartifacts:de uma FeatureRecipe leem-no para derivar um identificador de recurso determinístico —{{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}onde o fornecedor do host comunica um nome renderizado, como fazhelm, e{{ .context.instance_id }}-{{ .attachment_name }}onde não comunica nenhum — e para nomear o anexo que está a ser processado.
Os próprios templates de uma Recipe base não estão a resolver um anexo, pelo que o campo não faz parte do seu contexto: um template provides:, locals: ou source: de uma Recipe que o referencie é interrompido nomeando a referência em vez de renderizar um valor vazio. Uma FeatureRecipe com executionScope: boundary é renderizada uma vez para a fronteira em vez de uma vez por componente, pelo que o campo também não está disponível para os templates executados para a fronteira; o seu injectMapping: é executado para cada componente que o anexo alcança e lê-o aí.
Nos templates que produzem os recursos próprios do anexo — os seus valuesMapping:, workload: e artifacts: —, o contexto do anexo também lista os componentes que usam o seu host, em .context.used_by, e, onde a sua FeatureRecipe define readsTargetRenderFacts: true, contém o que cada componente a que o seu host está ligado renderizou, em .context.uses.<alias>.render_facts. Esses templates e os seus passos de pipeline: também leem o que o fornecedor do seu host comunicou sobre a renderização do host, em .context.render_facts. Uma FeatureRecipe de âmbito de fronteira renderiza os seus recursos para nenhum componente host e sem .context; em vez disso, lê cada ligação para a sua fronteira sob .boundary.internal_uses_edges e .boundary.incoming_cross_boundary_uses_edges. O seu injectMapping: é o único template que escreve que é executado no contexto de um componente — o de cada componente que o anexo alcança, .context.* incluído —, e uma referência a .boundary aí interrompe a compilação.
O campo é a única via para o nome de instância do anexo. .context.instance_id é o componente host para o qual o anexo está a ser resolvido — denota o host em todas as superfícies de template que o compilador avalia, incluindo os locals: próprios de uma FeatureRecipe —, pelo que os dois nomes não são intercambiáveis, e nenhum substitui o outro.
.source é o do próprio anexo. O template source: de uma FeatureRecipe é avaliado antes do seu valuesMapping:, tal como o de uma Recipe é avaliado antes do seu, e o que produziu é o que .source contém nos templates que produzem os recursos do anexo — o seu valuesMapping:, omits:, workload: e artifacts: — e nos seus passos de pipeline:. Nunca é a fonte do componente host: uma FeatureRecipe que não declare nenhum source:, ou cujo template não produza nada, não lê nada aí, mesmo num host cuja Recipe declare um. Uma FeatureRecipe com âmbito de fronteira lê a sua própria fonte nos mesmos templates. A única exceção é o injectMapping:, que é executado antes de a fonte do anexo ser avaliada e lê .source tal como o faz a própria Recipe do componente host.
.context.rendered_name é também o do componente host: em todos os templates de um anexo por componente, contém o nome que o próprio fornecedor do host comunica para o host — o valor que a própria Recipe do host lê —, pelo que um anexo nomeia um recurso a partir do seu host com {{ .context.rendered_name }}-{{ .attachment_name }} e obtém um nome que a plataforma aceita mesmo onde a identidade do host contém um carácter de sublinhado ou uma letra maiúscula. Está presente sempre que o fornecedor do host comunica um nome e ausente onde não comunica nenhum, e lê-lo num host assim interrompe a compilação a partir de qualquer template que a FeatureRecipe escreva inline além do seu injectMapping:; consulte Atribuir um nome a um recurso renderizado.
Disponibilidade por ponto de template
A disponibilidade dos campos varia consoante o ponto de template. Os templates provides: de uma Recipe são executados na avaliação dos provides com um contexto autónomo (sem .context.inject/.context.uses); o valuesMapping: de uma Recipe é executado na renderização base com o contexto de template completo; o injectMapping: de uma FeatureRecipe é executado no mapeamento de inject com o contexto de template completo, incluindo o pipe de inject que está a ser intercetado. A tabela completa de disponibilidade ponto a ponto encontra-se em expansion-matrix.md; esta página documenta as formas dos campos para as quais aponta a coluna «referências disponíveis» da matriz.
Referências cruzadas
05-templates.md— visão geral da utilização de templates.expansion-matrix.md— matriz de avaliação por ponto de template.sprig-functions.md— helpers do Sprig integrados no motor de templates.../entities/recipe.md— superfície de autoria da Recipe.../entities/featurerecipe.md— superfície de autoria da FeatureRecipe (incluindo o exemplo desenvolvido do resolvedor de DNS do K8s para percorrer.context.uses).../vocabulary/topology-triad.md— especificação do contrato de injeção (abrange o contexto de estado duplo, as regras de colisão de chaves e exemplos desenvolvidos).../10-status.md#compilation-pipeline-phases— prontidão atual das superfícies de inject-mapping, renderização base e pipeline de plugins.