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

Provider Helm-Chart

El proveedor helm-chart produce un chart paraguas de Helm empaquetado por cada ruta de ensamblado. Mientras que el proveedor helm emite YAML de Kubernetes plano para su consumo directo mediante GitOps, helm-chart emite un esqueleto de chart — un Chart.yaml + values.yaml paraguas más un subchart por cada nodo que contribuye — que las herramientas posteriores pueden instalar mediante helm install o copiar localmente (vendoring) para una personalización adicional por entorno. El proveedor ensambla por (path, provider): cada nodo enlazado a una Recipe helm-chart contribuye al paraguas en el directory: evaluado del límite unido al subDirectory: de cada componente. Dos límites que se evalúan a la misma ruta se funden en un único chart paraguas combinado que enumera a cada contribuidor como dependencia de subchart.

Las plantillas de un subchart copiadas del chart de origen llevan lo que escribió su autor: el valor syncWave: <integer> del límite, el helm.sh/hook-weight de un hook y las etiquetas de procedencia de Aggrega solo les llegan donde el chart los escribe. El proveedor helm es el que estampa argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" y las etiquetas de procedencia en cada recurso que renderiza. Un artefacto cargado con $import: que este proveedor añade a un subchart lleva las etiquetas de procedencia y la anotación argocd.argoproj.io/sync-wave, y ningún helm.sh/hook-weight (consulta «Regla de inyección de artifacts:» más abajo). ArgoCD lee la anotación sync-wave, y Helm lee el peso de un hook.

Esta página es la referencia de autoría del proveedor helm-chart. Para la separación entre helm y helm-chart, consulta la sección Providers de la página de estado; para el modelo de composición de entradas común a todos los proveedores, consulta architecture/16-recipe-input-composition.md.

Tipos de entrada admitidos

El proveedor helm-chart acepta dos tipos de entrada:

  • Modo procedente de una fuente. Una Recipe con source: <chart-path> apunta a un directorio de chart de Helm en disco. El chart se copia en la estructura paraguas como subchart, tal cual salvo el propio name del chart — consulta «El nombre del chart que corresponde al chart paraguas»; no se realiza ningún renderizado ni procesamiento de plantillas a nivel de cada nodo. El papel de Aggrega es la composición (el ensamblado del paraguas a través de los nodos del límite), no la evaluación de plantillas.
  • Modo artifacts: cargado con $import:. Una Recipe con entradas artifacts: escritas como $import: por entrada declara archivos de plantilla adicionales que el proveedor helm-chart inyecta en el directorio templates/ del subchart tras la copia del chart de origen. Cada archivo se preprocesa como plantilla frente al contexto de plantillas de Aggrega usando los delimitadores [[ ]] (consulta «Regla de inyección de artifacts:» más abajo), de modo que cualquier plantillado Helm {{ }} en el mismo archivo sobrevive hasta el renderizado posterior de helm install.

Una Recipe dirigida a helm-chart que declara workload: se rechaza antes de renderizarse, con el rechazo que cualquier proveedor da para un tipo de entrada que no declara — nombra el tipo que admite este proveedor y dirige al autor a un proveedor que sintetiza:

provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (el proveedor no admite el tipo de entrada del nodo (nodo “api”). el proveedor “helm-chart” no admite recipes sintetizadas (este proveedor admite: procedente de una fuente); declara uno de los tipos de entrada admitidos, o apunta a un proveedor que admita el tipo sintetizado)

La separación es deliberada: la síntesis de cargas de trabajo (traducir un Workload abstracto en recursos de Kubernetes) es competencia exclusiva del proveedor helm. El papel de helm-chart es la composición de paraguas + subcharts para charts que el autor ya ha producido.

Una Recipe dirigida a helm-chart también puede declarar entradas artifacts: con contenido en línea (entradas cuyo valor es un escalar de bloque que lleva el cuerpo del archivo en línea en la Recipe en lugar de una referencia cargada con $import:). Una entrada con contenido en línea se coloca en la raíz del subchart bajo su clave escrita — sin prefijo templates/ y sin inserción de procedencia. Las propias plantillas de un chart leen un archivo suelto así mediante .Files.Get / .Files.Glob de Helm (el patrón canónico de ConfigMap a partir de archivos), así que un archivo en la raíz del chart es una forma legítima y de primera clase y no un error.

