Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Provider Helm

El proveedor helm produce YAML de Kubernetes renderizado plano para los consumidores de GitOps (ArgoCD, Flux). El proveedor ensambla por (path, provider): el YAML renderizado de cada nodo dirigido a helm se enruta al ensamblador indexado por el directory: evaluado del límite unido al subDirectory: de cada componente, y ese ensamblador emite un archivo YAML por cada recurso de Kubernetes. Las herramientas posteriores comparan y aplican los archivos directamente, sin un paso de instalación de Helm.

Donde el syncWave: <integer> del límite no es 0, cada recurso de Kubernetes emitido lo lleva como la anotación argocd.argoproj.io/sync-wave: "<N>"; los hooks de Helm llevan además helm.sh/hook-weight: "<N>". ArgoCD lee la anotación sync-wave, y Helm lee el peso de un hook, y cada uno ordena los recursos según ese valor; un límite en la oleada predeterminada 0 no lleva ninguno de los dos, lo que ambas herramientas leen como la oleada 0.

Esta página es la referencia de autoría del proveedor helm. Para el modelo de composición de entradas común a todos los proveedores, consulta architecture/16-recipe-input-composition.md. Para la disponibilidad de cada proveedor, consulta Estado del lenguaje → Providers.

Tipos de entrada admitidos

El proveedor helm acepta los tres tipos de entrada de la Recipe, en papeles distintos:

  • Modo con fuente. Una Recipe con source: <chart-path> apunta a un directorio de chart de Helm en disco. El SDK de Go de Helm carga el chart, el diccionario de valores del renderizado base se combina con los valores predeterminados del chart, y las plantillas del chart se renderizan a YAML de Kubernetes plano.
  • Modo Workload (sintetizado). Una Recipe con workload: (en línea o cargado con $import:) declara un documento Workload. El proveedor sintetiza uno o más recursos de Kubernetes por nodo — un objeto controlador elegido por el form del Workload, más Services por servicio y PVC por volumen persistente — directamente a partir de la especificación del Workload; consulta Modo Workload (sintetizado).
  • Modo solo artefactos. Una Recipe con artifacts: y sin source: ni workload: emite los manifiestos que escribió su autor, con las etiquetas y anotaciones de procedencia de la compilación insertadas en los propios metadatos de cada recurso.

Los tres se combinan: una Recipe puede declarar a la vez un chart, un Workload y artifacts:, y cada uno se renderiza y se emite por su cuenta, uno junto a otro en la salida del nodo — consulta Qué acepta cada provider, en detalle.

Conjunto de claves de source:

El source: del proveedor helm nombra un chart, y acepta las dos formas que adopta el campo source:: una cadena simple de ruta del sistema de archivos y un objeto estructurado cuyo url: lleva la ubicación. Siempre que esa ubicación sea una ruta del sistema de archivos, se ancla al directorio que contiene el recipe.yaml que la declara, no al directorio desde el que se invoca la compilación, y debe permanecer dentro de ese directorio: una que salga de él, o una absoluta, se rechaza, porque cada archivo que lleva una publicación de la Recipe se toma de su directorio — consulta entities/recipe.md «Content paths stay inside the Recipe’s own directory (Las rutas de contenido permanecen dentro del propio directorio de la Recipe)». Un chart nombrado así se publica con la Recipe, con cada archivo que contiene que conservan las reglas de exclusión registradas cuando se fijó la Recipe — el proveedor helm deja fuera los directorios de control de versiones y los archivos ocultos bajo el templates/ del chart, respeta el propio .helmignore del chart, y el .aggregaignore del autor tiene la última palabra, como describe Qué archivos se distribuyen con una entidad — mientras que un archivo junto a la Recipe que nada de lo que declara nombra no se publica. El renderizado lee los mismos archivos que lleva la publicación, así que un chart se renderiza igual desde tu directorio y desde un registro. La forma en que lo escribiste no cambia eso: un source: estructurado cuyo url: es ./charts/api-server se ancla exactamente igual que la cadena simple ./charts/api-server.

spec:
capability: helm
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicas: {{ optional .infra `replicas` 2 }}

Un source: estructurado dice lo mismo con campos con nombre, y lo que lleva su url: decide si se obtiene algo. Donde url: lleva un esquema de transporte — oci://… para un chart OCI, un https://….tgz para un archivo de chart directo, o una raíz de repositorio https:// combinada con chart: — el chart se obtiene: el tipo procede del esquema de la URL o de un kind: explícito, aggrega pull obtiene y fija el chart en el lockfile, y la compilación lo extrae de la caché. Donde url: nombra una ruta del sistema de archivos, no se obtiene ni se fija nada — el chart se lee del disco, anclado exactamente como la forma de cadena simple de arriba.

spec:
capability: helm
source:
kind: helm-oci-chart
url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned
version: "1.0.0"

Solo url: decide de dónde se lee un chart. Los demás campos seleccionan lo que se obtendría, así que para una ruta no seleccionan nada — siguen llegando a las propias plantillas de la Recipe como .source.*.

Copiar un chart localmente (vendoring) se admite como alternativa a obtenerlo, y no es obligatorio. El esquema acepta un objeto estructurado abierto.

El chart en la ruta de origen debe contener un Chart.yaml válido. Los renderizados con fuente que no consiguen cargar el chart muestran literalmente el error subyacente del SDK de Helm. Un source: "" vacío no es un asunto de helm: no nombra ni el modo sin fuente ni el modo con fuente, así que el rechazo que recibe es el mismo sea cual sea el proveedor al que apunte la Recipe, y llega al leerse la Recipe, antes de que se cargue ningún chart y antes del despacho a este proveedor. Qué comandos informan de él se expone en entities/recipe.md «Source field scheme inventory (Inventario de esquemas del campo source)» y en errors/fatal-halts.md «Recipe source: is an empty string (El campo source de la Recipe es una cadena vacía)».

Modo con fuente

