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

Nomear um recurso renderizado

Uma Recipe precisa rotineiramente nomear algo que a sua própria saída produziu: um hostname a publicar por meio de provides:, uma referência dentro de um valuesMapping:, um identificador escrito em um corpo artifacts:. Duas chaves do contexto de template carregam os nomes disponíveis para isso, e elas respondem a perguntas diferentes. Ler a errada produz uma saída silenciosamente errada em vez de recusada — um endereço que nomeia um recurso que nada emitiu —, por isso esta página expõe qual chave responde a qual pergunta.

Ela também expõe a distinção em que as duas chaves se apoiam: um destino e uma referência não são a mesma coisa, e um destino nunca é um nome que uma plataforma de implantação vai resolver.

Um destino nomeia um componente; uma referência nomeia um recurso renderizado

Um destino é uma identidade de autoria. É o valor que um desenvolvedor escreve para dizer para qual componente uma aresta aponta — target: my_db em um bloco uses — e é a identidade que o build usa para encontrar esse componente, relatar sobre ele nos diagnósticos e indexar os seus fatos. Ele é lido da mesma forma em qualquer provedor, porque é um fato sobre os seus documentos e não sobre qualquer plataforma.

Uma referência é o que faz um artefato renderizado apontar para outro. Ela é escrita no vocabulário próprio de um provedor: um endereço interno do cluster sob helm, um nome de serviço sob compose, uma interpolação sob terraform, um valor importado sob cloudformation. Uma referência é diferente em cada provedor, porque cada plataforma resolve referências do seu próprio jeito.

🔴 Um destino nunca é escrito na saída renderizada. Cada provedor deriva os seus próprios nomes, de modo que uma identidade escrita pelo autor entregue a uma plataforma como nome está errada sempre que as duas grafias diferem — e elas diferem exatamente nos caracteres que o próprio alfabeto de um destino não admite. Uma identidade que não carrega nenhum caractere desse tipo sobrevive inalterada, e é isso que torna fácil errar: o erro funciona até que alguém nomeie um componente com um sublinhado ou uma letra maiúscula.

A referência de que um consumidor precisa é, portanto, publicada pelo produtor, porque a Recipe de um produtor é o que conhece o vocabulário do seu próprio provedor — um consumidor pode vincular um provedor totalmente diferente, e não pode escrever uma referência para uma plataforma para a qual não renderiza. O consumidor lê uma string publicada comum.

O par de exemplo

A Recipe do produtor publica o endereço; o consumidor o lê de volta por meio do alias da aresta.

# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.
# It publishes an in-cluster address built from the name that chart's own
# templates render their resources against.
spec:
capability: helm
source: ./charts/postgres
provides:
host: "{{ .context.rendered_name }}.svc.cluster.local"
port: "5432"
# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an
# authoring identity and stays in the documents. The uses block is keyed by the
# socket the catalog entity declares, then by the alias you choose for the edge.
spec:
components:
api:
type: core/compute/api-server
uses:
databases:
primary:
target: my_db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.
# The context keys an edge by its alias, so the socket does not reappear here.
spec:
capability: helm
valuesMapping: |
{
"db_host": "{{ .context.uses.primary.provides.host }}"
}

Para um chart fornecido pelo autor sob helm, um componente chamado my_db renderiza os seus recursos sob o nome da release my-zudb. Assim, o chart do produtor emite um Service cujo metadata.name é my-zudb, o host publicado é my-zudb.svc.cluster.local, e o consumidor se conecta a um Service que existe — quer leia o valor por meio de .context.uses.primary.provides.host, quer o receba como o DB_HOST injetado.

Escrever {{ .context.uses.primary.target }} ali publicaria my_db.svc.cluster.local em vez disso. Esse valor não parece errado: é a identidade que o desenvolvedor escreveu, grafada exatamente como ele a escreveu. Ele simplesmente não nomeia nenhum Service, e nada no build indica isso.

As duas chaves, como par

Nenhuma das duas chaves é legível sozinha, porque cada uma é definida pelo que a outra não é.