Ambas formas se evalúan con los delimitadores [[ ]] de Aggrega antes de su colocación, de modo que un cuerpo de cualquiera de las dos formas puede leer el contexto de pilares de la Recipe; {{ }} en cualquiera de los dos cuerpos se deja intacto y se convierte en una directiva de Helm en el momento del helm install posterior. Lo que difiere entre las formas es dónde acaba el archivo y si se le fusiona la procedencia:

  • Una entrada cargada con $import: es un archivo de plantilla: tras la evaluación (consulta «Regla de inyección de artifacts:» más abajo) se inyecta en el directorio templates/ del subchart con la procedencia fusionada, de modo que Helm la renderiza como un manifiesto junto a las propias plantillas del chart.
  • Una entrada con contenido en línea es un archivo de datos suelto: tras la evaluación acaba en la raíz del chart, sin cambios respecto a lo que produjo la evaluación y sin procedencia fusionada, para su consumo mediante .Files.

Regla de inyección de artifacts:

Cuando una Recipe helm-chart declara entradas artifacts: mediante $import: por entrada, cada valor $import: es la ruta a un archivo de plantilla resuelta relativa al propio directorio de la Recipe (el directorio que contiene el YAML de la Recipe en disco). El proveedor:

  1. Lee el contenido de cada archivo.
  2. Preprocesa el contenido como plantilla con los delimitadores de Aggrega [[ ]] frente al contexto de plantillas de la Recipe (el mismo contexto frente al que se evalúa el valuesMapping: de la Recipe). {{ }} dentro del contenido del archivo se deja intacto — esas expresiones se convierten en directivas de plantilla de Helm en el momento del helm install.
  3. Escribe cada archivo en charts/<instance-id>/templates/<authored-key> bajo la ruta de ensamblado del paraguas, con los archivos de un bundle anidados bajo esa clave. La clave bajo la que se escribe la entrada da nombre al archivo; la ruta de $import: selecciona su contenido y no aporta nada al nombre, así que la estructura de directorios dentro de esa ruta nunca llega a la salida.

La disciplina del doble delimitador [[ ]] / {{ }} es el detalle clave. Un archivo de artefacto típico cargado con $import: puede mezclar interpolación en tiempo de Aggrega (p. ej., [[ .values.image ]]) con interpolación en tiempo de Helm (p. ej., {{ .Release.Namespace }}). Cada par de delimitadores actúa en su propia fase: Aggrega resuelve [[ ]] en tiempo de compilación, antes de que el archivo quede colocado; Helm resuelve {{ }} en tiempo de instalación, después de que se entregue el paraguas.

Las colisiones de nombres de archivo entre las plantillas del chart de origen y las inyecciones de artefactos cargados con $import: generan CATALOG_ERROR — el diagnóstico nombra la ruta de salida en colisión, como templates/cm.yaml, y los dos tipos de entrada que la produjeron. Los autores resuelven la colisión renombrando la clave del artefacto o la propia plantilla del chart.

Conjunto de claves de source:

El source: del proveedor helm-chart nombra un chart, y acepta las dos formas que adopta el campo source:, leídas exactamente como las describe el conjunto de claves de source: del proveedor helm: una cadena simple de ruta del sistema de archivos y un objeto estructurado cuyo url: lleva la ubicación. Donde url: nombra una ruta del sistema de archivos, no se obtiene nada y el chart se lee del disco; donde lleva un esquema de transporte — oci://…, por ejemplo, con kind: helm-oci-chart — aggrega pull obtiene y fija el chart, y la compilación lo copia desde la caché al paraguas como subchart, en las mismas condiciones que un chart leído del disco.

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

El chart en la ruta de origen debe contener un Chart.yaml válido en su raíz; si falta, aparece un error claro antes de que se ejecute la copia. La estructura de directorios del chart se conserva al copiarlo — templates/, values.yaml, Chart.yaml y cualquier otro archivo están presentes en el directorio del subchart después de la composición. Cada archivo llega con los bytes que escribiste, hasta los comentarios, el orden de las claves y las comillas; la única excepción es el campo name del propio Chart.yaml del chart, que fija el paraguas — consulta «El nombre del chart que corresponde al chart paraguas».