Una Recipe con source: <chart-path> y valuesMapping: ejecuta el siguiente pipeline en el renderizado base:

  1. El chart en <chart-path> se carga mediante el SDK de Go de Helm.
  2. La plantilla valuesMapping se evalúa en el contexto de plantilla de la Recipe. Su salida YAML se trata como una superposición de valores para el chart.
  3. La superposición se combina una sola vez con los valores predeterminados del values.yaml del chart; en caso de colisión prevalecen las claves de la superposición (la semántica estándar de helm install --values de Helm). Una clave que la superposición establece en null elimina el valor predeterminado del chart para ella — en el nivel superior, dentro de una tabla o en los valores de una dependencia — como hace helm install --values, de modo que las plantillas del chart leen la clave como ausente; un null en una clave a la que el chart no da ningún valor predeterminado llega a las plantillas como null.
  4. El SDK de Helm renderiza las plantillas del chart con los valores combinados.
  5. Aggrega inyecta sus metadatos de procedencia en los manifiestos renderizados mediante una reescritura de YAML posterior al renderizado, lo que garantiza que la salida con fuente lleve el mismo etiquetado que la salida del modo Workload. Los valores de identidad se convierten en etiquetas (app.kubernetes.io/name, aggrega.ai/component-id, aggrega.ai/provider, aggrega.ai/provider-version, aggrega.ai/environment y — cuando están establecidos — aggrega.ai/aggregate-name, aggrega.ai/compiler-version), cada una escrita en una forma que Kubernetes acepta como valor de etiqueta; los valores que una etiqueta de Kubernetes no puede representar se convierten en anotaciones (aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave donde la oleada no es 0, y el valor literal de cualquier etiqueta cuyo valor tuvo que reescribirse — un Aggregate llamado imported/flow recibe la etiqueta imported-flow y la anotación imported/flow bajo la misma clave). La regla de reescritura se enuncia en well-known-annotations.md «Etiquetas de procedencia emitidas por los proveedores».
  6. Los archivos de salida quedan planos en el directorio de salida de la Recipe, uno por cada recurso renderizado, con el nombre <name-basis>-<kind>[-<namespace>]-<name>.yaml — la misma base de la que se deriva el nombre de release que se describe más abajo, seguida del tipo propio del recurso, su espacio de nombres cuando lo tiene, y su nombre, cada uno en minúsculas y con cada secuencia de otros caracteres reducida a un solo guion. Para un componente ordinario esa base es la identidad propia del componente, que es también lo que lleva la etiqueta aggrega.ai/component-id del recurso; para un chart que aportó el autor de una vinculación de Feature sigue siendo la del componente anfitrión, mientras que la etiqueta lleva la identidad propia de la vinculación. Un documento que no lleva tipo o nombre recibe en su lugar el nombre de la ruta de su plantilla. La estructura de directorios del chart se aplana: no hay ningún subdirectorio templates/ en la salida renderizada, y dos plantillas en subdirectorios distintos que comparten un nombre de archivo siguen siendo dos archivos, porque el nombre procede del recurso y no de la plantilla. Un archivo que nombra el bloque artifacts: de la Recipe no queda aquí: está un directorio más abajo, bajo un directorio con el nombre del componente que lo declaró, porque un archivo así recibe el nombre de la clave que escribió su autor y no del recurso que lleva — de modo que, sin ese directorio, dos componentes enlazados a una misma Recipe escribirían una única ruta, sin que ninguno de los dos autores pudiera separarlos.

El espacio de nombres para el que se renderiza el chart se lee de la anotación aggrega.ai/namespace que desciende en cascada desde el límite y llega al chart como el espacio de nombres de su release; cuando ningún límite declara uno, el chart se renderiza para default. Donde un límite declara uno, cada recurso con espacio de nombres que el chart renderiza sin espacio de nombres — sin metadata.namespace, o con uno escrito vacío o null — se emite en el espacio de nombres declarado, que es donde lo coloca la instalación del chart con Helm bajo ese espacio de nombres de la release, y su archivo se nombra con el segmento del espacio de nombres exactamente igual que un recurso cuya plantilla escribe el campo. Un recurso cuya plantilla escribe un espacio de nombres lo conserva, sea cual sea el espacio de nombres que nombre. Un recurso de ámbito de clúster queda sin espacio de nombres. Si un tipo tiene espacio de nombres lo determina el ámbito propio de la API de Kubernetes para un tipo que la API sirve por sí misma y, para un tipo personalizado, el scope que una CustomResourceDefinition del mismo renderizado declara para él — desde las plantillas del chart o desde su directorio crds/. Un recurso de un tipo que ninguno de los dos clasifica se deja tal como lo escribió el chart, y la compilación lo informa, una vez por tipo, nombrando el tipo y su grupo de API; lo mismo ocurre con un documento kind: List, cuyos elementos no se colocan. Donde ningún límite declara un espacio de nombres, no se coloca nada y no se informa nada: un recurso que el chart escribe sin espacio de nombres se emite sin él, colocado por lo que seleccione la herramienta que lo aplica.

El informe es una advertencia en la compilación, que aun así se completa:

warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places them

Donde el chart tiene un valor que renderiza la CustomResourceDefinition del tipo, o uno que escribe el propio espacio de nombres, establecerlo mediante el valuesMapping de la Recipe coloca dicho recurso.

La versión de Kubernetes para la que se renderiza un chart

Las plantillas de un chart leen la versión de Kubernetes para la que se renderizan como .Capabilities.KubeVersion, y muchas eligen según ella una versión de API, un campo o un mecanismo entero — un token de cuenta de servicio proyectado a partir de la 1.21, por ejemplo, y uno de primera parte por debajo. La compilación no tiene ningún clúster al que preguntar, así que la versión es una que indicas tú, donde la Release dice dónde se despliega un componente: la anotación aggrega.ai/kubernetes-version en un límite, o en un componente, donde prevalece sobre la de su límite, en cascada exactamente igual que aggrega.ai/namespace.

spec:
boundaries:
production:
annotations:
aggrega.ai/kubernetes-version: "1.31"
components:
api: {}
legacy:
annotations:
aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older cluster

El valor se lee del mismo modo en que helm template --kube-version lee su flag, así que acepta las formas que acepta ese flag y un chart lee exactamente lo que ese flag le daría: "1.31" se lee como v1.31, "v1.31.2" como v1.31.2, y el texto que sigue a los números permanece en .Capabilities.KubeVersion.Version tal como está escrito — "1.29.3-gke.100" se lee como v1.29.3-gke.100 — mientras que .Capabilities.KubeVersion impreso entero lee la versión sin él. Un chart que compara .Capabilities.KubeVersion.Version con semverCompare lee ese sufijo como una versión preliminar, de modo que una restricción sin un mínimo -0, como ">=1.21", no coincide con ella, y un valor con espacios alrededor se lee con esos espacios — " 1.30 " se lee como "v 1.30 " — y falla por completo esa comparación: escribe la versión sin más donde un chart la compare. Un valor que no es una versión — "one.two", "latest", un solo número — detiene la compilación con la condición de un valor que un plugin no puede representar, nombrando el valor, el componente y su límite; el chart nunca se renderiza para otra versión en su lugar. Consulta A Kubernetes version the helm provider cannot render a chart for (Una versión de Kubernetes para la que el proveedor helm no puede renderizar un chart). Un valor vacío se trata como no establecido.