ChaveO que nomeia
{{ .context.instance_id }}A identidade do nó, e o nome dos recursos construídos para este nó para os quais nenhum provedor deriva um nome — um conjunto de artefatos posicionado a partir do seu bloco artifacts:, e um workload sintetizado a partir do seu bloco workload: por um provedor que o nomeia segundo a identidade, como faz compose. Sempre presente.
{{ .context.rendered_name }}O nome que o provedor associado deriva para os recursos que renderiza para este nó — para uma fonte fornecida por você, o nome com base no qual seus próprios templates fornecidos renderizam os recursos deles, como o nome da release que um chart lê; para um workload: que ele sintetiza, o nome que ele dá a esses recursos quando os nomeia segundo um nome próprio em vez da identidade, como faz helm. Presente somente onde esse provedor deriva um. Nos templates próprios de uma vinculação de Feature, é o nome do componente host — veja mais abaixo.

A divisão decorre de onde o nome precisa ser utilizável. Um chart ou módulo que você forneceu tem templates, e esses templates nomeiam seus recursos segundo qualquer identidade que a plataforma lhes entregue — portanto o nome precisa ser aquele que essa plataforma usará, escrito no alfabeto próprio dessa plataforma. Um workload sintetizado não tem templates seus, mas seus recursos ainda precisam ter nomes que a plataforma aceite: um provedor cujos nomes admitem tudo o que um nome escrito pelo autor pode conter os nomeia segundo a identidade, e um cujos nomes não admitem os nomeia segundo o nome que deriva — e então informa esse nome aqui, para que você nunca precise prevê-lo.

Um nó que declara tanto uma fonte fornecida quanto um workload: emite os dois tipos de saída ao mesmo tempo, e não precisa de uma terceira chave. Sob helm ambos são nomeados segundo o único nome da release, então rendered_name serve para qualquer um: os recursos próprios do chart o carregam independentemente de como seus templates o componham, e cada Service sintetizado é <rendered_name>-<service key>. Sob um provedor que nomeia um workload sintetizado segundo a identidade, nomeie os recursos desse workload com instance_id e os da saída fornecida com o que o provedor informar para ela.

Os alfabetos são o motivo pelo qual os dois podem diferir. Um nome de componente escrito pelo autor pode conter um sublinhado ou uma letra maiúscula; o nome da release de um chart não pode, e em vez de reduzir esse caractere a um semelhante — o que permitiria que dois componentes que você consegue distinguir chegassem a um único nome em um cluster — a derivação o escreve por extenso. Veja ../providers/helm.md “How the release name is derived (Como o nome da release é derivado)” para o alfabeto e o limite de comprimento próprios desse provedor.

Quais provedores informam um nome, e por que os outros não

helm informa um: o nome da release. Um chart fornecido como fonte o lê como .Release.Name e rotineiramente nomeia seus recursos segundo ele, e o provedor também nomeia segundo ele cada recurso que sintetiza para um componente — o controlador com o próprio nome da release, e cada Service como <release name>-<service key>. Portanto, um endereço publicado para qualquer um dos dois tipos de saída é construído a partir de rendered_name. Para um nó que posiciona apenas um conjunto de artefatos, ele não informa nenhum: os nomes nesse conjunto são os que seu autor escreveu.

# A synthesized helm Recipe publishing the address of the Service its workload
# declares under the key `default`.
spec:
capability: helm
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
containers:
main:
image: "valkey/valkey:8"
ports:
redis: 6379
services:
default:
type: ClusterIP
ports:
redis: 6379
provides:
host: "{{ .context.rendered_name }}-default"
port: "6379"

Um componente chamado cache publica cache-default, e um chamado my_cache publica my-zucache-default — em cada caso, o nome do Service que o build emite.