Las dos formas de no nombrar un chart se rechazan, y los dos rechazos proceden de lugares distintos — conviene saberlo, porque solo uno de ellos cambia si cambias de capacidad. Un source: presente que sin embargo no declara nada lo rechaza el compilador antes de que se ejecute ningún proveedor, así que el resultado es el mismo sea cual sea la capacidad que nombre la Recipe; el diagnóstico te indica que omitas el campo para el modo sin fuente o que nombres una ruta no vacía. Omitir source: por completo es una autoría válida — es como una Recipe pide el modo sin fuente — y aquí se rechaza porque helm-chart solo declara el tipo de entrada procedente de una fuente, así que el compilador rechaza la combinación con el mismo mensaje que da para cualquier capacidad solicitada para un tipo de entrada que no declara. Lo que es propio de helm-chart es la declaración, no un rechazo propio: para recursos de Kubernetes generados a partir de un bloque workload:, usa en su lugar la capacidad helm.

Una Recipe que declara omits: se rechaza. La clave omits: deja fuera de la compilación documentos que una fuente renderiza, y este proveedor no renderiza ningún documento en tiempo de compilación: copia el chart en el paraguas, y las plantillas del chart se renderizan cuando se instala el paraguas. Sin nada renderizado no hay nada que dejar fuera, así que este proveedor no declara que respete la clave, y una Recipe o FeatureRecipe que la declare se rechaza antes de que se copie nada — consulta The provider does not support omits (El proveedor no admite omits). Para un chart que mantienes junto a la Recipe, una línea en el .aggregaignore de ese lugar deja fuera en cambio un archivo del chart, a partir de la próxima vez que se fije la Recipe; para un chart obtenido cuya salida deba perder un documento, renderízalo mediante el proveedor helm, que respeta la clave.

Composición indexada por ruta — la forma paraguas

El proveedor se ejecuta en dos fases por cada ruta de ensamblado:

  1. Copia por contribuidor. Para cada nodo enlazado a una Recipe helm-chart, el proveedor copia el árbol de directorios completo del chart de origen en un slot de subchart. Los archivos quedan planos en el mapa de salida por contribuidor; el ensamblador nombra charts como el subdirectorio bajo el que se sitúan sus contribuidores, y el orquestador da a cada contribuidor un directorio propio allí al ensamblar el paraguas — charts/<instance_id>/ para un componente. Una vinculación de Feature también es un contribuidor — tanto si copia localmente un chart como si renderiza manifiestos mediante el proveedor helm — y obtiene un directorio junto al del componente en lugar de dentro de él; consulta «Dónde acaba el chart de una vinculación».
  2. Ensamblado del paraguas por (path, provider). Una vez completadas todas las copias por nodo de la ruta, el ensamblador emite un Chart.yaml + values.yaml paraguas en la raíz de la ruta de ensamblado. El paraguas declara una dependencia por cada nodo que contribuye y dirige los valores por nodo a subbloques indexados por instance-id. Cuando la ruta de ensamblado recibe contribuidores de más de un límite (límites con un directory: compartido), cada contribuidor acaba como dependencia en el mismo paraguas.

El Chart.yaml paraguas tiene la forma:

apiVersion: v2
name: <effective-chart-name> # see "Chart-name resolution" below
version: 0.1.0
description: Aggrega umbrella chart for boundary "<assembly-path>"
dependencies:
- name: <encoded-instance-id> # the name the placed sub-chart carries
version: <user-chart-version> # from the source chart's Chart.yaml
alias: <encoded-instance-id> # see "How a name is derived" below
repository: file://charts/<instance_id> # the sub-chart's own directory

Resolución del nombre del chart

El name del chart del paraguas se resuelve mediante la cascada de anotaciones de los límites. La anotación aggrega.ai/chart-name efectiva de cada límite que contribuye (el valor resuelto por la cascada, subiendo por el árbol de límites) determina el nombre del paraguas; el valor resuelto se codifica para la posición del nombre del chart exactamente como cualquier otra identidad, así que un valor que solo contiene letras, dígitos, guiones bajos y guiones que la regla de más abajo conserva llega al chart tal cual. Cuando la ruta de ensamblado recibe contribuidores de más de un límite, la anotación aggrega.ai/chart-name efectiva de cada contribuidor DEBE resolverse al mismo valor; las discrepancias detienen la compilación con un diagnóstico que nombra los valores en conflicto y los límites que contribuyen.