Donde ninguna anotación nombra una versión, un chart se renderiza para la versión para la que renderiza el helm template estándar de la misma release de helm, que es la versión de la biblioteca cliente de Kubernetes con la que está construido el proveedor: un proveedor construido con la biblioteca cliente v0.37 renderiza para Kubernetes v1.37.0. Así, un chart se renderiza en Aggrega como lo renderiza el helm template de sus propios autores, y el valor predeterminado solo cambia cuando cambia la biblioteca cliente con la que está construido el proveedor. Indica la versión del clúster en el que despliegas siempre que difiera: un chart renderizado para una versión más reciente que la que ejecuta el clúster puede emitir una versión de API que ese clúster no sirve.

Solo la versión se establece de este modo. Cualquier otra capacidad que lee un chart — .Capabilities.APIVersions y .Capabilities.HelmVersion — es la integrada en la biblioteca helm, así que una API que un clúster sirve a partir de una CustomResourceDefinition instalada no se comunica al chart. El rango kubeVersion propio de un chart en su Chart.yaml no se compara con la versión: helm template rechaza un chart cuyo rango excluye la versión para la que renderiza, y la compilación lo renderiza. La anotación determina un chart renderizado desde una fuente y nada más: un Workload sintetizado y un cuerpo artifacts: no leen .Capabilities, y el proveedor helm-chart entrega su chart sin renderizar, para que se renderice cuando se instale.

Dejar fuera documentos renderizados. Este proveedor respeta las entradas omits: que declara una Recipe o una FeatureRecipe, en este modo y en ningún otro: un Workload sintetizado y un cuerpo artifacts: se renderizan sin ellas. Cada documento que renderiza el chart — desde una plantilla o desde un archivo de su directorio crds/ — se compara con cada entrada que se aplica a la compilación, y un documento que nombra cualquier entrada se deja fuera. Una entrada nombra un documento por las palabras que lleva el propio documento, las mismas palabras con las que se construyen su nombre de archivo de salida y sus hechos de renderizado: su kind, su metadata.name y, solo donde la entrada nombra uno, el espacio de nombres en el que está el documento — el que escribe su plantilla, o el espacio de nombres declarado del límite donde este proveedor coloca el documento como se describe arriba. Nunca es el espacio de nombres para el que el chart simplemente se renderiza: sin ningún espacio de nombres declarado el chart se renderiza para default, pero un documento cuya plantilla no escribe ningún espacio de nombres no está en ninguno, así que una entrada que nombra default no coincide con él. Un documento que no lleva tipo o nombre no coincide con ninguna entrada. Los documentos que se dejan fuera se renderizan y luego se descartan una vez fijado el nombre de cada archivo, de modo que cada documento conservado se nombra y se escribe exactamente como se haría sin las entradas, y un documento que se deja fuera no llega a nada de lo que hace la compilación después — ningún archivo, ningún nombre en la comparación que rechaza dos contribuidores que llegan al mismo nombre, ningún hecho de renderizado que lea una Feature, nada que se entregue a un paso del pipeline. El proveedor informa de cuántos documentos coincidieron con cada entrada, y una entrada con la que no coincidió ninguno detiene la compilación; consulta An omits entry left out nothing the source rendered (Una entrada omits no dejó fuera nada de lo que renderizó la fuente).

La release de Helm bajo la que se renderiza un chart

El proveedor renderiza con el SDK de Helm 4, en la v4.3, así que un chart lee lo que le da el propio helm template de Helm 4, y el mismo chart con los mismos valores renderiza los mismos bytes en cada compilación. Un chart escrito y comprobado con Helm 3 puede observar estos comportamientos de Helm 4:

  • .Capabilities.HelmVersion informa de la versión de Helm 4, v4.3.
  • La versión predeterminada de Kubernetes es v1.37.0, porque Helm 4 en la v4.3 está construido con la biblioteca cliente v0.37, y .Capabilities.APIVersions es el conjunto de versiones de API de esa biblioteca cliente. Indica la versión que ejecuta tu clúster, como describe La versión de Kubernetes para la que se renderiza un chart.
  • Un valor predeterminado null del chart se descarta. Una clave que el values.yaml del chart establece en null — en el nivel superior o dentro de una tabla — está ausente de .Values a menos que la establezcan los valores que aporta la Recipe, así que hasKey la indica como ausente, toYaml la omite y el values.schema.json del chart se comprueba con los valores sin ella.
  • Un escalar de bloque conserva su salto de línea final antes de ---. Un documento que termina en un escalar de bloque y va seguido de otro documento de la misma plantilla conserva el último salto de línea de ese escalar, de modo que se escribe | en lugar de |-.
  • .Chart es un mapa indexado por nombre de campo. .Chart.Name, .Chart.Version, .Chart.AppVersion y los demás campos se leen como antes, pero toYaml .Chart o toJson .Chart.Maintainers imprimen las claves como Name, AppVersion, etc., con los campos vacíos presentes, y un campo que los metadatos del chart no llevan se lee como vacío en lugar de hacer fallar el renderizado.
  • .Capabilities.KubeVersion.Version conserva el texto de una versión tal como está escrito, como se describe arriba para la anotación aggrega.ai/kubernetes-version.
  • Un values.yaml que contiene varios documentos YAML se lee entero, y los documentos posteriores se combinan sobre los anteriores.
  • .Files.Lines de un archivo vacío no devuelve ninguna línea en lugar de hacer fallar el renderizado.
  • Las funciones de plantilla añadidas por Helm 4 — mustToYaml, mustToJson, mustToToml, mustToDuration y las conversiones duration… — están disponibles para las plantillas de un chart.
  • Una dependencia con dos alias da a cada alias su propia copia de las dependencias de esa dependencia.
  • La validación del esquema de valores acepta o rechaza de forma distinta solo en los extremos: una parte local de correo electrónico entre comillas, NaN y los números infinitos, un número comparado con algo que no es un número en enum y const, y la ubicación indicada para un propertyNames, un contentSchema o un elemento posterior de un array que falla.