Os outros quatro não informam nenhum, e os motivos não são os mesmos. Nenhum deles é um provedor aguardando suporte — em cada caso, ou não há nenhum nome derivado a informar, ou o nome que você quer já é acessível de outra forma.

  • cloudformation e compose — você escreveu os nomes, ou a identidade é o nome. Uma Recipe de cloudformation escreve os ids lógicos dos seus recursos e o provedor os lê exatamente como escritos; um arquivo compose que você forneceu nomeia os próprios serviços e o provedor mescla e rotula esse arquivo sem renomear nada nele. Um workload que compose sintetiza é nomeado segundo a identidade do nó, que um arquivo compose admite como escrita, então {{ .context.instance_id }} é esse nome. Não há nenhuma derivação a informar, e os nomes são os que constam nos seus próprios documentos. Esse nome é o do serviço principal do workload, aquele que um par alcança; um serviço sidecar ou de inicialização que ele carrega é nomeado a partir da mesma identidade e do nome do contêiner, unidos por --, como descreve Como um serviço sidecar ou de inicialização é nomeado.

  • terraform — o nome é função de onde os arquivos foram posicionados. O bloco module de um contribuidor é nomeado a partir do diretório de saída em que sua configuração foi escrita, o que é definido quando os arquivos da fronteira são montados, e não quando um nó é renderizado. No momento em que os templates de uma Recipe são executados, essa posição ainda não existe.

  • helm-chart — o nome que ele deriva é o endereço próprio do chart posicionado, que é uma coisa diferente do nome com base no qual os templates desse chart renderizam. Este provedor define o campo name de um chart que você incorporou por vendoring como a identidade codificada daquilo que o contribuiu, que é também o alias pelo qual o umbrella vincula esse subchart e a chave sob a qual seus valores ficam delimitados. Para um componente, essa identidade é o que {{ .context.instance_id }} carrega, então o nome do chart posicionado já é acessível sob a chave que diz o que ele é. O nome com base no qual os próprios templates do chart incorporado renderizam é o nome da release, que a release do umbrella fornece no momento da instalação em vez de este provedor derivá-lo — então não há aqui nenhum nome desse tipo para esta chave informar. Veja ../providers/helm-chart.md “The chart name the umbrella owns (O nome do chart que pertence ao chart guarda-chuva)”.

Ler a chave onde nenhum nome é informado

Ler {{ .context.rendered_name }} em um nó cujo provedor não informa nenhum nome desse tipo interrompe o build, e o diagnóstico diz qual chave escrever em vez disso. Não renderiza um valor vazio: um endereço ao qual falta um segmento é um artefato errado que é implantado, o que é pior do que um build que para.

Qual solução a interrupção oferece depende do nó, e não de onde você escreveu a referência:

  • Um nó que não fornece nenhuma fonte própria, sob um provedor que não informa nenhum nome para ele, tem seus recursos nomeados segundo sua identidade, então a interrupção nomeia {{ .context.instance_id }} — existe um valor correto e ela o diz.
  • Um nó que de fato fornece fonte, sob um provedor que não deriva nenhum nome para ele, não tem substituto. A interrupção diz isso em vez de oferecer um, porque encaminhar você para a identidade ali nomearia recursos que seu nó não carrega.

A recusa abrange provides: e todo outro template que uma Recipe escreve inline — seu valuesMapping:, seu corpo workload:, cada entrada artifacts:, e os with: e when: de cada passo do pipeline.

🔴 As duas formas de importação ficam de fora. Uma entrada valuesMapping:, workload: ou artifacts: fornecida por meio de $import: — quer a importação nomeie um arquivo local, quer uma entrada de biblioteca — não carrega nenhum texto na sua Recipe até que a renderização a resolva, então uma referência a esta chave dentro de tal corpo não é verificada. Ela renderiza o nome que o provedor do nó importador informa onde esse provedor informa um, e um valor vazio em vez de uma interrupção onde ele não informa nenhum. Um corpo importado, portanto, lê a chave somente quando toda Recipe que o importa está associada a um provedor que informa um nome — uma entrada de biblioteca escrita para Recipes de helm que usam um chart como fonte, e que diz isso em sua descrição. Um corpo destinado a importadores cujo provedor pode não informar nenhum obtém o nome, em vez disso, por meio de um valor que a Recipe importadora define.

As entradas locals: de uma Recipe não leem a chave de forma alguma. Um local compartilha seu contexto com o template source: da Recipe, e se o nó fornece fonte é uma das coisas de que o nome depende, então o nome não é oferecido ali. Uma referência a {{ .context.rendered_name }} em um local, portanto, causa uma interrupção seja o que for que o provedor informe, com o diagnóstico para uma referência que o contexto de renderização não define (E0060), que lista .context.instance_id como a única chave que .context oferece ali. Leia a chave na entrada provides: ou no template inline que precisa dela.

Nos templates próprios de uma vinculação de Feature

