Atribuir um nome a um recurso renderizado
Uma Recipe tem habitualmente de nomear algo que a sua própria saída produziu: um nome de anfitrião a publicar através de provides:, uma referência dentro de um valuesMapping:, um identificador escrito num corpo artifacts:. Duas chaves do contexto de template contêm os nomes disponíveis para isso, e 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 —, pelo que esta página expõe que chave responde a que pergunta.
Expõe também a distinção em que as duas chaves assentam: um destino e uma referência não são a mesma coisa, e um destino nunca é um nome que uma plataforma de implementação vá resolver.
Um destino nomeia um componente; uma referência nomeia um recurso renderizado
Um destino é uma identidade de autoria. É o valor que um programador escreve para dizer para que componente aponta uma aresta — target: my_db num bloco uses — e é a identidade que a compilação usa para encontrar esse componente, reportá-lo nos diagnósticos e indexar os seus factos. Lê-se da mesma forma com qualquer fornecedor, porque é um facto sobre os seus documentos e não sobre qualquer plataforma.
Uma referência é o que faz um artefacto renderizado apontar para outro. É escrita no vocabulário próprio de um fornecedor: 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 fornecedor, porque cada plataforma resolve as referências à sua maneira.
🔴 Um destino nunca é escrito na saída renderizada. Cada fornecedor deriva os seus próprios nomes, pelo que uma identidade escrita pelo autor entregue a uma plataforma como nome está errada sempre que as duas grafias diferem — e diferem exatamente nos caracteres que o próprio alfabeto de um destino não admite. Uma identidade que não contenha nenhum carácter desse tipo sobrevive inalterada, e é isso que torna fácil errar: o erro funciona até alguém nomear um componente com um sublinhado ou uma letra maiúscula.
A referência de que um consumidor precisa é, por isso, publicada pelo produtor, porque a Recipe de um produtor é o que conhece o vocabulário do seu próprio fornecedor — um consumidor pode vincular um fornecedor totalmente diferente, e não pode escrever uma referência para uma plataforma para a qual não renderiza. O consumidor lê uma cadeia publicada comum.
O par de exemplo
A Recipe do produtor publica o endereço; o consumidor volta a lê-lo através 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 liga-se a um Service que existe — quer leia o valor através de .context.uses.primary.provides.host, quer o receba como o DB_HOST injetado.
Escrever ali {{ .context.uses.primary.target }} publicaria em vez disso my_db.svc.cluster.local. Esse valor não parece errado: é a identidade que o programador escreveu, grafada exatamente como a escreveu. Simplesmente não nomeia nenhum Service, e nada na compilação o indica.
As duas chaves, como par
Nenhuma das duas chaves é legível isoladamente, porque cada uma é definida por aquilo que a outra não é.
| Chave | O que nomeia |
|---|---|
{{ .context.instance_id }} | A identidade do nó, e o nome dos recursos construídos para este nó para os quais nenhum fornecedor deriva um nome — um conjunto de artefactos colocado a partir do bloco artifacts:, e um workload sintetizado a partir do bloco workload: por um fornecedor que o nomeia segundo a identidade, como faz compose. Sempre presente. |
{{ .context.rendered_name }} | O nome que o fornecedor associado deriva para os recursos que renderiza para este nó — para uma fonte fornecida pelo utilizador, o nome com base no qual os próprios templates fornecidos renderizam os seus recursos, como o nome da release que um chart lê; para um workload: que sintetiza, o nome que dá a esses recursos quando os nomeia segundo um nome próprio em vez da identidade, como faz helm. Presente apenas onde esse fornecedor deriva um. Nos templates próprios de um anexo de Feature, é o nome do componente host — consulte mais abaixo. |
A divisão decorre do sítio onde o nome tem de ser utilizável. Um chart ou módulo fornecido pelo próprio utilizador tem templates, e esses templates nomeiam os seus recursos segundo a identidade que a plataforma lhes entregue — por isso o nome tem de ser aquele que essa plataforma utilizará, escrito no alfabeto próprio dessa plataforma. Um workload sintetizado não tem templates do utilizador, mas os seus recursos continuam a ter de ostentar nomes que a plataforma aceite: um fornecedor cujos nomes admitem tudo o que um nome escrito pelo autor pode conter nomeia-os segundo a identidade, e um cujos nomes não o admitem nomeia-os segundo o nome que deriva — e depois comunica esse nome aqui, para que nunca seja preciso prevê-lo.
Um nó que declara tanto uma fonte fornecida como um workload: emite os dois tipos de saída em simultâneo, e não precisa de uma terceira chave. Com helm, ambos são nomeados segundo o único nome da release, pelo que rendered_name serve qualquer um deles: os recursos próprios do chart ostentam-no seja como for que os seus templates o componham, e cada Service sintetizado é <rendered_name>-<service key>. Com um fornecedor que nomeia um workload sintetizado segundo a identidade, os recursos desse workload nomeiam-se com instance_id e os da saída fornecida com aquilo que o fornecedor comunicar para ela.
Os alfabetos são a razão pela 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 carácter a um semelhante — o que permitiria que dois componentes distinguíveis chegassem a um único nome num cluster — a derivação escreve-o por extenso. Consulte ../providers/helm.md «How the release name is derived (Como é derivado o nome da release)» para o alfabeto e o limite de comprimento próprios desse fornecedor.
Que fornecedores comunicam um nome, e porque é que os outros não o fazem
helm comunica um: o nome da release. Um chart fornecido como fonte lê-o como .Release.Name e habitualmente nomeia os seus recursos segundo ele, e o fornecedor 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>. Por isso, um endereço publicado para qualquer um dos dois tipos de saída é construído a partir de rendered_name. Para um nó que coloca apenas um conjunto de artefactos, não comunica nenhum: os nomes nesse conjunto são os que o 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 a compilação emite.
Os outros quatro não comunicam nenhum, e as razões não são as mesmas. Nenhum deles é um fornecedor à espera de suporte — em cada caso, ou não há nenhum nome derivado a comunicar, ou o nome pretendido já é acessível de outra forma.
-
cloudformationecompose— os nomes foram escritos pelo utilizador, ou a identidade é o nome. Uma Recipe de cloudformation escreve os ids lógicos dos seus recursos e o fornecedor lê-os exatamente como escritos; um ficheiro compose fornecido pelo utilizador nomeia os seus próprios serviços e o fornecedor funde e etiqueta esse ficheiro sem renomear nada nele. Um workload quecomposesintetiza é nomeado segundo a identidade do nó, que um ficheiro compose admite tal como escrita, pelo que{{ .context.instance_id }}é esse nome. Não há nenhuma derivação a comunicar, e os nomes são os que constam nos próprios documentos do utilizador. Esse nome é o do serviço principal do workload, aquele que um par alcança; um serviço sidecar ou de inicialização que contém é nomeado a partir da mesma identidade e do nome do contentor, unidos por--, como descreve Como é nomeado um serviço sidecar ou de inicialização. -
terraform— o nome é função do sítio onde os ficheiros foram colocados. O blocomodulede um contribuidor é nomeado a partir do diretório de saída em que a sua configuração foi escrita, o que fica definido quando os ficheiros 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 deriva é o endereço próprio do chart colocado, o que é uma coisa diferente do nome com base no qual os templates desse chart renderizam. Este fornecedor define o camponamede um chart incorporado por vendoring como a identidade codificada daquilo que o contribuiu, que é também o alias pelo qual o umbrella associa esse subchart e a chave sob a qual os seus valores ficam delimitados. Para um componente, essa identidade é o que{{ .context.instance_id }}transporta, pelo que o nome do chart colocado 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 ser este fornecedor a derivá-lo — por isso não há aqui nenhum nome desse tipo que esta chave possa comunicar. Consulte../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 é comunicado
Ler {{ .context.rendered_name }} num nó cujo fornecedor não comunica nenhum nome desse tipo interrompe a compilação, e o diagnóstico indica que chave escrever em alternativa. Não renderiza um valor vazio: um endereço ao qual falta um segmento é um artefacto errado que é implementado, o que é pior do que uma compilação que para.
A solução que a interrupção oferece depende do nó, e não do sítio onde a referência foi escrita:
- Um nó que não fornece nenhuma fonte própria, com um fornecedor que não comunica nenhum nome para ele, tem os seus recursos nomeados segundo a sua identidade, pelo que a interrupção nomeia
{{ .context.instance_id }}— existe um valor correto e ela indica-o. - Um nó que efetivamente fornece fonte, com um fornecedor que não deriva nenhum nome para ele, não tem substituto. A interrupção indica-o em vez de oferecer um, porque remeter para a identidade nesse caso nomearia recursos que o nó não transporta.
A recusa abrange provides: e qualquer outro template que uma Recipe escreva inline — o seu valuesMapping:, o 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 através de $import: — quer a importação nomeie um ficheiro local, quer uma entrada de biblioteca — não transporta nenhum texto na Recipe até que a renderização a resolva, pelo que uma referência a esta chave dentro de tal corpo não é verificada. Renderiza o nome que o fornecedor do nó importador comunica onde esse fornecedor comunica um, e um valor vazio em vez de uma interrupção onde não comunica nenhum. Por isso, um corpo importado lê a chave apenas quando cada Recipe que o importa está associada a um fornecedor que comunica um nome — uma entrada de biblioteca escrita para Recipes de helm que usam um chart como fonte, e que o diz na sua descrição. Um corpo destinado a importadores cujo fornecedor pode não comunicar nenhum obtém o nome, em alternativa, através de um valor que a Recipe importadora define.
As entradas locals: de uma Recipe não leem a chave de todo. Um local partilha o seu contexto com o template source: da Recipe, e o facto de o nó fornecer fonte é uma das coisas de que o nome depende, pelo que o nome não é oferecido aí. Uma referência a {{ .context.rendered_name }} num local causa, por isso, uma interrupção seja o que for que o fornecedor comunique, 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 aí. A chave deve ser lida na entrada provides: ou no template inline que dela precisa.
Nos templates próprios de um anexo de Feature
Nos templates que a FeatureRecipe de um anexo de Feature escreve — os 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 fornecedor do host comunica para os recursos que renderiza para o host, que é o valor que a própria Recipe do host lê. Forma par com {{ .context.instance_id }}, que nesses templates é a identidade do componente host; o próprio anexo é .attachment_name. Um anexo escrito numa das ligações de um componente lê o nome do componente consumidor, porque esse componente é o seu host.
Essa é a chave a partir da qual se constroem os nomes dos recursos próprios de um anexo. Uma FeatureRecipe que nomeia um Secret, uma rota ou uma política segundo o componente ao qual está anexada precisa de um nome que a plataforma aceite, e a identidade do host tal como escrita não o é sempre que contenha um sublinhado ou uma letra maiúscula. Com helm, um componente chamado my_db comunica my-zudb, pelo que um Secret chamado {{ .context.rendered_name }}-{{ .attachment_name }} para um anexo root é renderizado como my-zudb-root, ao passo que {{ .context.instance_id }} daria my_db-root, que um cluster recusa. O valor continua a ser o do host, seja qual for o fornecedor através do qual o anexo é renderizado.
Está presente sempre que o fornecedor do host comunica um nome — com helm, um host cuja Recipe fornece um chart ou declara um workload: — e ausente onde não comunica nenhum: um host que coloca apenas um conjunto de artefactos, e um host em qualquer outro fornecedor. Lê-la num anexo de tal host interrompe a compilação 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 aí. {{ .context.instance_id }} está entre elas, e é segundo ela que os recursos próprios do host são nomeados num tal host, pelo que uma FeatureRecipe escrita para hosts que podem não comunicar nenhum nome lê, em alternativa, a identidade.
A recusa abrange os templates que uma FeatureRecipe escreve inline, exceto o seu injectMapping:. Um injectMapping:, e uma entrada valuesMapping:, workload: ou artifacts: que a FeatureRecipe fornece através de $import:, não são verificados: num host que não comunica nenhum nome, uma referência aí renderiza um valor vazio em vez de interromper.
Onde um anexo entrega um chart fornecido pelo seu autor, os templates desse chart renderizam com base no nome da release do componente host, deliberadamente: derivá-lo do anexo renomearia recursos que o autor do chart declarou e que poderá já ter implementado. .attachment_name é o valor que distingue dois anexos num mesmo host — consulte ../providers/helm.md «How the release name is derived (Como é derivado o nome da release)».
Nomes derivados do anexo de uma ligação
Um anexo que uma ligação transporta é um anexo do componente consumidor, com o nome <alias>.<slot> — gpt.credential para o slot credential da ligação escrita sob o alias gpt (consulte a entrada de ligação do Aggregate). Esse nome composto é o .attachment_name com base no qual a sua FeatureRecipe renderiza, e contém o ponto.
Dele decorrem dois tipos de nome, que tratam o ponto de forma diferente.
Um nome que a FeatureRecipe compõe mantém o que quer que o seu template escreva. As realizações de credencial da biblioteca padrão nomeiam o seu recurso {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, pelo que a credencial na ligaçã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 num nome deste tipo exatamente quando o template o mantém.
Um nome que a compilação deriva da identidade do anexo escreve o ponto por extenso. As etiquetas de identidade e o ficheiro emitido são compostos a partir do componente host e do nome do anexo através da mesma codificação pela qual passa todo o nome derivado de uma identidade, e esta 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 etiqueta, e um nome de Service não admite nenhum dos dois: uma ligação escrita sob o alias gptPro chegaria a cfr--router--gpt-zx000050ro-zdcredential. O recurso acima tem a etiqueta aggrega.ai/component-id: cfr--router--gpt-zdcredential (e app.kubernetes.io/name do mesmo modo), e com o fornecedor helm é emitido como router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Consulte Convenções de nomenclatura «The separator does not reach a name (O separador não chega a um nome)» para saber porque é que o ponto é escrito por extenso em vez de ser substituído.
Tópicos relacionados
- Contrato do contexto de template — a forma completa do contexto em que estas chaves se encontram.
- Matriz de expansão de templates — que pilares cada ponto de template lê.
- Tríade de topologia:
provides,inject,uses— como um valor publicado atravessa uma aresta até um consumidor. - Convenções de nomenclatura — o que se pode escrever como nome de componente, e o que um nome custa com um alfabeto mais restrito.
errors/fatal-halts.md— a interrupção que esta página descreve, com a mensagem que emite.