Una plantilla que el propio motor no consigue ejecutar — un valor leído a través de una tabla inexistente, por ejemplo — se informa en la forma de Helm 4: el archivo, la línea y la columna de la plantilla en una línea propia, después lo que se estaba ejecutando y el mensaje, con sangría, por cada plantilla por la que pasó el fallo. El fail o el required propios de un chart conservan su forma de una línea execution error at (<file>:<line>:<col>): <message>, igual que un error que devuelve una función de plantilla.

Cómo se deriva el nombre de la release

Un chart con fuente se renderiza con un nombre de release, que llega a cada plantilla como .Release.Name. Los charts suelen nombrar recursos a partir de él, así que un nombre de release es una identidad dentro del clúster y no una etiqueta de la compilación.

El nombre de la release es la forma codificada de la misma base con la que se prefija el nombre del archivo de salida del recurso renderizado, así que los dos son un mismo nombre escrito dos veces. Esa base es un instance_id para un componente ordinario, y la identidad compuesta que lleva una Feature vinculada a un límite. Para un chart que aportó el autor de una vinculación de Feature, es el nombre del componente anfitrión: las propias plantillas del chart se renderizan con el nombre de la release, así que derivarlo en cambio de la vinculación renombraría recursos que el chart declara, en un clúster donde ya están desplegados. Esos recursos siguen llevando la propia identidad de la vinculación en su etiqueta aggrega.ai/component-id — cómo se llama un recurso y a qué pertenece son aquí cuestiones separadas, y solo para un componente ordinario tienen la misma respuesta. Un nombre de release de Helm acepta un conjunto de caracteres más reducido que el que puede llevar una identidad: letras minúsculas, dígitos, guiones y puntos, empezando y terminando con una letra minúscula o un dígito, hasta 53 caracteres. En lugar de sustituir un carácter que el destino no acepta, la derivación lo escribe explícitamente, de modo que dos identidades de componente que solo difieren en la puntuación o en mayúsculas y minúsculas siempre llegan a dos nombres de release.

  • Una letra minúscula y un dígito se conservan exactamente como se escribieron.
  • Un guion se mantiene tal como se escribió siempre que el carácter que lo sigue se conserve directamente y no sea una z minúscula. Un guion seguido de una z minúscula abre una secuencia de escape, así que uno escrito en esa posición se escribe a su vez explícitamente — api-zone se convierte en api-zhzone, que es lo que permite leer de vuelta cualquier nombre sin adivinar. Un guion sin nada detrás se escribe explícitamente por la misma razón, así que db- da db-zh.
  • Cualquier otro carácter se escribe como -z seguido de una letra que lo nombra: d para un punto, u para un guion bajo, s para un separador de ruta, h para un guion que la regla anterior no conserva. Cualquier otra cosa — incluida una letra mayúscula — se escribe como x y el punto de código hexadecimal de seis dígitos del carácter, y un byte que no comienza ningún carácter como b y su propio valor de dos dígitos.
  • Un valor vacío se escribe -ze, que ningún valor no vacío puede producir.

Un punto se escribe explícitamente en lugar de conservarse, aunque Helm acepta uno en un nombre de release, porque Helm exige una letra minúscula o un dígito a cada lado de un punto y la derivación coloca guiones propios.

Como dos Features vinculadas a un mismo componente se renderizan ambas con el nombre de la release de ese componente, dos charts que nombran cada uno un recurso a partir de .Release.Name emiten dos recursos con un mismo nombre. Este proveedor informa del nombre que lleva cada recurso que produce su propio renderizado, acotado al tipo de ese recurso y, para un tipo que el clúster mantiene en un espacio de nombres, a su espacio de nombres, y la compilación rechaza dos contribuidores que llegan a uno de esos nombres en lugar de emitir una salida en la que aplicar ambos deja solo el último — consulta ../errors/fatal-halts.md «The same name is derived more than once inside the output (El mismo nombre se deriva más de una vez dentro de la salida)». Un tipo que el clúster mantiene fuera de todo espacio de nombres — un ClusterRole, una CustomResourceDefinition, o un tipo personalizado que una CustomResourceDefinition del mismo renderizado declara con el ámbito Cluster — se acota solo a su tipo, clasificado exactamente como lo clasifica la ubicación en espacios de nombres descrita arriba, así que dos componentes de una misma salida que escriben cada uno un objeto así con un mismo nombre se rechazan incluso donde la Release los coloca en espacios de nombres distintos. La solución es componer el nombre, y qué coordenada necesita depende de la disposición. Dos vinculaciones sobre un mismo componente ya comparten el anfitrión, así que es la vinculación la que tiene que llegar a la plantilla: pasa .attachment_name al chart mediante el valuesMapping: de la FeatureRecipe y asígnalo a aquel de los valores propios del chart a partir del cual se construyen los nombres de sus recursos. Un mismo chart vinculado a dos componentes es el caso contrario — el nombre de la release ya difiere por anfitrión, así que un recurso nombrado a partir de .Release.Name lleva un nombre propio en cada uno de ellos, mientras que un nombre literal no. Una FeatureRecipe que entrega sus recursos mediante artifacts: se informa en los mismos términos: este proveedor lee el nombre que lleva cada documento emitido, tanto si ese documento procede de una plantilla de chart como de un cuerpo de artefactos, así que un nombre literal en un cuerpo así vinculado a dos componentes también detiene la compilación. Un cuerpo de artefactos es una plantilla, así que compón el nombre a partir de .context.rendered_name — el nombre de la release del anfitrión, que difiere por anfitrión y se escribe con los caracteres que admite un nombre de Kubernetes — y de .attachment_name donde tenga que ser distinto por anfitrión; en un anfitrión que coloca un conjunto de artefactos por sí solo, que no informa de ningún nombre de release, compónlo en cambio a partir de .context.instance_id. No se informa de todos los nombres, así que una compilación que no se detiene no ha comparado todo lo que su salida llevará finalmente. El que es más probable que encuentres al escribir un chart es un recurso que declara generateName, cuyo nombre se deja que complete el clúster y que, por tanto, aún no tiene nada que comparar. La página enlazada arriba recoge el conjunto completo.

Así, un instance_id api da el nombre de release api, data.main-db da data-zdmain-db, y db_host da db-zuhost. Una identidad formada solo por letras minúsculas, dígitos y guiones que la derivación conserva aparece exactamente como se escribió. Una entrada idéntica siempre produce el nombre idéntico.