Nos templates que a FeatureRecipe de uma vinculação de Feature escreve — seus locals:, source:, provides:, injectMapping:, valuesMapping:, workload:, cada entrada artifacts:, e os with: e when: de cada passo do pipeline — {{ .context.rendered_name }} é o nome do componente host: aquele que o próprio provedor do host informa para os recursos que renderiza para o host, que é o valor que a própria Recipe do host lê. Ele forma par com {{ .context.instance_id }}, que nesses templates é a identidade do componente host; a própria vinculação é .attachment_name. Uma vinculação escrita em uma das conexões de um componente lê o nome do componente consumidor, porque esse componente é o seu host.

Essa é a chave a partir da qual construir os nomes dos recursos próprios de uma vinculação. Uma FeatureRecipe que nomeia um Secret, uma rota ou uma política segundo o componente ao qual está vinculada precisa de um nome que a plataforma aceite, e a identidade do host como escrita não é um onde quer que contenha um sublinhado ou uma letra maiúscula. Sob helm, um componente chamado my_db informa my-zudb, então um Secret chamado {{ .context.rendered_name }}-{{ .attachment_name }} para uma vinculação root é renderizado como my-zudb-root, enquanto {{ .context.instance_id }} daria my_db-root, que um cluster recusa. O valor continua sendo o do host qualquer que seja o provedor por meio do qual a vinculação é renderizada.

Ela está presente onde quer que o provedor do host informe um nome — sob helm, um host cuja Recipe fornece um chart ou declara um workload: — e ausente onde ele não informa nenhum: um host que posiciona apenas um conjunto de artefatos, e um host em qualquer outro provedor. Lê-la em uma vinculação de tal host interrompe o build com o diagnóstico para uma referência que o contexto de renderização não define (E0060), que lista as chaves que .context define ali. {{ .context.instance_id }} está entre elas, e é segundo ela que os recursos próprios do host são nomeados em tal host, então uma FeatureRecipe escrita para hosts que podem não informar nenhum nome lê a identidade em vez disso.

A recusa abrange os templates que uma FeatureRecipe escreve inline, exceto seu injectMapping:. Um injectMapping:, e uma entrada valuesMapping:, workload: ou artifacts: que a FeatureRecipe fornece por meio de $import:, não são verificados: em um host que não informa nenhum nome, uma referência ali renderiza um valor vazio em vez de interromper.

Onde uma vinculação entrega um chart fornecido pelo seu autor, os templates desse chart renderizam com base no nome da release do componente host, deliberadamente: derivá-lo da vinculação renomearia recursos que o autor do chart declarou e talvez já tenha implantado. .attachment_name é o valor que distingue duas vinculações em um mesmo host — veja ../providers/helm.md “How the release name is derived (Como o nome da release é derivado)”.

Nomes derivados da vinculação de uma conexão

Uma vinculação que uma conexão carrega é uma vinculação do componente consumidor, com o nome <alias>.<slot> — gpt.credential para o slot credential da conexão escrita sob o alias gpt (veja a entrada de conexão do Aggregate). Esse nome composto é o .attachment_name com base no qual a sua FeatureRecipe renderiza, e ele contém o ponto.

Dele decorrem dois tipos de nome, e eles tratam o ponto de forma diferente.

Um nome que a FeatureRecipe compõe mantém o que quer que seu template escreva. As realizações de credencial da biblioteca padrão nomeiam seu recurso {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, então a credencial na conexão gpt de um componente chamado router é renderizada como um recurso chamado router-gpt.credential, ponto incluído, que é um nome de objeto Kubernetes válido. O ponto sobrevive em um nome desse tipo exatamente quando o template o mantém.

Um nome que o build deriva da identidade da vinculação escreve o ponto por extenso. Os rótulos de identidade e o arquivo emitido são compostos a partir do componente host e do nome da vinculação por meio da mesma codificação pela qual passa todo nome derivado de uma identidade, e ela escreve o ponto como zd e uma letra maiúscula como um escape do seu ponto de código, porque a identidade é usada como nome de recurso e também como rótulo, e um nome de Service não admite nenhum dos dois: uma conexão escrita sob o alias gptPro chegaria a cfr--router--gpt-zx000050ro-zdcredential. O recurso acima tem o rótulo aggrega.ai/component-id: cfr--router--gpt-zdcredential (e app.kubernetes.io/name da mesma forma), e sob o provedor helm é emitido como router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Veja Convenções de nomenclatura “The separator does not reach a name (O separador não chega a um nome)” para saber por que o ponto é escrito por extenso em vez de substituído.