La cascada resuelve de forma natural la tensión DRY: declara aggrega.ai/chart-name una sola vez en el límite padre y los límites hijos la heredan a través de la cascada; los límites hermanos sin un padre común deben declarar explícitamente valores coincidentes. Los límites que no declaran aggrega.ai/chart-name en ningún punto de su cascada recurren al nombre del agregado y a la ruta de ensamblado — el directorio de salida del paraguas bajo dist/, como boundaries/data/helm-chart —, cada uno codificado y unido como se describe más abajo.

El name de cada entrada de dependencia es el nombre que lleva el subchart colocado — la propia identidad codificada de la instancia del componente, el mismo valor que el alias — por las razones expuestas en «El nombre del chart que corresponde al chart paraguas». Su version sigue siendo la versión del propio Chart.yaml del chart de origen. El alias delimita los valores del subchart bajo values.yaml.<alias>.*, conforme a la convención de Helm para los valores paraguas, de modo que los valores por instancia se propagan correctamente cuando se instala el paraguas.

El directorio de subchart de un componente conserva el instance_id exactamente como se escribió, así que charts/<instance_id>/ es donde acaban sus archivos y aquello a lo que apunta el repository de la dependencia. Por tanto, dos instancias del mismo chart de origen coexisten sin colisión en el sistema de archivos, y cada una conserva su propio bloque de valores bajo su propio alias.

El name de la dependencia y su repository son cadenas distintas, y es por diseño. name es lo que el chart en esa ubicación DECLARA, porque Helm enlaza una dependencia a un chart hijo por el nombre declarado del propio hijo; repository es donde se encuentra ese chart. Para un componente ambos resultan leerse igual, ya que los dos derivan del mismo ID de instancia. Para una vinculación de Feature difieren — el nombre declarado lleva la identidad compuesta de la vinculación, mientras que el directorio lleva sus dos coordenadas unidas —, así que leer uno como el otro nombra algo que no existe.

Dónde acaba el chart de una vinculación

Una vinculación de Feature que copia localmente un chart obtiene un directorio propio junto al componente al que está vinculada, un nivel por debajo de charts/:

charts/
├── api/ # the component's own chart
├── api--guardrail/ # a Feature attached to `api` under `guardrail`
└── api--audit/ # a second Feature attached to the same component

Una Feature vinculada a un límite en lugar de a un componente no tiene un componente anfitrión que nombrar, así que su directorio es solo su nombre de instancia: charts/aux/.