Dos de las condiciones de Helm son propiedades de la base y no de la derivación: un nombre de release tiene que empezar con una letra minúscula o un dígito, y tiene que tener como máximo 53 caracteres. Una base cuyo primer carácter se escribe explícitamente empieza su nombre con el guion con el que se abre toda secuencia de escape, y una que lleva caracteres que se escriben explícitamente queda, una vez codificada, más larga de lo que se escribió. La compilación consulta a este proveedor sobre ambas, y actúa según la respuesta en tiempo de compilación en lugar de dejar el rechazo al clúster en el momento de aplicar — consulta ../errors/fatal-halts.md «The target will not accept a name derived from an authored identity (El destino no acepta un nombre derivado de una identidad escrita)». Lo que hace con la respuesta depende de quién escribió la base. Un nombre que escribiste tú se rechaza en lugar de alterarse, y el rechazo nombra el campo que escribiste y el margen del que dispones; un nombre que compuso Aggrega se acorta hasta que este proveedor lo acepta.

El clúster somete los recursos nombrados a partir de un componente a una regla más estricta que las de Helm: el nombre de un Service tiene que empezar con una letra, mientras que un nombre de release puede empezar con un dígito. Un chart suele nombrar sus Services a partir del nombre de la release, y los Services de una carga de trabajo sintetizada también empiezan con él, así que este proveedor también rechaza un nombre de componente que empiece con un dígito, e informa de él como un Service name que el destino no puede usar. Ninguna longitud arregla un primer carácter, así que ese rechazo no indica ninguna. Por tanto, empieza un instance_id con una letra minúscula, y mantenlo lo bastante corto como para que su forma codificada siga cabiendo.

Cambiar la base de la que se deriva un nombre de release renombra los recursos del clúster que un chart nombra a partir de .Release.Name, y cada recurso que este proveedor sintetiza para el componente, y Kubernetes no renombra un recurso en su lugar. La herramienta que aplica la salida crea el recurso con su nuevo nombre y elimina el que tiene el nombre antiguo, lo que, para los recursos con estado, significa que se libera el almacenamiento asociado al nombre antiguo. Trata un cambio así como un reemplazo que hay que planificar — con drenaje, migración o una ventana programada — y no como una actualización que desplegar.

Modo Workload (sintetizado)

Una Recipe con workload: (en línea o cargado con $import:) sintetiza recursos de Kubernetes a partir de la intención abstracta del Workload. El esquema del Workload se documenta en entities/workload.md; esta sección cubre lo que emite el proveedor helm.

Para cada nodo:

  • Un objeto controlador elegido por el form del Workload: stateless (y el valor predeterminado) emite un Deployment, stateful un StatefulSet, daemon un DaemonSet, task un Job, scheduled un CronJob cuyo spec.schedule es el campo schedule del Workload (una expresión cron de 5 campos o una macro @); una carga de trabajo scheduled sin programación, o con una mal formada, detiene la compilación de forma explícita. Una carga de trabajo scheduled que declara suspend: true emite su CronJob con spec.suspend: true, de modo que no se inicia ninguna ejecución a partir de la programación hasta que se reanude, mientras que aún se puede crear un Job a mano a partir del CronJob; una que no lo declara no emite ninguna clave suspend. El Deployment y el StatefulSet llevan el número de réplicas; DaemonSet, Job y CronJob no llevan ninguno. Un Workload stateful requiere exactamente un Service type: Headless declarado en el Workload para gobernar el StatefulSet; el proveedor conecta el serviceName del StatefulSet con el nombre renderizado de ese Service, y la compilación se detiene si no se declara ningún Service headless (o si se declara más de uno). Un volumen persistentTemplate es un complemento de form: stateful — declarar uno en cualquier otra forma detiene la compilación con un mensaje que nombra la corrección.
  • Un Service por cada entrada services: declarada en el Workload, que expone los puertos con nombre que enumera la especificación del servicio. El type de la entrada se convierte en el tipo del Service — ClusterIP, NodePort y LoadBalancer tal cual, y Headless como un Service ClusterIP con clusterIP: None. Una entrada Loopback detiene en cambio la compilación, nombrando el nodo y el servicio: un Service de Kubernetes no tiene ningún tipo que se asocie a la dirección de loopback de un host, y en qué direcciones de nodo escucha un Service NodePort es un ajuste de todo el clúster, así que la entrada se rechaza en lugar de renderizarse con un alcance que no pidió. Consulta A service type the helm provider cannot render (Un tipo de servicio que el proveedor helm no puede renderizar).
  • Un PersistentVolumeClaim por cada volumen persistent, dimensionado y configurado a partir de la especificación del volumen. Un volumen persistentTemplate no emite ninguna claim independiente: se convierte en una entrada volumeClaimTemplates dentro de la propia especificación del StatefulSet, que es por lo que es un complemento de form: stateful.

Nombres de los recursos. Cada recurso que este modo emite para un componente se nombra a partir del nombre de la release del componente — el mismo nombre con el que se renderiza un chart con fuente, derivado como expone Cómo se deriva el nombre de la release — y el proveedor informa de ese nombre a la compilación como {{ .context.rendered_name }}. El objeto controlador lleva el propio nombre de la release; cada Service es <release name>-<service key>; cada claim independiente es <release name>-<volume>, y el volumen del pod hace referencia exactamente a esa claim; un secret entregado como archivo se monta desde un volumen del pod llamado <release name>-secret-<slot>, con el slot escrito en el alfabeto que acepta el clúster, igual que el nombre de la release — así, un slot server_certificate se monta desde <release name>-secret-server-zucertificate, y un slot leído a través de una conexión tiene el punto que sigue al nombre de la conexión escrito de la misma manera; el serviceName de un StatefulSet es el nombre del Service headless que emite; y un Workload expuesto solo mediante un nombre externo emite un único Service que lleva el nombre de la release. Así, un componente api emite un Deployment api y un Service default api-default, y un componente my_api emite my-zuapi y my-zuapi-default — nombres que el clúster acepta, donde la identidad tal como está escrita no lo sería. Una Recipe que publica la dirección de uno de esos Services la construye a partir de {{ .context.rendered_name }}, como muestra ../templates/rendered-resource-names.md; para un componente cuyo nombre no lleva guion bajo ni letra mayúscula, el nombre de la release es igual a su instance_id, así que sus nombres se leen exactamente como la identidad. Una carga de trabajo que sintetiza una vinculación de Feature es la única excepción: se nombra a partir de la propia identidad compuesta de la vinculación — el valor que lleva su etiqueta aggrega.ai/component-id — porque la vinculación se renderiza con su componente anfitrión, y un nombre de release derivado allí nombraría la carga de trabajo de la vinculación a partir del anfitrión y colisionaría con la propia del anfitrión. Esa identidad nunca lleva una letra mayúscula: una mayúscula en el nombre del anfitrión o en el de la vinculación se escribe explícitamente como secuencia de escape, como cualquier otro carácter que rechaza un nombre de recurso, así que una vinculación worker en un componente myApi emite un Deployment cfr--my-zx000041pi--worker y un Service default cfr--my-zx000041pi--worker-default, y cada nombre que lleva la carga de trabajo es uno que el clúster acepta.

