Nombrar un recurso renderizado
Una Recipe tiene que nombrar habitualmente algo que produjo su propia salida: un nombre de host que publicar a través de provides:, una referencia dentro de un valuesMapping:, un identificador escrito en un cuerpo artifacts:. Dos claves del contexto de plantilla llevan los nombres disponibles para ello, y responden a preguntas diferentes. Leer la equivocada produce una salida silenciosamente errónea en lugar de rechazada — una dirección que nombra un recurso que nada emitió —, por lo que esta página expone qué clave responde a qué pregunta.
También expone la distinción en la que se basan las dos claves: un destino y una referencia no son lo mismo, y un destino nunca es un nombre que una plataforma de despliegue vaya a resolver.
Un destino nombra un componente; una referencia nombra un recurso renderizado
Un destino es una identidad de autoría. Es el valor que un desarrollador escribe para decir a qué componente apunta una arista — target: my_db en un bloque uses — y es la identidad que la compilación usa para encontrar ese componente, informar sobre él en los diagnósticos e indexar sus hechos. Se lee igual con cualquier proveedor, porque es un hecho sobre tus documentos y no sobre ninguna plataforma.
Una referencia es lo que hace que un artefacto renderizado apunte a otro. Se escribe en el vocabulario propio de un proveedor: una dirección interna del clúster con helm, un nombre de servicio con compose, una interpolación con terraform, un valor importado con cloudformation. Una referencia es distinta con cada proveedor, porque cada plataforma resuelve las referencias a su manera.
🔴 Un destino nunca se escribe en la salida renderizada. Cada proveedor deriva sus propios nombres, de modo que una identidad escrita por el autor entregada a una plataforma como nombre es errónea siempre que las dos grafías difieren — y difieren exactamente en los caracteres que el propio alfabeto de un destino no admite. Una identidad que no lleva ningún carácter de ese tipo sobrevive sin cambios, que es lo que hace que sea fácil equivocarse: el error funciona hasta que alguien nombra un componente con un guion bajo o una letra mayúscula.
La referencia que necesita un consumidor la publica por tanto el productor, porque la Recipe de un productor es la que conoce el vocabulario de su propio proveedor — un consumidor puede vincular un proveedor completamente distinto, y no puede escribir una referencia para una plataforma a la que no renderiza. El consumidor lee una cadena publicada corriente.
El par de ejemplo
La Recipe del productor publica la dirección; el consumidor la vuelve a leer a través del alias de la arista.
# 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 un chart aportado por el autor con helm, un componente llamado my_db renderiza sus recursos con el nombre de la release my-zudb. Así que el chart del productor emite un Service cuyo metadata.name es my-zudb, el host publicado es my-zudb.svc.cluster.local, y el consumidor se conecta a un Service que existe — tanto si lee el valor mediante .context.uses.primary.provides.host como si lo recibe como el DB_HOST inyectado.
Escribir {{ .context.uses.primary.target }} ahí publicaría en su lugar my_db.svc.cluster.local. Ese valor no parece erróneo: es la identidad que escribió el desarrollador, escrita exactamente como la escribió. Simplemente no nombra ningún Service, y nada en la compilación lo indica.
Las dos claves, como par
Ninguna de las dos claves es legible por sí sola, porque cada una se define por lo que la otra no es.
| Clave | Qué nombra |
|---|---|
{{ .context.instance_id }} | La identidad del nodo, y el nombre de los recursos construidos para este nodo para los que ningún proveedor deriva un nombre — un conjunto de artefactos colocado desde tu bloque artifacts:, y un workload sintetizado desde tu bloque workload: por un proveedor que lo nombra según la identidad, como hace compose. Siempre presente. |
{{ .context.rendered_name }} | El nombre que el proveedor asignado deriva para los recursos que renderiza para este nodo — para una fuente que tú proporcionaste, el nombre con respecto al cual tus propias plantillas proporcionadas renderizan sus recursos, como el nombre de la release que lee un chart; para un workload: que sintetiza, el nombre que da a esos recursos cuando los nombra según un nombre propio en lugar de la identidad, como hace helm. Presente solo donde ese proveedor deriva uno. En las plantillas propias de una vinculación de Feature es el nombre del componente host — consulta más abajo. |
La división se deriva de dónde tiene que ser utilizable el nombre. Un chart o un módulo que proporcionaste tú tiene plantillas, y esas plantillas nombran sus recursos según la identidad que la plataforma les entregue — así que el nombre tiene que ser el que esa plataforma usará, escrito en el alfabeto propio de esa plataforma. Un workload sintetizado no tiene plantillas tuyas, pero sus recursos aun así tienen que llevar nombres que la plataforma acepte: un proveedor cuyos nombres admiten todo lo que puede llevar un nombre escrito por el autor los nombra según la identidad, y uno cuyos nombres no lo admiten los nombra según el nombre que deriva — y luego informa ese nombre aquí, para que nunca tengas que predecirlo.
Un nodo que declara tanto una fuente proporcionada como un workload: emite ambos tipos de salida a la vez, y no necesita una tercera clave. Con helm ambos se nombran según el único nombre de la release, así que rendered_name sirve para cualquiera de los dos: los recursos propios del chart lo llevan como sea que sus plantillas lo compongan, y cada Service sintetizado es <rendered_name>-<service key>. Con un proveedor que nombra un workload sintetizado según la identidad, nombra los recursos de ese workload con instance_id y los de la salida proporcionada con lo que el proveedor informe para ella.
Los alfabetos son la razón por la que los dos pueden diferir. Un nombre de componente escrito por el autor puede llevar un guion bajo o una letra mayúscula; el nombre de la release de un chart no, y en lugar de reducir tal carácter a uno similar — lo que permitiría que dos componentes que sabes distinguir llegaran a un único nombre en un clúster — la derivación lo escribe de forma explícita. Consulta ../providers/helm.md «How the release name is derived (Cómo se deriva el nombre de la release)» para el alfabeto y el límite de longitud propios de ese proveedor.
Qué proveedores informan un nombre, y por qué los demás no
helm informa uno: el nombre de la release. Un chart proporcionado como fuente lo lee como .Release.Name y nombra habitualmente sus recursos según él, y el proveedor también nombra según él cada recurso que sintetiza para un componente — el controlador con el propio nombre de la release, y cada Service como <release name>-<service key>. Así que una dirección publicada para cualquiera de los dos tipos de salida se construye a partir de rendered_name. Para un nodo que coloca únicamente un conjunto de artefactos no informa ninguno: los nombres de ese conjunto son los que escribió su autor.
# 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"Un componente llamado cache publica cache-default, y uno llamado my_cache publica my-zucache-default — en cada caso, el nombre del Service que emite la compilación.
Los otros cuatro no informan ninguno, y las razones no son las mismas. Ninguno de ellos es un proveedor a la espera de soporte — en cada caso, o no hay ningún nombre derivado que informar, o el nombre que quieres ya es accesible de otra forma.
-
cloudformationycompose— tú escribiste los nombres, o la identidad es el nombre. Una Recipe de cloudformation escribe los identificadores lógicos de sus recursos y el proveedor los lee exactamente como están escritos; un archivo compose que proporcionaste nombra sus propios servicios y el proveedor fusiona y etiqueta ese archivo sin renombrar nada en él. Un workload quecomposesintetiza se nombra según la identidad del nodo, que un archivo compose admite tal como está escrita, así que{{ .context.instance_id }}es ese nombre. No hay ninguna derivación que informar, y los nombres son los que figuran en tus propios documentos. Ese nombre es el servicio principal del workload, el que alcanza un par; un servicio sidecar o de inicialización que lleve se nombra a partir de la misma identidad y del nombre del contenedor, unidos por--, como describe Cómo se nombra un servicio sidecar o de inicialización. -
terraform— el nombre depende de dónde se colocaron los archivos. El bloquemodulede un contribuyente se nombra a partir del directorio de salida en el que se escribió su configuración, que se fija cuando se ensamblan los archivos del límite y no cuando se renderiza un nodo. En el momento en que se ejecutan las plantillas de una Recipe, esa posición todavía no existe. -
helm-chart— el nombre que deriva es la dirección propia del chart colocado, que es algo distinto del nombre con respecto al cual renderizan las plantillas de ese chart. Este proveedor establece el camponamede un chart que incorporaste mediante vendoring en la identidad codificada de lo que lo aportó, que también es el alias con el que el umbrella vincula ese subchart y la clave bajo la que se acotan sus valores. Para un componente, esa identidad es lo que lleva{{ .context.instance_id }}, así que el nombre del chart colocado ya es accesible bajo la clave que dice lo que es. El nombre con respecto al cual renderizan las propias plantillas del chart incorporado es el nombre de la release, que la release del umbrella proporciona en el momento de la instalación en lugar de derivarlo este proveedor — así que aquí no hay ningún nombre de ese tipo que esta clave pueda informar. Consulta../providers/helm-chart.md«The chart name the umbrella owns (El nombre del chart que corresponde al chart paraguas)».
Leer la clave donde no se informa ningún nombre
Leer {{ .context.rendered_name }} en un nodo cuyo proveedor no informa ningún nombre de ese tipo detiene la compilación, y el diagnóstico indica qué clave escribir en su lugar. No renderiza un valor vacío: una dirección a la que le falta un segmento es un artefacto erróneo que se despliega, lo cual es peor que una compilación que se detiene.
Qué remedio ofrece la detención depende del nodo y no de dónde escribiste la referencia:
- Un nodo que no proporciona ninguna fuente propia, con un proveedor que no informa ningún nombre para él, tiene sus recursos nombrados según su identidad, así que la detención nombra
{{ .context.instance_id }}— hay un valor correcto y lo dice. - Un nodo que sí proporciona una fuente, con un proveedor que no deriva ningún nombre para él, no tiene sustituto. La detención lo dice en lugar de ofrecer uno, porque remitirte a la identidad ahí nombraría recursos que tu nodo no lleva.
El rechazo cubre provides: y cualquier otra plantilla que una Recipe escribe inline — su valuesMapping:, su cuerpo workload:, cada entrada artifacts:, y los with: y when: de cada paso de la pipeline.
🔴 Ambas formas de importación quedan fuera. Una entrada valuesMapping:, workload: o artifacts: proporcionada mediante $import: — tanto si la importación nombra un archivo local como una entrada de biblioteca — no lleva ningún texto en tu Recipe hasta que el renderizado la resuelve, así que una referencia a esta clave dentro de tal cuerpo no se comprueba. Renderiza el nombre que informa el proveedor del nodo importador donde ese proveedor informa uno, y un valor vacío en lugar de una detención donde no informa ninguno. Por tanto, un cuerpo importado lee la clave solo cuando cada Recipe que lo importa está asociada a un proveedor que informa un nombre — una entrada de biblioteca escrita para Recipes de helm que usan un chart como fuente, y que lo dice en su descripción. Un cuerpo pensado para importadores cuyo proveedor puede no informar ninguno toma en su lugar el nombre mediante un valor que establece la Recipe importadora.
Las entradas locals: de una Recipe no leen la clave en absoluto. Un local comparte su contexto con la plantilla source: de la Recipe, y si el nodo proporciona una fuente es una de las cosas de las que depende el nombre, así que el nombre no se ofrece ahí. Por tanto, una referencia a {{ .context.rendered_name }} en un local se detiene sea lo que sea que informe el proveedor, con el diagnóstico de una referencia que el contexto de renderizado no define (E0060), que enumera .context.instance_id como la única clave que .context ofrece ahí. Lee la clave en la entrada provides: o en la plantilla inline que la necesita.
En las plantillas propias de una vinculación de Feature
En las plantillas que escribe la FeatureRecipe de una vinculación de Feature — sus locals:, source:, provides:, injectMapping:, valuesMapping:, workload:, cada entrada artifacts:, y los with: y when: de cada paso de la pipeline — {{ .context.rendered_name }} es el nombre del componente host: el que el propio proveedor del host informa para los recursos que renderiza para el host, que es el valor que lee la propia Recipe del host. Forma pareja con {{ .context.instance_id }}, que en esas plantillas es la identidad del componente host; la vinculación en sí es .attachment_name. Una vinculación escrita en una de las conexiones de un componente lee el nombre del componente consumidor, porque ese componente es su host.
Esa es la clave a partir de la cual construir los nombres de los recursos propios de una vinculación. Una FeatureRecipe que nombra un Secret, una ruta o una política según el componente al que está vinculada necesita un nombre que la plataforma acepte, y la identidad del host tal como está escrita no lo es dondequiera que lleve un guion bajo o una letra mayúscula. Con helm, un componente llamado my_db informa my-zudb, así que un Secret llamado {{ .context.rendered_name }}-{{ .attachment_name }} para una vinculación root se renderiza como my-zudb-root, donde {{ .context.instance_id }} daría my_db-root, que un clúster rechaza. El valor sigue siendo el del host sea cual sea el proveedor a través del cual se renderiza la vinculación.
Está presente dondequiera que el proveedor del host informe un nombre — con helm, un host cuya Recipe proporciona un chart o declara un workload: — y ausente donde no informa ninguno: un host que coloca únicamente un conjunto de artefactos, y un host en cualquier otro proveedor. Leerla en una vinculación de tal host detiene la compilación con el diagnóstico de una referencia que el contexto de renderizado no define (E0060), que enumera las claves que .context define ahí. {{ .context.instance_id }} está entre ellas, y es según ella como se nombran los recursos propios del host en tal host, así que una FeatureRecipe escrita para hosts que pueden no informar ningún nombre lee en su lugar la identidad.
El rechazo cubre las plantillas que una FeatureRecipe escribe inline, salvo su injectMapping:. Un injectMapping:, y una entrada valuesMapping:, workload: o artifacts: que la FeatureRecipe proporciona mediante $import:, no se comprueban: en un host que no informa ningún nombre, una referencia ahí renderiza un valor vacío en lugar de detenerse.
Donde una vinculación entrega un chart proporcionado por su autor, las plantillas de ese chart renderizan con respecto al nombre de la release del componente host, deliberadamente: derivarlo en cambio de la vinculación renombraría recursos que el autor del chart declaró y que quizá ya haya desplegado. .attachment_name es el valor que distingue dos vinculaciones en un mismo host — consulta ../providers/helm.md «How the release name is derived (Cómo se deriva el nombre de la release)».
Nombres derivados de la vinculación de una conexión
Una vinculación que lleva una conexión es una vinculación del componente consumidor, con el nombre <alias>.<slot> — gpt.credential para el slot credential de la conexión escrita bajo el alias gpt (consulta la entrada de conexión del Aggregate). Ese nombre compuesto es el .attachment_name con respecto al cual renderiza su FeatureRecipe, y lleva el punto.
De él se derivan dos tipos de nombre, que tratan el punto de forma distinta.
Un nombre que compone la FeatureRecipe conserva lo que escriba su plantilla. Las realizaciones de credenciales de la biblioteca estándar nombran su recurso {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, así que la credencial en la conexión gpt de un componente llamado router se renderiza como un recurso llamado router-gpt.credential, punto incluido, que es un nombre de objeto de Kubernetes válido. El punto sobrevive en un nombre de este tipo exactamente cuando la plantilla lo conserva.
Un nombre que la compilación deriva de la identidad de la vinculación escribe el punto de forma explícita. Las etiquetas de identidad y el archivo emitido se componen a partir del componente host y del nombre de la vinculación mediante la misma codificación por la que pasa todo nombre derivado de una identidad, y esta escribe el punto como zd y una letra mayúscula como un escape de su punto de código, porque la identidad se usa como nombre de recurso además de como etiqueta, y un nombre de Service no admite ninguno de los dos: una conexión escrita bajo el alias gptPro llegaría a cfr--router--gpt-zx000050ro-zdcredential. El recurso anterior lleva la etiqueta aggrega.ai/component-id: cfr--router--gpt-zdcredential (y app.kubernetes.io/name igualmente), y con el proveedor helm se emite como router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Consulta Convenciones de nomenclatura «The separator does not reach a name (El separador no llega a un nombre)» para saber por qué el punto se escribe de forma explícita en lugar de sustituirse.
Temas relacionados
- Contrato del contexto de plantillas — la forma completa del contexto en el que se encuentran estas claves.
- Matriz de expansión de plantillas — qué pilares lee cada punto de plantilla.
- Tríada de topología:
provides,inject,uses— cómo un valor publicado cruza una arista hasta un consumidor. - Convenciones de nomenclatura — qué puedes escribir como nombre de componente, y qué cuesta un nombre con un alfabeto más restringido.
errors/fatal-halts.md— la detención que describe esta página, con el mensaje que emite.