Por qué junto y no dentro. Helm descubre un chart hijo en charts/* — un nivel, no un recorrido recursivo. Un chart colocado a más profundidad no es hijo de nada; es un dato dentro del directorio de otro hijo, accesible solo mediante .Files. Así que un chart colocado dentro del propio directorio de chart del componente se copiaría en la salida, haría que la compilación tuviera éxito y no aportaría ninguno de sus recursos a lo que despliegas — sin que nada lo informe. Colocar cada contribuidor en su propio directorio de nivel superior es lo que hace que se rendericen los recursos de la vinculación.

El paraguas también declara la vinculación como una de sus dependencias. Hacen falta las dos mitades: un chart presente bajo charts/ y ausente de dependencies: es un error de lint, y un chart declarado en dependencies: sin un chart hijo correspondiente presente hace que el paraguas se niegue a cargarse.

Las dos coordenadas se unen, no se concatenan. Un nombre de directorio se compone a partir del anfitrión y de la instancia mediante la misma regla de escape descrita más abajo, aplicada a cada coordenada antes de unirlas con --. Juntarlas directamente con -- sería ambiguo: un anfitrión llamado a--b con una instancia c, y un anfitrión a con una instancia b--c, llegarían a un mismo directorio. Codificar primero cada coordenada las mantiene separadas, de modo que un -- escrito dentro de una coordenada aparece como -zh-.

Qué admite el nombre de directorio. Las letras ASCII en mayúsculas y minúsculas, los dígitos, el punto y el guion bajo pasan tal como los escribiste, así que API--aux y web.api--aux se leen como esperarías. Un guion que escribiste se conserva siempre que el carácter que lo sigue sea uno de esos, así que web-api--aux no cambia; un guion doble se escapa, porque el par es la unión. Todo lo demás se escapa con la misma regla que un nombre de chart. El conjunto se delimita así porque estos nombres de directorio son a la vez rutas en disco y la ubicación que resuelve el puntero file:// de una dependencia, y un carácter que sirve en un nombre de archivo puede truncar una URL o hacer que se vuelva a decodificar.

Los valores siguen al nombre declarado, no al directorio. Los valores de un chart hijo se delimitan bajo el nombre que ese chart declara, así que los valores para el chart de arriba se direccionan por el nombre declarado de api--guardrail — cfr-zh-api-zh-guardrail — en lugar de por su directorio.

Nunca escribes esa clave tú mismo. Escribes los valores en la vinculación, y el values.yaml del paraguas se compone por ti con el bloque ya en la dirección por la que se direcciona el chart colocado. Para una Feature vinculada a un componente son los values: que declaras en la vinculación, leídos por el propio valuesMapping: de la FeatureRecipe; para una Feature vinculada a un límite es el infra: que declaras allí, ya que una Feature vinculada a un límite no tiene un pilar de valores del componente. Sea cual sea, el mapa al que se resuelve valuesMapping: se convierte en el propio bloque de la vinculación en el paraguas:

# the umbrella's values.yaml, composed for you
api: # the component's own chart
replicaCount: 3
cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought
auditEndpoint: "https://audit.internal"

Esta es la única vía que tienen esos valores. Un chart que aporta una Feature llega con sus archivos tal como los escribió su autor — salvo el único campo del manifiesto descrito en «El nombre del chart que corresponde al chart paraguas» —, así que nada escribe tus valores en ese chart, y es el bloque del paraguas el que los suministra. Un chart cuyo bloque nunca llegó no es un chart roto: renderiza los valores predeterminados que trae su propio values.yaml e informa de éxito, así que da a un valor predeterminado un valor que notarías si quieres ver la diferencia durante la autoría.

Una vinculación cuya FeatureRecipe se renderiza a través del proveedor helm

Una FeatureRecipe de la capacidad helm, vinculada a un componente en este destino, aporta manifiestos de Kubernetes terminados en lugar de un chart. Acaban en el propio directorio de la vinculación exactamente como los renderizó el proveedor helm, y el proveedor da a ese directorio las dos cosas que lo convierten en un chart que Helm instala: un Chart.yaml mínimo, que declara el propio nombre de la vinculación en la versión 0.1.0, y una única plantilla, templates/rendered.yaml, que emite cada archivo YAML renderizado mediante .Files.Get de Helm por su nombre:

charts/api--guardrail/
├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0
├── guardrail-config.yaml # the manifest the helm provider rendered
└── templates/
└── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}

El nombre declarado es el que declararía un chart que la misma vinculación copiara localmente, de modo que la entrada de dependencia del paraguas y su bloque de valores se direccionan exactamente como se describe arriba. .Files.Get devuelve los bytes de un archivo tal cual en lugar de evaluarlos una segunda vez, de modo que un manifiesto que lleva llaves de plantilla literales — el {{ $labels.instance }} de una regla de alertas, la consulta de un panel — se instala con ellas intactas. Sus valores se resolvieron en esos manifiestos cuando el proveedor helm los renderizó, así que el bloque que el values.yaml del paraguas lleva bajo ese nombre no lo lee nada.

El nombre del chart que corresponde al chart paraguas

Lo único que Aggrega cambia dentro de un chart que copiaste localmente es el propio campo name de ese chart. En el Chart.yaml del chart colocado, name se establece en la identidad codificada de lo que haya aportado ese chart.

Para un componente, es la propia identidad de la instancia del componente — el mismo valor que el alias de la dependencia — y la entrada de dependencia del paraguas también nombra ese valor, de modo que ambos lados siempre coinciden.

Un chart que aporta una vinculación de Feature es un contribuidor por derecho propio, y declara su propia identidad en lugar de repetir la del componente al que está vinculado. Esa identidad se compone de dos cosas que escribiste — el componente que aloja la vinculación y el nombre bajo el que se vincula la Feature — detrás de un breve prefijo que la marca como identidad de una vinculación y no de un componente; el valor compuesto se escribe luego para la posición del nombre del chart mediante la derivación de más abajo, exactamente como cualquier otra identidad.

Así, vincular una Feature que copia localmente un chart a un componente llamado api bajo el nombre guardrail coloca un chart que declara cfr-zh-api-zh-guardrail, mientras que el propio chart de ese componente sigue declarando api. Los dos son contribuidores separados, y cada uno declara un nombre propio en lugar de declarar ambos el del anfitrión.

Nada más en el chart se toca. Todos los demás archivos llegan byte a byte tal como los escribiste, y dentro de Chart.yaml todos los demás campos, cada comentario, el orden de las claves y el entrecomillado son exactamente como se escribieron. Una clave anidada en otro lugar del manifiesto que también se llame name — el nombre de un mantenedor, por ejemplo — se deja como está.

Por qué el paraguas necesita ese campo. El name de un chart es aquello a lo que Helm enlaza una dependencia del paraguas. Lo escribe quien creó el chart, que, para un chart obtenido de upstream, no es la persona que lo despliega — así que dos componentes en una misma ruta de ensamblado pueden, de forma perfectamente razonable, copiar localmente charts cuyos manifiestos declaran el mismo nombre. Si ambos subcharts conservaran ese nombre compartido, ambas dependencias del paraguas se resolverían al que Helm hubiera cargado primero de los dos: el chart de un componente se renderizaría dos veces y el del otro ninguna, mientras que los valores de cada componente seguirían llegando, de modo que la salida parecería completa y sería incorrecta. Derivar el nombre colocado de la instancia del componente elimina por completo el nombre compartido, y por eso no hay que rechazar nada — incluidos los dos casos que no tienen otro remedio: copiar localmente el mismo chart bajo dos componentes, donde el nombre se comparte por construcción, y copiar localmente un chart que no escribiste, cuyo nombre no puedes cambiar.

Lo único que puedes observar. Una plantilla que lee el nombre de su propio chart — {{ .Chart.Name }}, y todo lo que se deriva de él, como el habitual idioma de nombrado de recursos {{ .Chart.Name }}-{{ .Release.Name }} — lee la identidad codificada de la instancia, no el nombre escrito en el Chart.yaml del chart de origen. Es lo que esa plantilla ya leía antes de que se estableciera el campo, porque Helm presenta un subchart bajo el alias con el que su padre lo enlaza; establecer el campo hace que el archivo en disco coincida con lo que el renderizado ya producía. Así, en el ejemplo práctico de más abajo, una plantilla del subchart api-east lee api-east.

Si el nombre de un recurso tiene que llevar el nombre escrito del chart, pon ese nombre en el values.yaml del chart y léelo de ahí — un valor es tuyo y Aggrega no lo toca.

Cómo se deriva un nombre

Un nombre de chart de Helm y un alias de dependencia de Helm aceptan cada uno un conjunto de caracteres más reducido que el que pueden llevar un nombre de agregado, una ruta de límite o un instance_id. En lugar de sustituir un carácter que el destino no acepta, la derivación lo escribe explícitamente, de modo que dos identidades que solo difieren en la puntuación siempre llegan a dos nombres — y un valor escrito bajo un alias solo puede llegar al subchart que ese alias nombra.

  • Una letra, un dígito y un guion bajo se conservan exactamente como se escribieron.
  • Un guion se conserva 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.
  • Cualquier otro carácter se escribe como -z seguido de una letra que lo nombra: d para un punto, s para un separador de ruta, h para un guion que la regla anterior no conserva. Cualquier otra cosa 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 — de modo que un nombre que no es texto válido se sigue escribiendo explícitamente de forma distinta en lugar de colapsarse.
  • Un valor vacío se escribe -ze, que ningún valor no vacío puede producir.
  • Donde dos identidades componen un mismo nombre de chart — un nombre de agregado que cualifica una ruta de ensamblado — se unen con --. Una única identidad codificada nunca contiene ese par, así que el nombre unido indica sin ambigüedad qué identidad es cuál.

Así, un instance_id data.main-db da el alias data-zdmain-db, y el agregado fullstack-app con la ruta de ensamblado boundaries/data/helm-chart da el nombre de chart fullstack-app--boundaries-zsdata-zshelm-chart. Una entrada idéntica siempre produce el nombre idéntico.

El values.yaml del paraguas está indexado por alias:

api-server: # sub-chart alias = encoded instance_id
image: "registry/api-server:v2"
replicaCount: 3
billing-svc:
image: "registry/billing:v1"
replicaCount: 2

Cuando el valuesMapping: de un subchart se evalúa frente a su contexto de plantillas, el mapa de valores resultante rellena automáticamente este subbloque indexado por alias. Eso vale para cada contribuidor del paraguas, no solo para los componentes: una vinculación de Feature que copia localmente un chart es un contribuidor por derecho propio, así que el valuesMapping: de su FeatureRecipe rellena un bloque propio, indexado por el nombre que declara su chart colocado. Consulta «Dónde acaba el chart de una vinculación».

Una clave que el valuesMapping: establece en null se escribe en su bloque como null. Al instalar con Helm 4, un null en el propio values.yaml del paraguas elimina el valor predeterminado del subchart para esa clave solo cuando la instalación también aporta valores para ese subchart; una instalación que no aporta ninguno para él descarta el null, y el valor predeterminado del subchart se mantiene. Un null en los valores pasados a helm install elimina el valor predeterminado en cualquier caso.

Particularidades específicas del Provider

  • El Chart.yaml del subchart es obligatorio. La operación de copia exige que haya un Chart.yaml en la raíz de la ruta de origen. Si falta, se detiene la compilación antes de que se ejecute el paso del paraguas.
  • El name del chart colocado corresponde al paraguas. Se establece en la identidad codificada de lo que haya aportado el chart — la propia identidad de una instancia de componente o, para un chart que aporta una vinculación de Feature, la propia identidad de esa vinculación — y es lo único dentro de un chart copiado localmente que Aggrega cambia. Consulta «El nombre del chart que corresponde al chart paraguas».
  • Un chart de origen debe declarar una versión, y un nombre. La versión de la entrada de dependencia es la que declara el propio Chart.yaml del chart de origen, así que un chart que no declara ninguna versión detiene la compilación en lugar de recibir una — una dependencia fijada a una versión que el subchart no lleva dejaría a los valores por instancia del paraguas sin poder llegar a él. Un chart cuyo Chart.yaml no declara ningún nombre, contiene más de un documento YAML o no se puede analizar detiene la compilación por el mismo motivo: el paraguas no puede componer un subchart que no puede leer.
  • Alias y nombres de chart codificados. Un instance_id, un nombre de agregado o una ruta de límite que lleve un carácter que un nombre de chart de Helm o un alias de dependencia no acepta aparece codificado en el paraguas renderizado, según «Cómo se deriva un nombre» más arriba. Una identidad formada solo por letras, dígitos, guiones bajos y guiones que la derivación conserva aparece exactamente como se escribió.
  • Puntero de repositorio file://. Las entradas de dependencia del paraguas usan un puntero de repositorio file:// que nombra el propio directorio del chart hijo — file://charts/<instance_id> para un componente, y el propio directorio de la vinculación para un chart que aporta una Feature. Es la convención del sistema de archivos local para charts hijos dentro del árbol y permite que helm dependency build resuelva el paraguas sin llamadas a registros externos. El puntero nombra una ubicación y nunca el nombre declarado del chart; los dos difieren para una vinculación, y helm dependency build es el paso que rechaza un puntero que nombra un directorio que no existe.
  • Sin renderizado de plantillas a nivel de helm-chart. El proveedor no invoca el pipeline de renderizado del SDK de Helm; copia y compone. Los autores que necesiten manifiestos planos prerrenderizados deberían usar en su lugar el modo con fuente del proveedor helm.

Ejemplo práctico

Un límite de dos nodos, cada nodo enlazado a una Recipe helm-chart que apunta al mismo chart de origen:

# Recipe — used by both `api-east` and `api-west` instances
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helmchart
version: 1.0.0
spec:
capability: helm-chart
implements: core/api-server
source: ./charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

Tras la composición, la ruta de ensamblado evaluada del límite (por defecto dist/<boundary-directory>/<capability>/, porque subDirectory: tiene como valor predeterminado {{ .capability }}) contiene:

dist/<boundary-directory>/helm-chart/
├── Chart.yaml # umbrella; lists api-east and api-west as dependencies
├── values.yaml # alias-keyed: api-east + api-west values blocks
└── charts/
├── api-east/ # ./charts/api-server, name: api-east
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ └── deployment.yaml
└── api-west/ # ./charts/api-server, name: api-west
├── Chart.yaml
├── values.yaml
└── templates/
└── deployment.yaml

Ambos subcharts son copias del único chart de origen, y cada uno lleva el nombre de su propia instancia en su Chart.yaml — que es lo que permite copiar localmente un mismo chart dos veces en un único paraguas. Todo lo demás en ambas copias es idéntico al origen.

Un helm install <release-name> dist/<boundary-directory>/helm-chart sobre esta estructura instala ambas instancias como una única release de Helm, con los valores del paraguas indexados por alias controlando las plantillas de cada subchart.

Referencias cruzadas