Longitudes de nombre que dependen del Workload. El clúster somete dos de estos nombres a límites propios, y la compilación comprueba ambos una vez resuelto el Workload en lugar de dejar el rechazo al clúster en el momento de aplicarlo. El nombre de un CronJob tiene como máximo 52 caracteres, menos que los demás nombres del clúster porque el controlador nombra el Job de cada ejecución a partir del CronJob con un sufijo añadido; solo se comprueba para un Workload scheduled. El nombre de cada Service, <release name>-<service key>, tiene como máximo 63 caracteres. Superado cualquiera de los dos límites, lo que ocurre depende de quién escribió el nombre, exactamente como con el nombre de release: un nombre de componente que escribiste se rechaza, y la compilación se detiene en la clave spec.components que escribiste indicando el tipo de nombre, su longitud y el margen de caracteres del que dispone tu nombre — consulta ../errors/fatal-halts.md «The target will not accept a name derived from an authored identity (El destino no acepta un nombre derivado de una identidad escrita por el autor)»; una identidad compuesta, como aquella a partir de la cual se nombra el workload de una vinculación de Feature, se acorta hasta que todos los nombres caben. El nombre de un Service se construye a partir de tu nombre de componente y de una clave que declara el workload — en la Recipe o en una FeatureRecipe —, así que un rechazo nombra esa clave y el lugar donde el workload la declara, spec.workload.services.<key>; una clave que no deja sitio a ningún nombre de componente tiene que acortarse ella misma. Así, un componente que lleva un Workload scheduled puede tener un nombre codificado de hasta 52 caracteres, y un componente web puede llevar claves de Service de hasta 59. Una Feature vinculada a una frontera entera tiene su identidad fijada antes de que se resuelva su Workload, porque el lugar donde se ensambla su salida puede depender de esa identidad, así que no se comprueba ninguno de los dos límites para los recursos que sintetiza.

Cada recurso emitido lleva el conjunto completo de etiquetas y anotaciones de procedencia de Aggrega más un par de selectores (app: <instance_id>) conectado entre el Deployment/StatefulSet y sus Services. Un valor de etiqueta admite la identidad tal como está escrita, así que el selector la conserva mientras que los nombres anteriores toman el nombre de la release. Los nombres de los contenedores en el Deployment renderizado son las claves de contenedor del Workload con los caracteres . y _ sustituidos por - (saneamiento de nombres de Kubernetes).

Transporte de puertos. Un puerto de contenedor que declara un transporte lo emite tal cual como protocol: en el containerPort renderizado, y cada puerto de Service que nombra ese puerto de contenedor lleva el mismo valor — el transporte se declara una sola vez, en el puerto de contenedor, así que la exposición no puede discrepar de él. Un puerto que no declara ningún transporte no emite ninguna clave protocol en ninguno de los dos recursos, y deja en vigor el valor predeterminado del clúster. Los tres valores que admite el Workload (TCP, UDP, SCTP) se emiten tal cual; helm no necesita ninguna degradación, ya que Kubernetes expresa cada uno de ellos directamente.

Ejecución en la red del nodo. Un Workload que declara hostNetwork: true emite hostNetwork: true en la especificación del pod renderizada, de modo que el pod se ejecuta en el propio espacio de nombres de red del nodo y los puertos que abren sus contenedores son accesibles en las direcciones del nodo. Kubernetes expresa la elección directamente, así que no se degrada nada. La declaración llega a la especificación del pod y a nada más: no añade, elimina ni reescribe ningún puerto, y los Services emitidos son idénticos con ella y sin ella. Un Workload que no la declara no emite ninguna clave hostNetwork.

Cantidades de recursos. Cada cantidad que el proveedor copia en los manifiestos se emite tal cual, y cada una se comprueba primero frente a la forma de cantidad expuesta en Workload → Cantidades de recursos: los valores resources.requests y resources.limits de cada contenedor y de cada contenedor de inicialización — cpu, memory y cada recurso extendido como nvidia.com/gpu — y ephemeral.sizeLimit, persistent.size y persistentTemplate.size de cada volumen. La comprobación se ejecuta sobre el Workload tal como lo evaluaron las plantillas de la Recipe, así que un valor que llegó mediante infra o un parámetro de la Release se juzga por aquello en lo que se renderizó. Un valor fuera de la forma detiene la compilación con un error TRANSLATION_ERROR que nombra el nodo, la ruta del campo en el Workload y el valor — por ejemplo containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number — donde, de otro modo, el chart se compilaría sin errores y el clúster lo rechazaría en la instalación. Un cpu, memory o sizeLimit que se deja vacío se omite de los manifiestos y por tanto no se comprueba; un valor de recurso extendido o un tamaño persistente que se deja vacío se emitiría de todos modos, así que se rechaza. La comprobación solo juzga la forma: si el clúster puede programar la cantidad no es algo que el proveedor pueda saber en tiempo de compilación.

La denominación de los archivos de salida tiene dos formas. El objeto controlador se nombra a partir del nombre de la release y su tipo — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. Un archivo por recurso se nombra a partir del recurso que lleva, con el tipo al final: <release name>-<svcName>-service.yaml y <release name>-<volName>-pvc.yaml, cada uno tomado del propio metadata.name de ese recurso según la convención de nombres sintetizados de entities/workload.md. Un Workload expuesto solo mediante un nombre externo emite <release name>-service.yaml, al no haber ninguna clave de servicio que llevar.

Hechos de renderizado

Además de los archivos que renderiza, este proveedor informa de cuatro hechos de renderizado sobre cada nodo: lo que los documentos de Kubernetes que emitió dicen de sus pods, sus selectores, sus puertos y el espacio de nombres en el que se emite cada uno. Una FeatureRecipe vinculada al componente lee los propios hechos del componente en .context.render_facts; una que establece readsCallerRenderFacts: true lee además, en cada entrada de .context.used_by, los hechos de un componente que se conecta a su anfitrión, y una que establece readsTargetRenderFacts: true lee, en cada entrada de .context.uses, los hechos de un componente al que está conectado su anfitrión. Así es como una Feature puede nombrar los pods de los componentes que llaman a su anfitrión, o de los componentes a los que llega su anfitrión — una política de red que admita exactamente esos, por ejemplo — a partir de lo que sus renderizados emitieron realmente, sin que nadie repita una etiqueta a mano. Los nombres y las entradas de abajo son el contrato de este proveedor.

HechoUna entrada porCada entrada lleva
pod_template_labelsplantilla de pod emitida: la spec.template de un Deployment, StatefulSet, DaemonSet, ReplicaSet o Job, la plantilla de job de un CronJob, y un Pod suelto, que es su propia plantillakind, name y namespace del recurso que lleva la plantilla; labels, las etiquetas de la plantilla
controller_selectorsDeployment, StatefulSet, DaemonSet, ReplicaSet, Job y CronJob emitidokind, name, namespace; match_labels, los matchLabels de su selector
service_selectorsService emitidoname, namespace; selector, las etiquetas a las que envía tráfico
container_portscontenedor de una plantilla de pod que declara una lista ports, contenedores de inicialización incluidoskind, name y namespace del recurso que lleva la plantilla; container, el nombre del contenedor; ports, una entrada por puerto con su name, container_port y protocol

Cómo se leen los hechos:

  • Cada hecho es una lista. Una plantilla siempre recorre un hecho, incluso cuando contiene una sola entrada; no hay un valor único que leer por sí solo.
  • Los cuatro, en cada renderizado. Cada uno se informa siempre que este proveedor renderiza un nodo, como una lista vacía cuando el renderizado no emitió nada de lo que describe — un componente cuyo chart emite solo un ConfigMap informa de cuatro listas vacías. El renderizado de otro proveedor no informa de ninguno de estos nombres, y un nombre del que nadie informó se lee como nada.
  • Leídos a partir de lo que se emitió, en cada ruta. Los hechos proceden de los documentos que emitió el renderizado, sea cual sea el modo que los produjo: los manifiestos renderizados de un chart, los de un Workload sintetizado y los manifiestos que un autor colocó mediante artifacts:, que informan exactamente de lo que llevan esos manifiestos. Se leen en la misma pasada, sobre los mismos documentos, que los nombres de recursos que este proveedor informa para la comprobación de nombres duplicados de la compilación. Las propias etiquetas de procedencia de un recurso forman parte de lo que lleva, así que las labels de un Pod suelto las incluyen; la plantilla de pod de un chart o de un artefacto conserva las etiquetas que escribió su autor.
  • Las entradas pueden proceder del propio renderizado del componente y de los renderizados de sus Features. Un componente puede renderizarse mediante más de una llamada — un chart y una colocación artifacts:, por ejemplo — y las listas que un nombre recibe de esas llamadas se unen en una sola, en el orden en que se ejecutaron las llamadas. En .context.used_by y .context.uses, los hechos del componente en el otro extremo de una conexión también reúnen lo que renderizaron las Features vinculadas a él, después de los suyos; .context.render_facts lleva solo el propio renderizado del componente.
  • En el orden de emisión. Las entradas siguen el orden en que el renderizado emitió los recursos. Un mapa de etiquetas es un mapa con claves como cualquier otro del contexto, así que una plantilla que recorre uno encuentra sus claves en orden de clave.
  • Lo que un documento omite, su entrada lo omite. Un recurso nombrado mediante generateName no tiene name; un recurso que no escribe ningún metadata.namespace no tiene namespace, y tampoco lo tiene uno que lo escribe vacío o null, que tampoco nombra ningún espacio de nombres; un controlador escrito sin matchLabels — un Job que se apoya en el selector que genera el clúster — no tiene match_labels; un Service sin selector no tiene selector; un puerto sin nombre o sin protocolo no tiene ninguno de los dos. Cualquier otra parte escrita vacía se informa vacía. protocol se informa solo donde el documento escribe uno, así que una plantilla que lo necesita escribe ella misma el valor predeterminado propio del clúster, TCP. container_port es un número dondequiera que el documento escriba uno.
  • namespace es el que escribe el documento, nunca una suposición. Es el propio metadata.namespace del recurso — para una plantilla de pod, el del recurso que la lleva, que es donde se ejecutan sus pods; un espacio de nombres escrito dentro de la propia plantilla de pod no se lee. Un Workload sintetizado escribe el espacio de nombres que declara su límite en cada recurso que emite, así que sus entradas llevan ese espacio de nombres. Las entradas de un chart llevan lo que escriben sus documentos emitidos: donde un límite declara un espacio de nombres, ese espacio de nombres — ya sea que las plantillas del chart lo proyecten o que el proveedor coloque en él el recurso (consulta Modo con fuente) — salvo que una plantilla fije uno propio, que la entrada lleva en su lugar; donde no se declara ninguno, el espacio de nombres de la release, default, donde las plantillas lo proyectan, y nada donde no escriben ninguno. Donde no hay nada escrito, la entrada no lleva ningún namespace en lugar del valor predeterminado del límite o del clúster, porque un recurso así acaba donde lo coloque la herramienta que aplica la salida, algo que no se conoce cuando se ejecuta la compilación. Una plantilla distingue ambos casos con optional: {{ optional . "namespace" "" }} está vacío exactamente donde el documento no escribió ninguno, así que una Feature que coloca algo junto a los pods de un componente puede distinguir un componente cuyo espacio de nombres de los pods se conoce de uno cuyo espacio de nombres no se conoce.
  • Reconocidos por tipo y grupo de API. Pod y Service se leen en el grupo core, los cuatro controladores en apps, Job y CronJob en batch, en cualquier versión del grupo. Un recurso personalizado de otro grupo que por casualidad lleve uno de estos nombres de tipo no se lee como tal. Las matchExpressions de un selector no se informan, ni tampoco un recurso envuelto en un documento kind: List o un valor escrito mediante una clave de fusión de YAML.

Lo que los hechos no pueden ver. Describen los documentos que emite la compilación, y nada que el clúster cree después. Los pods que un controlador crea en tiempo de ejecución a partir de un recurso personalizado — el clúster de base de datos de un operador, por ejemplo — no aparecen en ningún documento emitido, así que están ausentes por construcción; lo mismo ocurre con cualquier etiqueta que añada un controlador de admisión mutante cuando se aplican los manifiestos. Una Feature que debe admitir esos pods toma sus etiquetas de la propia documentación del recurso personalizado, como lo haría un autor sin estos hechos.

Una FeatureRecipe que admite en los pods de su anfitrión exactamente los pods de los componentes que lo llaman, seleccionando los propios pods del anfitrión mediante el selector del controlador del anfitrión:

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: admit-callers
version: 1.0.0
spec:
capability: helm
implements: example/admit-callers:1.0.0
readsCallerRenderFacts: true
artifacts:
allow-callers.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: {{ .context.rendered_name }}-allow-callers
spec:
podSelector:
matchLabels:
{{- range .context.render_facts.controller_selectors }}
{{- range $k, $v := .match_labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
policyTypes:
- Ingress
ingress:
- from:
{{- range .context.used_by }}
{{- range .render_facts.pod_template_labels }}
- podSelector:
matchLabels:
{{- range $k, $v := .labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
{{- end }}

Para un anfitrión api llamado por un componente web cuyo Workload sintetizó este proveedor, la política selecciona app: "api" y admite un podSelector que lleva cada etiqueta de la plantilla de pod de web — las mismas etiquetas que contiene el spec.template.metadata.labels de su Deployment emitido. Como la FeatureRecipe establece la clave, su vinculación se renderiza una vez que todos los componentes se han renderizado, así que los hechos están ahí sea cual sea, de api y web, el que la compilación alcance primero; sin la clave, una plantilla que lee render_facts en .context.used_by detiene la compilación antes de que se renderice nada.

Un podSelector en el from de una política coincide con pods del propio espacio de nombres de la política, así que la política anterior admite a los llamadores emitidos en el espacio de nombres en el que se aplica. Un llamador cuyas entradas llevan otro namespace se admite emparejando su podSelector con un namespaceSelector sobre la etiqueta kubernetes.io/metadata.name de ese espacio de nombres, que Kubernetes establece en cada espacio de nombres.

Particularidades específicas del Provider

  • Las descargas de charts usan solo los manejadores integrados de Helm. Un chart obtenido de un repositorio de Helm se descarga con los propios manejadores integrados http y https de Helm. Un plugin de descarga de Helm — uno instalado para el comando helm, o uno ubicado en el directorio desde el que se ejecuta la compilación — nunca se consulta, así que lo que haya en ese directorio no puede cambiar cómo se obtiene un chart.

  • Inyección de la procedencia. Las rutas con fuente y sintetizada convergen en el mismo conjunto de etiquetas y anotaciones; los renderizados con fuente las inyectan mediante una reescritura de YAML posterior al renderizado (después de que el SDK de Helm ya haya renderizado), así que los autores de charts no necesitan pasar las etiquetas de Aggrega a través de sus propias plantillas.

  • Orden del entorno — primero las entradas leídas de un Secret. La lista env de un contenedor sintetizado lleva dos clases de entrada: cada entrada attachments entregada as: env lee su valor de un Secret mediante valueFrom.secretKeyRef, y cada entrada variables lleva un value simple. El proveedor escribe primero cada entrada leída de un Secret y después cada variable simple, cada clase en el orden en que se escribió, y enumera las fuentes envFrom por separado bajo envFrom. Kubernetes expande una referencia $(NAME) en un valor de env a partir de las entradas enumeradas antes que ella en el mismo contenedor, nunca a partir de una enumerada después, así que este orden permite que una variable simple componga por referencia un valor leído de un Secret mientras el secreto mismo permanece en el Secret:

    containers:
    api:
    image: "api:1.0"
    variables:
    DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"
    attachments:
    DB_PASSWORD: { from: db-credentials, as: env }

    El contenedor renderizado enumera DB_PASSWORD antes que DATABASE_URL, así que el proceso recibe la URL con la contraseña en su lugar. Una variable también puede hacer referencia a cualquier variable escrita antes que ella, lo que mantiene significativo el orden de escritura dentro de variables. Los contenedores de inicialización siguen el mismo orden. Un contenedor que da un mismo nombre tanto como entrada variables como entrada attachments entregada as: env detiene la compilación en lugar de escribir ambas entradas, porque entonces solo este orden decidiría qué valor ve el proceso (consulta A container gives one environment variable two values (Un contenedor da dos valores a una misma variable de entorno)).

  • Cascada del espacio de nombres — los dos modos llegan al recurso de forma distinta. Ambos leen aggrega.ai/namespace de la cascada de anotaciones del límite, y ninguno inventa un espacio de nombres cuando ningún límite declara uno. En modo sintetizado el proveedor escribe metadata.namespace directamente, y omite el campo por completo cuando la cascada no produce ningún valor. En modo con fuente el proveedor suministra el valor como espacio de nombres de la release del chart — default cuando la cascada no produce ninguno — y la propia plantilla del chart decide si proyectarlo; donde se declara un espacio de nombres, el proveedor lo escribe después en cada recurso con espacio de nombres que el chart renderizó sin uno (consulta Modo con fuente). Así, con un espacio de nombres declarado, ambos modos colocan en él cada recurso con espacio de nombres — salvo un espacio de nombres que un chart fija por sí mismo y un tipo que el proveedor no puede clasificar. Sin ninguno declarado se separan: un chart que proyecta el espacio de nombres de la release coloca sus recursos en default, donde la salida sintetizada no escribe ninguno, y un chart que no escribe ningún espacio de nombres no los coloca en ninguno, así que acaban donde los ponga la herramienta que aplica los manifiestos. Los charts locales que llevan las FeatureRecipes de la biblioteca estándar leen en cambio el valor de la cascada directamente mediante su valuesMapping: hacerlo les permite omitir el campo cuando ningún límite declara un espacio de nombres, en consonancia con la salida sintetizada, algo que el espacio de nombres de la release por sí solo no puede expresar porque nunca está vacío.

Ejemplos prácticos

Modo con fuente — Recipe que apunta a un chart copiado localmente:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helm
version: 1.0.0
spec:
capability: helm
implements: core/api-server
source: ./vendor/charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}
service:
type: ClusterIP
port: {{ .values.port }}
env:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"

Modo Workload — Recipe que declara un Workload en línea:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-workload
version: 1.0.0
spec:
capability: helm
implements: core/api-server
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
api:
image: "{{ .values.image }}"
ports:
web: {{ .values.port }}
services:
svc:
type: ClusterIP
ports:
web: {{ .values.port }}

Referencias cruzadas