Workload
El papel arquitectónico del tipo Workload — por qué existe, cómo se compone con los otros dos tipos de entrada de una Recipe (sourced y artifacts) y toda la superficie del esquema — se encuentra en ../../architecture/16-recipe-input-composition.md. Esta página cubre la superficie de autoría del Workload: cómo escribe un autor de Recipe el contenido de un Workload, qué evalúa el compilador y cuándo, cómo interactúan los campos del Workload con el featuresSchema del Component y qué pilares pueden leer las plantillas dentro de un Workload.
Ubicación de autoría
El contenido de un Workload se escribe en línea o desde un archivo, dentro de una Recipe o de una FeatureRecipe (consulta FeatureRecipe). Una Recipe declara como máximo un workload:; una FeatureRecipe declara igualmente como máximo uno propio:
# Inline (block scalar)spec: workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload # ...o
# File-loaded via $import: (path relative to the Recipe directory)spec: workload: $import: ./workload/workload.yamlAmbas formas producen el mismo objeto Workload tras el análisis; la elección es una cuestión de ergonomía de autoría. Una tercera forma importa un Workload compartido entre Recipes desde una entrada de una WorkloadLibrary, por su identidad de nombre simple: $import: <Library>#/workloads/<entry>. Según el vocabulario unificado de importación de archivos, $import: acepta una única fuente — consulta ../vocabulary/cross-document-ref.md para la distinción más amplia entre $ref: / $import:.
El YAML de un Workload no se escribe como una entidad de catálogo independiente. No existe ningún directorio catalog/workload/; la gramática de Workload existe solo como contenido que consume una Recipe o una FeatureRecipe — escrito en línea, en un archivo junto a ella o en una entrada de una WorkloadLibrary. Las declaraciones apiVersion y kind dentro del YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) identifican el contenido incrustado para la validación del esquema; no hacen que el Workload sea direccionable de forma independiente.
Evaluación de plantillas
El contenido de un Workload se procesa como plantilla de Go con el contexto completo de los pilares antes del análisis. Cuando un autor de Recipe escribe una plantilla como la siguiente…
replicas: {{ optional .infra `replicas` 1 }}…el compilador evalúa esa plantilla durante la subpasada de Workload del renderizado, resuelve .infra.replicas respecto a la carga útil infra del nodo y analiza el YAML resultante como un documento Workload. Los locals de la Recipe se resuelven antes de evaluar el Workload, por lo que una plantilla de Workload los lee, ya resueltos, bajo .locals.
Acceso a los pilares dentro de las plantillas de Workload:
.values— carga útil cognitiva escrita por el desarrollador y declarada en el Aggregate..infra— dimensionamiento físico escrito por Ops y declarado en la Release..parameters— ya interpolados en la resolución; visibles mediante.values/.infradondequiera que el desarrollador u Ops hayan referenciado.parameters.<name>en lo que escribieron..locals— estado privado de la Recipe resuelto en el preámbulo de locals y publicado en la resolución de las fuentes; disponible en todos los puntos de evaluación de plantillas de Workload..context.instance_id— el ID de instancia aplanado del nodo; el prefijo de los nombres de recursos que emite un proveedor que nombra los recursos sintetizados según la identidad..context.rendered_name— el nombre que da a los recursos sintetizados un proveedor que deriva por sí mismo su nombre, como el nombre de release de helm; presente solo donde el proveedor informa de uno. Consulta ../templates/rendered-resource-names.md..context.inject— el pipe de inyección posterior a la interceptación, ya reescrito por cualquierinjectMappingde FeatureRecipe durante el mapeo de la inyección..context.uses— las aristas de topología enriquecidas salientes de este nodo, cada una con losprovides, laslabelsy las anotaciones en cascada resueltos del destino y, bajo.context.uses.<alias>.features.<slot>, las vinculaciones que lleva esa conexión..features— las vinculaciones propias del nodo, cada una con sutype,values,infray susprovidesresueltos. Una vinculación con el nombre de un slot que el Component declara enfeaturesSchemallena ese slot (ver más abajo). Una vinculación que lleva una conexión no está entre ellas; se lee bajo su conexión, y un Workload la entrega nombrando la conexión (consulta Entregar una credencial que lleva una conexión).
Consulta ../vocabulary/data-pillars.md para el contrato completo de acceso a los pilares y ../templates/expansion-matrix.md para ver dónde se sitúa la evaluación del Workload en la secuencia de evaluación de plantillas.
Aspectos esenciales de la semántica de los campos
El esquema completo del Workload está en ../../architecture/16-recipe-input-composition.md, en «El tipo Workload». Las convenciones de autoría que siguen cubren las decisiones a nivel de campo que toma el autor de una Recipe.
form
form declara la forma abstracta de controlador de la carga de trabajo — el tipo de ciclo de vida en tiempo de ejecución que tiene, independientemente de cualquier plataforma de destino. Es una única cadena, una de stateless, stateful, daemon, scheduled, task, reference, y su valor predeterminado es stateless cuando se omite:
stateless— réplicas intercambiables, escaladas horizontalmente, sin identidad por réplica (el servicio común de larga duración).stateful— réplicas con identidad estable por réplica y almacenamiento por réplica. Un volumenpersistentTemplatees un complemento de esta forma.daemon— una instancia por cada host elegible.scheduled— ejecuciones recurrentes, activadas por tiempo.task— una única ejecución hasta su finalización.reference— sin contenedores propios: el componente representa un endpoint externo, dado comoendpoint(un host o una URL, transmitido tal como está escrito) y unportopcional. El proveedor helm lo emite como un Service de tipoExternalName; el proveedor compose no emite nada para él.
La forma no contiene por sí misma tipos de recursos nativos de la plataforma. Cada proveedor de destino que sintetiza un Workload asigna la forma a su propia forma nativa:
form | Kubernetes (helm) | Compose |
|---|---|---|
stateless | Deployment | service (sin volumen persistente) |
stateful | StatefulSet | service + volumen con nombre |
daemon | DaemonSet | detiene la compilación |
scheduled | CronJob | detiene la compilación |
task | Job | detiene la compilación |
Los proveedores terraform y cloudformation renderizan Recipes con origen y Recipes solo de artefactos, y no sintetizan ningún Workload: una Recipe que declara workload: vinculada a cualquiera de los dos detiene la compilación, nombrando los tipos de entrada que admite el proveedor.
Cuando un proveedor de destino no tiene una correspondencia limpia para una forma, la compilación se detiene de forma explícita en lugar de degradar la carga de trabajo a una forma que tergiversa la intención — elegir una forma que un límite de destino no puede expresar es un error en tiempo de compilación, no una degradación silenciosa. El proveedor compose se detiene ante daemon, scheduled y task. El proveedor helm emite un CronJob para scheduled (consulta schedule más abajo) y solo se detiene cuando su programación falta o está mal formada.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: statefulcontainers: db: { image: "postgres:16", ports: { db: 5432 } }volumes: data: persistentTemplate: size: "20Gi"services: headless: type: Headless ports: db: 5432schedule
schedule es la programación cron de una carga de trabajo form: scheduled — el campo complementario que da a la forma recurrente su recurrencia. Es una única cadena en un único formato canónico:
- una expresión crontab estándar de 5 campos — minuto, hora, día del mes, mes, día de la semana (por ejemplo,
0 0 * * *para cada día a medianoche,*/15 * * * *para cada quince minutos), o - una de las macros
@hourly,@daily,@weekly,@monthly,@yearly.
schedule es obligatorio cuando form: scheduled y solo tiene sentido en ese caso. Una carga de trabajo form: scheduled sin programación, una programación que no es ni una expresión de 5 campos ni una macro reconocida (una expresión de 6 campos con los segundos al principio, un token @ no reconocido o un campo con caracteres no válidos), o un schedule establecido en cualquier otra forma es una detención en tiempo de compilación que indica la corrección. El proveedor helm transmite el valor tal cual al spec.schedule del CronJob emitido.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # daily at 02:00containers: report: image: "reporter:1.0" command: ["/report"]suspend
suspend suspende la programación recurrente de una carga de trabajo form: scheduled. Es un booleano y su valor predeterminado es false. Con suspend: true, el recurso programado se sigue renderizando con su schedule en su lugar, pero ninguna ejecución se inicia a partir de esa programación hasta que se reanuda, y una ejecución todavía se puede iniciar manualmente desde el recurso. Esa es la forma adecuada para una tarea que solo debe ejecutarse cuando alguien la solicita.
El proveedor helm emite el campo como el spec.suspend: true del CronJob. En Kubernetes, kubectl create job <name> --from=cronjob/<cronjob> inicia una ejecución a partir del CronJob suspendido, y la programación se reanuda en cuanto spec.suspend vuelve a ser false. suspend: false se renderiza exactamente igual que un suspend omitido, de modo que el campo no cambia ninguna salida hasta que se establece. El proveedor compose no tiene una forma programada y se detiene ante cualquier carga de trabajo form: scheduled, suspendida o no.
suspend: true en cualquier otra forma es una detención en tiempo de compilación que indica la corrección: ninguna otra forma tiene una programación que pueda suspender.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # documents when it would run; nothing starts it while suspendedsuspend: truecontainers: report: image: "reporter:1.0" command: ["/report"]replicas
Un único entero para el número de réplicas de la carga de trabajo. Su valor predeterminado es 1 cuando se omite. Usa una expresión de plantilla para determinar las réplicas a partir del dimensionamiento declarado por Ops:
replicas: {{ optional .infra `replicas` 1 }}containers frente a initContainers
containers es un mapa ordenado cuya clave es el nombre del contenedor. El contenedor 0 (la primera clave del mapa) importa para el orden de la especificación del pod en la salida de Kubernetes y para la semántica del contenedor predeterminado. initContainers es una lista ordenada de entradas de contenedores de inicialización, cada una con name, image y la misma forma de autoría para variables, secretos y montajes de volumen que los contenedores principales.
name es opcional en una entrada de initContainers. Una entrada que lo omite recibe el nombre init-<index>, donde el índice es la posición de la entrada en la lista, contando desde 0. Como el nombre identifica el contenedor en la salida renderizada y en cualquier diagnóstico que lo nombre, una entrada a la que valga la pena referirse merece un nombre explícito.
La preservación del orden del autor es un contrato fundamental del modelo Workload — el compilador emite containers, volumes, services, los ports de los contenedores, las variables de los contenedores y los attachments de los contenedores, cada uno en el orden en que el autor de la Recipe los declaró, en cada compilación. Los autores de Recipe pueden confiar en la forma ordenada: cuando lo que ocurre en tiempo de ejecución depende del orden (arranque de sidecars, encadenamiento $(VAR) en variables de entorno, volumeMounts que hacen referencia a volúmenes declarados previamente), el orden de autoría ES el orden en tiempo de ejecución dentro de cada una de esas colecciones. El entorno de un contenedor combina dos de ellas, y entre ambas los proveedores que sintetizan escriben primero las entradas leídas de vinculaciones (attachments entregados as: env) y después las variables simples, cada tipo en el orden escrito — de modo que, en un destino Kubernetes, una variable puede hacer referencia, como $(NAME), a cualquier variable leída de una vinculación de su contenedor y a cualquier variable declarada antes que ella (consulta el orden del entorno del proveedor helm). Un contenedor que da un mismo nombre tanto como entrada de variables como entrada de attachments entregada as: env detiene la compilación, porque solo ese orden decidiría cuál de los dos valores ve el proceso (consulta A container gives one environment variable two values (Un contenedor da dos valores a una misma variable de entorno)).
La autoría de los campos de contenedor sigue estas convenciones:
imagesuele ser una expresión de plantilla que hace referencia a.values.image(la imagen seleccionada por el desarrollador) con anulaciones.infra.*opcionales para añadir un prefijo de registro específico del entorno.variableses un mapa simple string → string para variables de entorno. El mapa combina dos fuentes de datos distintas mediante expresiones de plantilla de Go: literales del pilar del desarrollador (entradas cuyas expresiones de plantilla leen.values/.infra/.locals— carga útil que se origina en los pilares del Component) y datos de la tubería entre componentes (entradas cuyas expresiones de plantilla leen.context.inject.env.<KEY>— carga útil que se origina en elprovides:de otro componente y se enruta a través de la tubería de la topología). Las dos fuentes fluyen al mismo mapavariables; los autores eligen una por entrada según si el valor es local del componente o se deriva de otro componente. Patrones comunes:LOG_LEVEL: "{{ .values.log_level }}"es del pilar del desarrollador (local del componente);DB_HOST: "{{ .context.inject.env.DB_HOST }}"es de la tubería entre componentes (el valor se origina en elprovides.hostde un componente de destino, enrutado a través de la declaraciónuses[].inject.env.DB_HOSTdel llamador). Ambas formas se compilan en una única listaenv:de Kubernetes en el Deployment renderizado; la semántica de doble origen existe solo en tiempo de autoría.attachmentshace referencia a slots declarados en elfeaturesSchemadel Component o, nombrando una conexión, a un slot que declara el socket de esa conexión (consulta la sección de integración más abajo).portses un mapa de puertos con nombre (web: 8080,admin: 9901); los nombres de puerto coinciden con los nombres de puerto del ámbito del contenedor y se referencian medianteservices.<service>.ports.<portname>. Un puerto que usa un transporte distinto del predeterminado del destino se escribe en su lugar en la forma ampliada — consulta Protocolos de transporte de los puertos más abajo.volumeMountshace referencia por nombre a volúmenes declarados en otra parte de la secciónvolumes:del Workload.resourcesdeclara lasrequestsy loslimitsdel contenedor — las cantidadescpuymemoryy, opcionalmente, claves de recursos extendidos para GPU y otros dispositivos (consulta Cargas de trabajo de GPU y dispositivos más abajo).healthusa la forma de intención (http: /path,tcp: <port>,exec: [cmd, ...]) — consulta la sección de sondas de estado más abajo.
volumes
Cada volumen es exactamente de un tipo: ephemeral, configmap, secret, persistent o persistentTemplate. Los tipos son mutuamente excluyentes dentro de una única declaración de volumen; cada tipo tiene sus propios campos obligatorios:
volumes: app-config: configmap: source: "{{ .locals.app_cm }}" data: persistent: size: "10Gi" class: "gp3" cache: ephemeral: sizeLimit: "1Gi"persistentTemplate produce un PVC por réplica en la traducción con forma de StatefulSet; en la traducción a compose se degrada a un único volumen con nombre compartido, con una advertencia notificada junto con la compilación. El archivo generado en sí no lleva ninguna nota de la degradación — es idéntico byte a byte a como sería sin la advertencia.
Traducción por proveedor. Cada proveedor traduce las cinco variantes de volumen a su forma nativa:
| Variante | Helm / helm-chart (K8s) | Compose | Notas sobre pérdidas |
|---|---|---|---|
ephemeral | emptyDir: { sizeLimit } | entrada tmpfs: a nivel de service que nombra la ruta de montaje (en memoria) | El tmpfs de Compose está respaldado por RAM; el emptyDir de helm está respaldado de forma predeterminada por el disco del nodo — una divergencia semántica en el medio de almacenamiento subyacente. sizeLimit no llega a ninguna parte de la salida de compose: la entrada emitida es solo la ruta de montaje. Un sizeLimit escrito por el autor genera una advertencia unsupported-field que lo nombra, notificada junto con la compilación en lugar de escrita en el archivo generado. |
configmap | Referencia a un volumen ConfigMap (consume un recurso ConfigMap emitido por los artifacts: de la Recipe o por una Feature) | Referencia configs: a nivel de service que nombra el configmap, montado en la ruta del montaje del volumen; la entrada configs: de nivel superior correspondiente proviene de los artifacts: de la Recipe | Ambos destinos hacen referencia al configmap por nombre y ninguno lee su contenido, por lo que la forma de autoría es simétrica. Lo que compose pierde es la semántica de actualización en el rollout del ConfigMap de K8s: una config de compose queda fijada al contenido que emitió la compilación. Una referencia que ninguna entrada de nivel superior resuelve detiene la compilación en lugar de emitir un montaje que quedaría colgando en tiempo de ejecución. |
secret | Referencia a un volumen Secret (consume el Secret que nombra una vinculación de credenciales — uno que emite su FeatureRecipe, o uno que ya existe) | env_file: para secretos con forma de variables de entorno, o un archivo de secreto montado con bind para secretos con forma de ruta | Compose carece de una semántica de primera clase para los Secret de Kubernetes. Un secreto con forma de ruta deliberadamente no toma la vía configs: de la variante configmap: una entrada de config en línea escribiría el valor del secreto en texto plano en el archivo compose emitido, y el compilador nunca resuelve un secreto en texto plano. El origen del bind es una ruta que el operador hace accesible en el host de compose, fuera de cualquier ciclo de vida de CRD de obtención desde un vault. |
persistent | Recurso PVC + volume.persistentVolumeClaim | Volumen con nombre | Los volúmenes con nombre de Compose son una abstracción plana del lado del host; el PVC de helm admite la declaración de clase de almacenamiento, modo de acceso y capacidad, que compose ignora. |
persistentTemplate | StatefulSet.volumeClaimTemplates (PVC por réplica; complemento de form: stateful) | Volumen con nombre (degradado — un único volumen compartido entre réplicas, con una advertencia notificada) | Compose no puede expresar plantillas por réplica. Cuando persistentTemplate se traduce a compose, se emite un único volumen con nombre y la fidelidad reducida se notifica como advertencia junto con la compilación en lugar de escribirse en el archivo generado. Los Workloads que dependen del aislamiento de volúmenes por réplica no deberían apuntar a límites solo de compose. |
La forma del controlador la elige el form de la carga de trabajo, no sus volúmenes. Se emite un StatefulSet cuando form: stateful; un volumen persistentTemplate es un complemento de esa forma — declara almacenamiento por réplica en una carga de trabajo que ya tiene la identidad por réplica que proporciona un StatefulSet. Declarar un volumen persistentTemplate en cualquier otra forma (o en el stateless predeterminado) es un error en tiempo de compilación que indica la corrección: declare form: stateful. Lo inverso está permitido — una carga de trabajo form: stateful no necesita declarar un volumen persistentTemplate. Los autores que quieren la semántica de StatefulSet establecen form: stateful directamente.
Una carga de trabajo form: stateful en el proveedor helm requiere un Service de gobierno headless: declara exactamente un service con type: Headless en el mismo Workload. El proveedor conecta el serviceName del StatefulSet a ese Service headless (proporciona las identidades de red estables por pod que necesita un StatefulSet). La compilación se detiene si no se declara ningún service headless — un StatefulSet no tendría entonces ningún Service de gobierno que nombrar — o si se declara más de uno, lo que deja ambiguo el Service de gobierno. Una carga de trabajo StatefulSet aún puede declarar services adicionales no headless (por ejemplo, un service ClusterIP para el acceso de clientes) junto al único service de gobierno headless.
Cantidades de recursos
Estos valores del Workload son cantidades — importes escritos en la notación que Kubernetes usa para los recursos: los valores resources.requests y resources.limits de un contenedor (o de un contenedor de inicialización) para cpu, para memory y para cada clave de recurso extendido, y ephemeral.sizeLimit, persistent.size y persistentTemplate.size de un volumen. El esquema del Workload tipa cada uno como cadena y no restringe su forma. El proveedor que sintetiza el Workload para un destino comprueba cada cantidad que emite, y comprueba el Workload tal como lo evaluaron las plantillas de la Recipe, de modo que un valor que llegó a través de infra, de un parámetro de la Release o de cualquier otra entrada de plantilla se juzga por la cadena a la que se renderizó.
Una cantidad es, sin nada antes ni después:
- un signo opcional,
+o-; - un número con al menos un dígito —
2,0.5,.5o1.; - como máximo uno de entre un exponente —
eoE, un signo opcional y luego dígitos, como en1e3o5E-2— o un sufijo de unidad: un sufijo decimaln,u,m,k,M,G,T,PoE(de 10⁻⁹ a 10¹⁸, en pasos de mil), o un sufijo binarioKi,Mi,Gi,Ti,PioEi(de 1024 a 1024⁶).
500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n y 4u son cantidades; lots, 1.5 cores, 1 gigabyte, 10 GB y 1e1.5 no lo son — un exponente es un número entero. Una E sola después del número es el sufijo decimal para 10¹⁸ (12E); seguida de dígitos, abre un exponente (1E3).
Esta es la forma que acepta el propio analizador de cantidades de Kubernetes, con una diferencia deliberada: una cadena cuyo número no tiene ningún dígito — m, Ki, +, ., e5 — se rechaza, mientras que Kubernetes la lee como cero. Esa cadena es exactamente lo que deja una plantilla cuando el valor que interpola está vacío: "{{ .infra.cpu }}m" con un cpu vacío se renderiza como m. Rechazarla convierte una entrada vacía en una detención que nombra el campo, en lugar de en una solicitud de tamaño cero que nada notifica.
Qué hace cada destino con una cantidad:
- helm emite cada cantidad tal cual, tras comprobar cada una con la forma anterior. Un valor fuera de ella detiene la compilación con un error que nombra el nodo, la ruta del campo en el Workload —
containers.main.resources.requests.cpu,initContainers[0].resources.limits.memory,volumes.data.persistent.size— y el valor. Consulta Helm Provider → Modo Workload (sintetizado). - compose convierte
cpuymemorya sus propias unidades a partir del valor analizado:cpusse convierte en un número decimal de núcleos (500m→0.5) ymemoryen un número exacto de bytes (1.5Gi→1610612736). Un valor que no es una cantidad detiene la compilación, y también la detiene una cantidad que compose no puede representar exactamente — una cantidad negativa, una cantidad de memoria que no es un número entero de bytes (1500m) o una cantidad de cpu más fina que nueve decimales de un núcleo — y el error indica cuál de los dos casos encontró. Un recuentonvidia.com/gpuse lee de la misma forma y se convierte en un número de dispositivos, así que uno que no es un número entero de dispositivos también detiene la compilación. compose no emite ningún otro recurso extendido ni ningún tamaño de volumen, por lo que no comprueba ninguno de los dos: cualquier otra clave de recurso extendido y unephemeral.sizeLimitse descartan con una advertencia, y un tamaño persistente no da forma a nada en su salida. Consulta Compose Provider → Recursos de los contenedores.
La comprobación solo juzga la forma. Si un clúster puede programar la cantidad, o si la cantidad es adecuada para su dispositivo, queda fuera de ella.
services
Un mapa ordenado de exposiciones de servicio. Cada servicio declara su tipo (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — hasta dónde llegan sus puertos — y un mapa de puertos con nombre. Los nombres de los puertos deben coincidir con los nombres de los puertos de contenedor declarados en otra parte del Workload:
services: http: type: ClusterIP ports: web: 8080 # must exist in containers.<name>.portsEs habitual tener varios servicios en un único Workload para exponer por separado el tráfico interno y el externo (ClusterIP interno para los consumidores dentro del clúster, LoadBalancer para el tráfico externo, ClusterIP para el scraping de Prometheus).
Hasta dónde llegan los puertos de un servicio. Lo indica el type, y cada destino lo renderiza en sus propios términos:
type | Alcance | helm | compose |
|---|---|---|---|
ClusterIP | los pares de la carga de trabajo, en la propia red del destino | un Service de tipo ClusterIP | no publica nada; los pares alcanzan el puerto en la red de compose |
Headless | lo mismo, sin dirección de clúster | un Service de tipo ClusterIP con clusterIP: None | no publica nada |
NodePort | más allá de la propia red del destino | un Service de tipo NodePort | cada puerto publicado en todas las interfaces del host, como <service port>:<container port> |
LoadBalancer | más allá de la propia red del destino | un Service de tipo LoadBalancer | lo mismo que NodePort |
Loopback | solo la propia dirección de loopback del host | detiene el build, indicando el servicio | cada puerto publicado en la dirección de loopback IPv4, como 127.0.0.1:<service port>:<container port> |
El número de un puerto de servicio y el puerto de contenedor que nombra son dos números, como lo son port y targetPort de un Service de Kubernetes: helm escribe el número de la entrada como el port del Service y apunta al puerto de contenedor por su nombre, y compose publica el número de la entrada en el host sobre el número del puerto de contenedor. Cuando los dos números son iguales, compose escribe ese número en ambos lados.
Loopback es para un puerto al que llega algo en la misma máquina — un navegador o un agente que se ejecuta en el host — y al que nada más debería llegar. En compose el enlace es únicamente la dirección de loopback IPv4: la dirección de loopback IPv6 ::1 no se enlaza, así que dirige el puerto como 127.0.0.1 en lugar de mediante un nombre que pueda resolverse a ::1. Un transporte declarado se escribe en la entrada como en cualquier puerto publicado, como en 127.0.0.1:5514:5514/udp.
Cuando dos entradas nombran el mismo puerto, gana el alcance más amplio: un puerto que publica una entrada NodePort o LoadBalancer se publica en todas las interfaces aunque una entrada Loopback también lo nombre, sea cual sea de las dos la que se declare primero.
En helm una entrada Loopback detiene el build en lugar de renderizarse como algo que no es. Un Service de Kubernetes no tiene ningún tipo que se enlace a la dirección de loopback de un host — en qué direcciones de nodo escucha un Service NodePort es una configuración de todo el clúster, no de un solo Service —, de modo que un Service ClusterIP perdería el alcance que pide la entrada, y uno NodePort publicaría el puerto en todas las direcciones de nodo que permita el clúster. La detención nombra el nodo y el servicio; consulta A service type the helm provider cannot render (Un tipo de servicio que el proveedor helm no puede renderizar).
Convención de nombres sintetizados. Cuando el proveedor helm sintetiza los servicios de un Workload, el metadata.name de cada Service se deriva de forma determinista del nombre que lleva el propio controlador de la carga de trabajo y de la clave de autoría del servicio. Para el Workload de un componente, ese nombre es el nombre de release del nodo: <release name>-<service-key>. El nombre de release es la identidad del componente escrita en el alfabeto que admite un nombre de Kubernetes — el mismo nombre con el que se renderiza un chart, legible en las plantillas de una Recipe como {{ .context.rendered_name }} —, por lo que es igual al instance_id siempre que la identidad no contenga guiones bajos ni mayúsculas. Un Workload que declara services.http en el nodo api-server produce un Service llamado api-server-http; el mismo Workload en el nodo billing produce billing-http, y en el nodo my_api produce my-zuapi-http. El nombre del archivo de salida sigue la misma convención: <release name>-<service-key>-service.yaml. Una Recipe que publica la dirección de un Service así la construye a partir de {{ .context.rendered_name }}, nunca de {{ .context.instance_id }}, que no nombra ningún Service siempre que los dos difieren — consulta ../templates/rendered-resource-names.md.
Un Workload que sintetiza la FeatureRecipe de una vinculación de Feature recibe el nombre de la identidad compuesta de la propia vinculación en lugar de un nombre de release: el valor que sus recursos llevan en su etiqueta aggrega.ai/component-id, compuesto a partir del componente anfitrión y de la clave escrita bajo features:, tras el cfr-- inicial. Un nombre de release derivado ahí sería el del anfitrión, y daría a los recursos de la vinculación el nombre de los del anfitrión. Así, una FeatureRecipe cuyo Workload declara services.scrape, para una vinculación stats en el nodo front-door, produce un Deployment cfr--front-door--stats y un Service cfr--front-door--stats-scrape. Ese primer segmento nunca es igual al instance_id, y ninguna clave del contexto de plantillas de la FeatureRecipe lo contiene: en las plantillas de una vinculación, {{ .context.rendered_name }} y {{ .context.instance_id }} nombran ambos al anfitrión (front-door) y {{ .attachment_name }} es solo la clave (stats), por lo que {{ .context.rendered_name }}-scrape nombra el propio Service scrape del anfitrión, donde el anfitrión declara uno, y nunca el de la vinculación — consulta ../templates/rendered-resource-names.md. El archivo de salida se sitúa tras el prefijo que lleva cada archivo que emite una vinculación — el nombre del anfitrión y el de la vinculación, cada uno seguido de -- —, de modo que ese Service se escribe en front-door--stats--cfr--front-door--stats-scrape-service.yaml.
La convención tiene dos consecuencias prácticas. Primero, las colisiones entre nodos son imposibles por construcción — el prefijo del nombre diferencia los servicios entre todos los nodos del límite, porque dos identidades distintas siempre dan lugar a dos nombres de release distintos, la identidad de una vinculación lleva tanto su anfitrión como su clave, y ningún nombre de componente puede empezar por cfr-- (el build se detiene ante uno que lo haga — consulta Component identity cannot be stamped on what it emits (La identidad del Component no se puede estampar en lo que emite)), de modo que dos Workloads que declaran cada uno services.http producen recursos Service de K8s distintos con nombres que no se solapan. El único residuo es una identidad de vinculación demasiado larga para el destino: se acorta en torno a un digest del conjunto, y dos identidades acortadas pueden en principio coincidir — consulta Etiquetas de procedencia emitidas en la salida renderizada. Segundo, un Workload no puede declarar dos veces una misma clave de servicio — un mapa services: que nombra una clave dos veces se rechaza al analizar el YAML del Workload, y el build se detiene indicando la clave y su línea.
El riesgo de colisión que sí permanece está en el límite de longitud de nombres de K8s: los nombres de Service de Kubernetes tienen un máximo de 63 caracteres, y la forma sintetizada <release name>-<service-key> puede superar ese límite cuando ambos segmentos son largos. El compilador de Aggrega no impone el límite; el build emite el Service, y Kubernetes lo rechaza cuando se aplica. Los autores con ID de instancia profundamente anidados (p. ej., data-layer.regional.eu-west.primary) y claves de servicio largas deberían mantener la longitud combinada por debajo de 63 caracteres. Lo mismo vale para el Workload de una vinculación: una identidad compuesta demasiado larga para el destino se acorta, pero la clave de servicio que se le añade no, de modo que un Service de una vinculación con una clave larga todavía puede superar los 63 caracteres y construirse sin detención.
Nota específica del Provider (compose). El proveedor compose deriva depends_on automáticamente de las aristas uses del IR. Esas entradas se emiten sin condición — tienen semántica service_started independientemente de que el destino declare un healthcheck —, de modo que un servicio cuyas dependencias provienen todas de aristas uses emite la lista en forma corta (depends_on: [<target>]). Condicionar una entrada derivada de una arista a la salud del destino no está implementado. La forma larga se emite donde una entrada sí lleva una condición, que es como se expresa una espera sobre un contenedor de inicialización; consulta providers/compose.md.
Protocolos de transporte de los puertos
Un puerto de contenedor se escribe en una de dos formas equivalentes. El número solo es la forma corta y no declara ningún transporte, de modo que el destino aplica su propio valor predeterminado — TCP en todo destino que tenga uno:
containers: main: image: "{{ .values.image }}" ports: web: 8080La forma expandida lleva juntos el número y el transporte, y es lo que necesita un puerto cuando transporta algo distinto de ese valor predeterminado:
containers: main: image: "{{ .values.image }}" ports: web: 8080 # short form — no transport declared dns: port: 53 protocol: UDP # TCP | UDP | SCTP sigtran: port: 2905 protocol: SCTPLas dos formas pueden mezclarse libremente dentro de un mismo mapa ports, y un puerto sin transporte que declarar se queda en la forma corta.
El transporte se declara una sola vez, en el puerto de contenedor. Una entrada services.<service>.ports nombra un puerto de contenedor y toma consigo el transporte de ese puerto, de modo que una exposición de servicio no puede discrepar del puerto que abrió el contenedor. No existe una clave protocol en un puerto de servicio, y escribir una se rechaza.
Por qué existe el campo. Los destinos de despliegue tratan un transporte no especificado como el de flujo. Un componente que necesita un puerto de datagramas — medios en tiempo real, telefonía, resolución de nombres, redes privadas, un servidor de juegos — podría, de lo contrario, declarar solo el número, y la pila se desplegaría superando todos los controles mientras ningún cliente se conecta, porque el tráfico es de datagramas y el puerto que se abrió no lo es. Declarar el transporte es lo que hace que esto sea expresable.
El compilador no interpreta el valor. No deduce ningún transporte del nombre de un puerto ni comprueba el transporte declarado frente a lo que realmente habla el proceso detrás del puerto: el valor es un dato que tú declaras y que el motor del destino emite. Un puerto llamado dns sin clave protocol es un puerto TCP, y un puerto llamado web que declara protocol: UDP es un puerto UDP.
Comportamiento por destino.
| Destino | Un puerto sin transporte declarado | Un transporte declarado |
|---|---|---|
| helm | containerPort y el puerto del Service no llevan clave protocol | se emite tal cual como protocol: en el puerto de contenedor y en cada puerto de Service que lo nombra |
| compose | se publica como <host>:<container>, sin cambios | se publica como <host>:<container>/tcp o /udp; SCTP no tiene escritura en compose y detiene el build en lugar de publicar un puerto que llevaría un transporte distinto |
Un puerto de contenedor que ningún servicio publica no llega a ninguna parte de un archivo compose — ese es el comportamiento habitual de compose para los puertos de contenedor —, de modo que un transporte declarado en un puerto así no tiene dónde escribirse y no provoca una detención.
Sondas de salud — forma de intención
Cada contenedor declara sus sondas bajo su propia clave health: (containers.<name>.health), en una forma de intención abstracta; el Workload no tiene un health de nivel superior. Cada proveedor traduce la intención a su forma de sonda nativa en el momento de la síntesis.
health: ready: http: /healthz # intent: HTTP GET probe timeoutSeconds: 5 live: tcp: 8080 # intent: TCP socket check timeoutSeconds: 5 startup: exec: ["check-ready.sh"] # intent: command exec timeoutSeconds: 30 periodSeconds: 10Tres formas de intención (http:, tcp:, exec:) son mutuamente excluyentes dentro de una misma declaración de sonda. La resolución del puerto para http: sin un puerto explícito toma el primer nombre de puerto, en orden alfabético, que el contenedor declara bajo containers.<name>.ports — la misma regla en ambos destinos, de modo que una sonda lee el mismo puerto sea cual sea el que la renderice. Un contenedor que no declara ningún puerto con nombre no puede llevar una sonda HTTP: el build se detiene con un error de traducción que nombra la sonda en cuestión.
Traducción por proveedor. Cada proveedor traduce la intención de sonda abstracta a su forma nativa en el momento de la síntesis:
| Intención | Helm (K8s) | Compose | Notas sobre pérdidas |
|---|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" | Compose carece de una forma nativa de sonda HTTP; el envoltorio CMD-SHELL depende de que curl esté presente en la imagen del contenedor. |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" | Compose carece de una forma nativa de sonda TCP; el envoltorio CMD-SHELL depende de que nc esté presente en la imagen del contenedor. |
exec: [cmd, ...] | exec.command: [cmd, ...] | CMD [cmd, ...] | Correspondencia uno a uno; ambos proveedores llevan la lista de comandos tal cual. |
Los envoltorios CMD-SHELL de Compose aproximan las sondas HTTP y TCP mediante predicados evaluables por la shell. Lo que le falta a compose es la forma de sonda nativa, no los campos de temporización: los periodSeconds, timeoutSeconds, failureThreshold e initialDelaySeconds escritos por el autor se trasladan al healthcheck como interval, timeout, retries y start_period — la sección «Sondas» de providers/compose.md recoge la correspondencia campo por campo. La forma nativa exec: no necesita ningún envoltorio y se traduce uno a uno en ambos destinos.
Una sonda envuelta se traduce en silencio: nada en el docker-compose.yaml emitido la marca, y ningún diagnóstico informa del envoltorio. Lo que el build sí informa en esta ruta es una ranura de sonda que no llega a ninguna salida — un servicio de compose lleva un solo healthcheck, así que, cuando un Workload declara más de una de ready:, live: y startup:, solo se traduce la ranura preferida (live antes que ready antes que startup) y una advertencia unsupported-field nombra la ranura traducida y las ranuras descartadas.
Nota específica del Provider (compose). Escribir un bloque health: en un Workload destinado a compose no condiciona el orden de depends_on a la salud: las entradas depends_on del proveedor compose derivadas de aristas uses: usan siempre la semántica service_started, independientemente de que el Workload de destino declare sondas de salud. Condicionar esas entradas a la salud del destino no está implementado — la forma larga que llevaría una condición así se emite ella misma, para las esperas sobre contenedores de inicialización, de modo que lo que falta es la elección de condicionar una arista a la salud, no la forma de expresarlo. Consulta providers/compose.md para ver todas las reglas de inferencia.
Campos de paso directo con forma de K8s — scheduling, serviceAccount, podSecurityContext
El esquema de Workload acepta tres campos opcionales de nivel superior que existen principalmente para hacer pasar primitivas nativas de Kubernetes a través del proveedor helm conservando la forma estructural de Aggrega. El proveedor compose traduce el subconjunto que tiene un análogo en Compose e ignora el resto emitiendo una advertencia. Aggrega valida la forma externa pero no vigila el contenido interno (consulta Superficie de validación más abajo) — los valores internos nativos de K8s pasan tal cual al pod spec renderizado por helm.
scheduling
scheduling agrupa cuatro primitivas de planificación nativas de K8s — nodeSelector, affinity, tolerations, topologySpreadConstraints — en un único bloque organizado por propósito. Cada subcampo tiene exactamente la forma del campo correspondiente del pod spec de Kubernetes:
apiVersion: aggrega.ai/v1beta1kind: Workloadscheduling: nodeSelector: disktype: ssd region: us-east-1 tolerations: - key: dedicated operator: Equal value: gpu-workloads effect: NoSchedule affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: { app: "{{ .context.instance_id }}" } topologyKey: kubernetes.io/hostname topologySpreadConstraints: - maxSkew: 1 topologyKey: topology.kubernetes.io/zone whenUnsatisfiable: ScheduleAnywaycontainers: app: { image: "..." }Traducción por el Provider. El proveedor helm pasa cada subcampo tal cual al pod spec renderizado. El proveedor compose no traduce ninguno de los cuatro: omite todo el bloque scheduling, y una advertencia lo nombra.
serviceAccount
serviceAccount es una cadena simple que lleva el nombre de la ServiceAccount con la que se ejecuta la carga de trabajo:
apiVersion: aggrega.ai/v1beta1kind: WorkloadserviceAccount: "{{ .context.rendered_name }}-runner"containers: app: { image: "..." }El nombre se construye a partir de {{ .context.rendered_name }}, el nombre de release con el que el proveedor helm nombra los recursos propios de la carga de trabajo, de modo que es un nombre que el clúster acepta se llame como se llame el componente. El campo hace referencia a una ServiceAccount existente; no crea ninguna. Los recursos RBAC que la acompañan (el propio objeto ServiceAccount, más Role / RoleBinding / ClusterRole / ClusterRoleBinding) deberían entregarse por uno de dos canales:
artifacts:de la Recipe — cuando el RBAC es intrínseco a esta Recipe (la Recipe sabe que necesita un Role concreto para una tarea concreta).- Features con generación de recursos — cuando el RBAC es transversal (una FeatureRecipe de Workload-Identity que vincula ServiceAccounts ligadas a IAM a cada componente con una etiqueta determinada).
Establecer serviceAccount: sin asegurarse de que la ServiceAccount nombrada exista produce un error de K8s en tiempo de ejecución al aplicar, no un error en tiempo de build — la validación del esquema de la carga de trabajo no comprueba la existencia de la ServiceAccount (no hay acceso al estado del clúster en tiempo de compilación, según el invariante de pureza AOT).
El proveedor compose ignora serviceAccount: con una advertencia; Compose no tiene un concepto equivalente de vinculación de identidad.
podSecurityContext
podSecurityContext lleva primitivas de seguridad a nivel de pod — UID, GID, fsGroup, supplementalGroups — que se aplican a cada contenedor del pod:
apiVersion: aggrega.ai/v1beta1kind: WorkloadpodSecurityContext: runAsUser: 1000 runAsGroup: 3000 fsGroup: 2000 supplementalGroups: [4000, 5000]containers: app: { image: "..." }Semántica de los campos. Los cuatro campos son enteros (UID/GID numéricos, no cadenas); runAsUser y runAsGroup fijan el UID/GID efectivo de los procesos del contenedor; fsGroup fija el grupo propietario de los volúmenes montados en el pod; supplementalGroups añade GID adicionales al grupo de procesos de cada contenedor.
Traducción por el Provider. El proveedor helm pasa el bloque tal cual al pod spec renderizado. El proveedor compose no tiene equivalente para fsGroup ni supplementalGroups y omite cada uno con una advertencia; runAsUser/runAsGroup se traducen a la forma de Compose user: 1000:3000 en cada servicio que produce el Workload, sidecars y contenedores de inicialización incluidos, y un runAsGroup sin un runAsUser al lado se omite con una advertencia. Cada contenedor y contenedor de inicialización lleva además su propio securityContext — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation, y capabilities.add / capabilities.drop. El proveedor helm lo emite en el contenedor; el proveedor compose emite readOnlyRootFilesystem como read_only, capabilities.add / capabilities.drop como cap_add / cap_drop, y runAsUser / runAsGroup como el propio user del contenedor, que ocupa el lugar del del pod; omite runAsNonRoot, allowPrivilegeEscalation y un runAsGroup escrito sin un runAsUser, con una advertencia cada uno, y también advierte cuando el propio runAsUser de un contenedor deja fuera el runAsGroup del pod. providers/compose.md recoge la correspondencia campo por campo.
Cargas de trabajo con GPU y dispositivos
Una carga de trabajo que necesita hardware especializado — una GPU u otro dispositivo proporcionado por un fabricante — expresa dos aspectos independientes: el runtime a nivel de pod que expone el nodo habilitado para el dispositivo (runtimeClassName), y la cantidad del dispositivo por contenedor que reclama la carga de trabajo (una clave de recurso extendido bajo resources de un contenedor). Una carga de trabajo con GPU típica declara ambos a la vez, pero cada uno se sostiene por sí solo y cualquiera de los dos puede aparecer sin el otro.
Ambos campos describen cómputo — el pod y el contenedor que se ejecuta en el dispositivo —, así que pertenecen a una carga de trabajo que ejecuta contenedores. Una carga de trabajo que solo lleva un endpoint externo y no declara contenedores propios no tiene ningún pod ni contenedor al que vincularlos: establecer runtimeClassName en una carga de trabajo así, solo de endpoint, detiene el build, nombrando runtimeClassName y la Recipe cuyo Workload lo declaró, y sin contenedores no hay dónde colocar una solicitud de recurso de dispositivo.
runtimeClassName
runtimeClassName es una única cadena que nombra la RuntimeClass con la que se ejecuta el pod — el runtime de contenedores que expone un nodo habilitado para el dispositivo, por ejemplo un runtime de GPU llamado nvidia. Es un selector a nivel de pod: se aplica a cada contenedor de la carga de trabajo. El compilador pasa el nombre tal cual como un puntero determinista; el clúster lo resuelve, en el momento de la planificación, a una RuntimeClass que su administrador ha configurado. Aggrega no comprueba que exista una RuntimeClass coincidente — no tiene acceso al estado del clúster en tiempo de compilación —, de modo que un nombre sin RuntimeClass configurada aparece como un error de planificación al aplicar, no como un error en tiempo de build.
Claves de recursos extendidos
Los resources.requests y resources.limits de un contenedor llevan las cantidades ordinarias cpu y memory y, junto a ellas, claves de recursos extendidos: cantidades de dispositivos con ámbito de fabricante o de dominio, identificadas por un nombre completamente calificado <domain>/<name> como nvidia.com/gpu o amd.com/gpu. El segmento de dominio lleva al menos un punto, y ese punto es lo que distingue una clave extendida (nvidia.com/gpu) de las cantidades simples cpu y memory. Cada valor es una cantidad en forma de cadena ("1", "2") que el compilador pasa tal cual, y el proveedor helm comprueba su forma antes de emitirla (consulta Cantidades de recursos); el device plugin del clúster resuelve y asigna el dispositivo en el momento de la planificación.
Ejemplo práctico — una carga de trabajo de inferencia con GPU
apiVersion: aggrega.ai/v1beta1kind: WorkloadruntimeClassName: nvidiacontainers: inference: image: "{{ .values.image }}" resources: requests: cpu: "2" memory: "8Gi" nvidia.com/gpu: "1" limits: nvidia.com/gpu: "1"La carga de trabajo selecciona el runtime nvidia para su pod y reclama una GPU para el contenedor inference. La cantidad de GPU aparece tanto en requests como en limits: un dispositivo no admite sobreasignación, así que su solicitud y su límite se fijan en el mismo valor.
Traducción por el Provider. Son conceptos nativos de Kubernetes. El proveedor helm emite runtimeClassName en el pod spec renderizado y cada clave de recurso extendido tal cual bajo resources.requests / resources.limits del contenedor, de modo que llegan al clúster a través de la salida de Kubernetes. El proveedor compose reserva un recuento de nvidia.com/gpu como otras tantas GPU NVIDIA en el servicio del contenedor (consulta Compose Provider → Recursos de contenedor); un único host no tiene concepto de runtime class ni análogo para ninguna otra clave de recurso extendido, de modo que una carga de trabajo que declara runtimeClassName u otra clave se renderiza en un destino compose sin ella.
Ejecución en la red del nodo
De forma predeterminada, una carga de trabajo se ejecuta en un espacio de nombres de red propio: sus contenedores solo ven sus propias interfaces, y el tráfico les llega a través de la traducción de direcciones del destino. hostNetwork: true solicita la otra disposición: la carga de trabajo se ejecuta en el propio espacio de nombres de red del nodo, de modo que ve las interfaces del nodo y los puertos que abren sus contenedores son accesibles en las propias direcciones del nodo, sin ninguna traducción intermedia.
Eso es lo que necesita toda una clase de software. Los medios en tiempo real, la telefonía, las redes privadas virtuales y el tráfico similar llevan la dirección del par dentro de la carga útil, por lo que una dirección reescrita en tránsito llega describiendo un lugar al que el par no puede llegar; ejecutarse en las direcciones del nodo es lo que mantiene la coherencia entre ambas.
apiVersion: aggrega.ai/v1beta1kind: WorkloadhostNetwork: truecontainers: media: image: "{{ .values.image }}" ports: rtp: port: 7881 protocol: UDPQué declara y qué no
hostNetwork elige un espacio de nombres de red, y eso es todo.
- No declara puertos. Los puertos que abre una carga de trabajo se siguen declarando en
containers.<name>.ports, exactamente igual que sin él, y siguen significando lo mismo. DeclararhostNetworkno añade ningún puerto ni elimina la necesidad de declarar uno. - No declara ningún número de puertos. Una aplicación que quiere muchos puertos contiguos (un servidor multimedia que dimensiona un rango según el número de procesadores de una máquina, por ejemplo) configura ese rango en su propio cuerpo de configuración, a partir de valores que proporciona su operador, del mismo modo en que configura cualquier otra cosa que lee al arrancar. Es un ajuste de la aplicación y no de la carga de trabajo, y el contrato de la carga de trabajo no es donde reside.
- No se infiere nada. El compilador no lee ningún significado en el valor ni lo deriva de ninguna otra cosa: ni del nombre de un puerto, ni del tipo o las etiquetas de un componente, ni de cuántos puertos se declaran. Una carga de trabajo se ejecuta en la red del nodo cuando, y solo cuando, lo indica.
Como describe recursos de cómputo, hostNetwork corresponde a una carga de trabajo que ejecuta contenedores. Una carga de trabajo que solo lleva un endpoint externo no declara contenedores, por lo que no tiene ningún espacio de nombres de red que elegir: declarar hostNetwork en una carga de trabajo con solo un endpoint detiene la compilación, indicando hostNetwork y la Recipe cuyo Workload lo declaró.
Traducción por el Provider
El proveedor helm emite hostNetwork: true en la especificación del pod renderizada, que es como Kubernetes expresa la misma elección. La declaración llega a la especificación del pod y a nada más: los Services emitidos son idénticos con ella y sin ella.
El proveedor compose emite network_mode: host en el servicio propio de la carga de trabajo. De cómo compose modela las redes se deriva una consecuencia: un servicio en ese modo no está conectado a la red del límite, porque compose trata la conexión a una red y la adopción del espacio de nombres del host como alternativas y no como adiciones. Por eso sus pares lo alcanzan en las propias direcciones del host en lugar de por el nombre del servicio (que es lo que significa la red del host en cualquier destino), y ningún otro servicio del límite se ve afectado.
Dos formas se combinan con él en ese destino. Un contenedor sidecar sigue al servicio principal a la red del host sin declarar nada, porque toma el espacio de nombres del servicio principal al nombrarlo. Un contenedor de inicialización no lo hace: se convierte en un servicio al que espera el servicio principal, por lo que se une a la red del límite por derecho propio en lugar de adoptar un espacio de nombres que haría circular esa espera. Por tanto, una carga de trabajo que declara tanto hostNetwork como initContainers ejecuta su propio servicio en la red del nodo mientras sus servicios de inicialización permanecen en la red del límite: una disposición más estrecha que el único espacio de nombres compartido que ofrece la forma de pod, y que el proveedor compose señala en una advertencia unsupported-field en lugar de dejar que se descubra en tiempo de ejecución.
Una carga de trabajo que no declara hostNetwork no lleva esa clave en su salida: la clave está ausente en lugar de emitirse como false.
Integración de las vinculaciones con el featuresSchema del Component
El bloque containers.<name>.attachments del Workload hace referencia a slots de credenciales declarados en el featuresSchema del Component (o, para una entrada que nombra una conexión, a un slot que declara el socket de esa conexión; consulta Entregar una credencial que lleva una conexión); no declara slots nuevos. Consulta ../entities/component.md para la superficie de autoría de featuresSchema. from nombra el slot; no es el nombre del Secret generado.
Una entrada containers.<name>.attachments se renderiza como una referencia a un recurso Secret (un secretKeyRef de Kubernetes para as: env o un volumen respaldado por un secret para as: file), y ambos apuntan al Secret por nombre. El sintetizador resuelve ese nombre y la clave de datos a partir de los provides expuestos del slot: el secretKeyRef.name renderizado de la entrada es el .features.<slot>.provides.name del slot y la clave de datos es .features.<slot>.provides.key. El autor de la Recipe escribe solo from: <slot> y as: env; el sintetizador lee los provides resueltos y no vuelve a derivar el nombre. Es la misma lectura de .features.<slot>.provides.<key> que usa una Recipe source para un existingSecret: un único slot de credenciales alimenta de forma idéntica a un consumidor Recipe source y a un consumidor Workload sintetizado (simetría source/workload).
Cuatro reglas de validación rigen la integración:
- Cada valor
attachments.<KEY>.fromdebe coincidir con un nombre de slot declarado en elfeaturesSchemadel Component o, en una entrada que nombra una conexión, en el socket de esa conexión. Un nombre de slot desconocido es un error en tiempo de carga. - El mecanismo de entrega
as:(envofile) debe figurar en la lista de permitidosinject:del slot que declara el Component. Un Workload que declaraas: filepara un slot cuya entrada defeaturesSchemaespecificainject: [env]es un error en tiempo de carga. - Los slots marcados con
inject: [](entrega de caja negra) en elfeaturesSchemadel Component no pueden aparecer en absoluto en los bloquesattachments:de un Workload. Esos slots los entrega la fontanería interna de la Recipe (el parámetroexistingSecretde un chart de Helm, por ejemplo), no la exposición en el Workload. - El slot referenciado debe ser referenciable: su relleno debe publicar un localizador
provides(name,key) para un recurso Secret, uno que emita su realización o uno que ya exista. Un slot rellenado por una credencial entregada por inject (una que escribe un valor en la tubería de inject y no publica ningún localizador) no tiene nada a lo que apuntar; hacer referencia a él desde una entradaattachments:de un Workload es un error en tiempo de carga. Una credencial entregada por inject llega al contenedor a través de la tubería de inject del slot (una entradavariablesque lee.context.inject.env.<KEY>), no a través de una entradaattachments:.
Nota sobre el Provider. Helm renderiza la referencia secretKeyRef/volumen secret descrita arriba. El proveedor compose no tiene una primitiva nativa de entorno desde un secret; una entrada de vinculación as: env en un Workload destinado a compose se renderiza como una entrada de entorno con un valor vacío y una advertencia que nombra la entrada (consulta la página del proveedor compose), mientras que la regla de referenciabilidad (agnóstica respecto a las capacidades) sigue aplicándose.
Ejemplo:
# In the Component catalog entityspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipe's Workloadworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected at load time: blackbox slotEntregar una credencial que lleva una conexión
El socket de un Component puede declarar, en usesSchema.<socket>.featuresSchema, los slots que rellena cada conexión cableada a través de él, de modo que un componente que alcanza varios destinos tiene una credencial por conexión en lugar de una para todas. Una vinculación de ese tipo no está entre las .features propias del componente; se encuentra bajo su conexión, en .context.uses.<alias>.features.<slot>. Una entrada del Workload la entrega nombrando la conexión junto al slot:
- en una entrada
attachmentsde un contenedor,connection: <alias>junto afrom: <slot>; - en una entrada
envFromde un contenedor,connection: <alias>junto asecret: <slot>;connectionsolo se acepta junto asecret.
Ambas formas se aceptan en cada contenedor y en cada contenedor de inicialización. <alias> es el nombre con el que la conexión está escrita en el bloque uses del componente, en el Aggregate o en la Release (la clave con la que una Recipe lee la conexión bajo .context.uses), y <slot> es un slot que declara el socket a través del cual está cableada esa conexión.
Antes de que cualquiera de las reglas anteriores lea el Workload, cada entrada que nombra una conexión se reescribe con el nombre que adopta en el componente la vinculación que esa conexión lleva en ese slot: el alias, un punto y el slot (gpt.credential). Después, cada regla se ejecuta sobre la entrada reescrita exactamente como se ejecuta sobre una entrada que nombra uno de los slots propios del Component: la lista de permitidos inject: del slot del socket rige as:, un slot del socket que declara inject: [] no puede ser referenciado, la vinculación que lo rellena debe ser referenciable, y el proveedor resuelve el nombre del Secret y la clave de datos a partir de los provides resueltos de esa vinculación, de modo que la entrada de cada conexión hace referencia a la credencial propia de esa conexión. Un slot del socket que declara sensitive: true se lee para la entrada exactamente como se lee la declaración de un slot del Component. La entrada reescrita es lo que recibe el proveedor; la clave connection no llega a él.
Se rechazan tres entradas, cada una indicando lo que nombró:
- una entrada que nombra una conexión que el componente no traza: el rechazo nombra la conexión, el slot y las conexiones que el componente sí traza;
- una entrada que nombra un slot que el socket de la conexión no declara: el rechazo nombra el slot, la conexión, el socket y los slots que declara;
- una entrada que escribe ella misma el nombre compuesto (
from: gpt.credential). El slot de una conexión se nombra nombrando la conexión, por lo que el nombre compuesto nunca es una segunda forma de llegar a él.
Una conexión que no lleva ninguna vinculación en el slot deja la entrada sin nada a lo que hacer referencia, y la regla de referenciabilidad la rechaza. Un Workload que renderiza una FeatureRecipe está limitado a los slots que declara la Feature que implementa, que no alcanzan ninguna de las conexiones del componente anfitrión, por lo que una entrada allí que nombra una conexión se rechaza por nombrar una que el componente no traza.
Ejemplo:
# In the Component catalog entityspec: usesSchema: models: featuresSchema: credential: sensitive: true inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`# through the `models` socket, each carrying its own `credential`workload: | containers: main: attachments: MODEL_KEY_GPT: from: credential connection: gpt as: env MODEL_KEY_NIM: from: credential connection: nim as: envEn helm, MODEL_KEY_GPT se renderiza como un secretKeyRef que nombra el Secret que publicó la credencial de la conexión gpt, y MODEL_KEY_NIM el que publicó la de la conexión nim. En compose, una entrada as: env que nombra una conexión se emite con un valor vacío y el mismo aviso de compatibilidad parcial que recibe una entrada que nombra uno de los slots propios del Component.
Superficie de validación
Cada Workload se valida en el momento de carga de la Recipe, antes de que se ejecute ningún renderizado. La validación tiene dos etapas:
- Validación del esquema. El valor del Workload se unifica con el esquema de Workload
aggrega.ai/v1beta1incrustado. Los errores incluyen la ruta del campo y la restricción infringida (por ejemplo,.containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). La validación del esquema impone cada tipo, enumeración, rango y disyunción declarados en el esquema, incluidos elformde controlador de conjunto cerrado (uno destateless,stateful,daemon,scheduled,task,reference), eltypede servicio de conjunto cerrado (uno deClusterIP,Headless,NodePort,LoadBalancer,Loopback), el rango entero de puertos (1..65535), la disyunción de forma de sonda (exactamente uno dehttp,tcp,exec) y la disyunción de variante de volumen (exactamente uno deephemeral,configmap,secret,persistent,persistentTemplate). - Validación de referencias cruzadas. Las referencias de vinculación del Workload se comprueban contra el
featuresSchemadel Component —y, para una entrada que nombra una conexión, contra los slots que declara el socket de esa conexión— (pertenencia al slot, lista de permitidos de entregaas:, exclusión de caja negra) y contra los provides resueltos de cada slot referenciado (referenciabilidad: el relleno debe publicarname/key). Son comprobaciones entre entidades que una validación basada solo en el esquema no puede realizar.
Ambas etapas producen la misma forma de mensaje con el prefijo CATALOG_ERROR; los fallos detienen la compilación antes de que se produzca ninguna salida de renderizado. Los autores de Recipe reciben información precisa que identifica el campo exacto que falló y la restricción que lo rechazó.
Los campos de paso directo con forma de K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, las listas items dentro de los volúmenes ConfigMap y Secret, los hooks de ciclo de vida httpGet) solo se validan estructuralmente: el esquema de Aggrega restringe su presencia y su forma externa, pero la forma interna de estos valores definidos por la API de K8s es responsabilidad del proveedor (el proveedor helm los pasa tal cual a la especificación del pod de K8s; el proveedor compose los rechaza o los degrada según corresponda). Un Workload que usa un valor affinity mal formado supera la validación de Aggrega, y el error aparece en cambio durante la síntesis del proveedor.
Del mismo modo, las cantidades de recursos son cadenas para el esquema: ninguna de las dos etapas comprueba su forma. Lo hace el proveedor que sintetiza, sobre el Workload evaluado, y se detiene ante un valor que no tiene forma de cantidad; consulta Cantidades de recursos.
Los recursos auxiliares van fuera del Workload
El Workload describe solo la forma de la carga de trabajo: contenedores, volúmenes, servicios, réplicas, planificación, contexto de seguridad, cuenta de servicio. No tiene ningún campo additionalResources ni declaraciones en línea de ConfigMap / Secret / CRD.
Los autores de Recipe emiten recursos auxiliares por dos canales externos al Workload:
artifacts:a nivel de Recipe: para recursos intrínsecos a esta Recipe (un ConfigMap específico al que hace referencia el Workload de la Recipe, un registro puntual de CRD que la Recipe necesita). El campo es un mapa de entradas con nombre; cada entrada se escribe en línea o se carga mediante un$import:por entrada. Consulta la sección sobre el mecanismo de artefactos en ../../architecture/16-recipe-input-composition.md para conocer los tres modos de autoría.- Features con generación de recursos: para aspectos transversales vinculados mediante los selectores de la Release (una Feature ServiceMonitor vinculada a cada componente con métricas expuestas, una Feature NetworkPolicy vinculada a cada carga de trabajo de producción). Consulta ../entities/featurerecipe.md para la superficie de autoría de la FeatureRecipe.
El Workload se mantiene centrado en la forma de la carga de trabajo; los manifiestos auxiliares transversales y los intrínsecos a la Recipe tienen sus propios lugares de autoría.
Patrones comunes de Workload
El esquema de Workload es amplio: abarca servidores HTTP de un solo contenedor, patrones sidecar de varios contenedores, cadenas de contenedores de inicialización, trabajos por lotes y servicios con estado con volúmenes persistentes. Tres patrones se repiten con la frecuencia suficiente como para que escribir el código repetitivo desde cero en cada Recipe sea un desperdicio. Los bloques siguientes son plantillas para copiar y pegar que los autores de Recipe pueden adaptar a componentes concretos.
Un patrón que comparten varias Recipes puede publicarse una vez como entrada de una WorkloadLibrary e importarse con $import: <Library>#/workloads/<entry>; las plantillas de aquí son puntos de partida para adaptar, o para publicar de ese modo.
Patrón 1: servidor con exposición de métricas
Una aplicación web típica que sirve tráfico de la aplicación en un puerto y expone métricas recogidas por Prometheus en un puerto separado. Dos servicios en el Workload (uno para la aplicación y otro para las métricas) mantienen la política de la malla de servicios y la configuración del balanceador de carga claramente separables.
apiVersion: aggrega.ai/v1beta1kind: Workloadreplicas: {{ optional .infra `replicas` 2 }}containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} metrics: {{ optional .values `metrics_port` 9090 }} variables: LOG_LEVEL: "{{ optional .values `log_level` "info" }}" health: ready: http: /healthz timeoutSeconds: 5 live: http: /healthz timeoutSeconds: 5services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }} metrics: type: ClusterIP ports: metrics: {{ optional .values `metrics_port` 9090 }}El servicio de métricas suele anotarse para el descubrimiento por Prometheus mediante una vinculación de Feature en la superficie de la Release (p. ej., feature.aggrega.ai/prometheus-scrape: "true"); el propio Workload se mantiene libre de anotaciones de recolección específicas del proveedor.
Patrón 2: trabajo por lotes
Una carga de trabajo que se ejecuta hasta completarse en lugar de servir tráfico indefinidamente. El patrón establece form: task, omite por completo services: (los trabajos por lotes no exponen puertos) y se apoya en la forma de tarea del proveedor de destino (un Job de Kubernetes en el proveedor helm; el proveedor compose no tiene forma de tarea y se detiene ante form: task). El proveedor helm fija una restartPolicy de pod válida para un Job (Never salvo que el contenedor declare OnFailure), ya que un pod de Job no puede usar el valor predeterminado Always.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: taskcontainers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"] args: - "--config" - "/etc/config/job.yaml" variables: JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}" volumeMounts: - name: config path: /etc/configvolumes: config: configmap: source: "{{ .context.instance_id }}-config"El volumen de configuración hace referencia a un ConfigMap que se espera que la Recipe emita junto al Workload mediante artifacts: (consulta «Los recursos auxiliares van fuera del Workload» más arriba); el propio Workload solo declara el lado del consumo. La identidad le da nombre en un proveedor que nombra la carga de trabajo según la identidad, como hace compose; con helm, que nombra los recursos de la carga de trabajo según el nombre de la release de helm, construye en su lugar el nombre del ConfigMap (aquí y en el artefacto) a partir de {{ .context.rendered_name }}, para que sea uno que el clúster acepte se llame como se llame el componente.
Patrón 3: par con sidecar
Un pod de dos contenedores en el que el contenedor principal se encarga de la lógica de la aplicación y el sidecar de un aspecto transversal (terminación TLS, envío de registros, proxy de la malla de servicios, guardarraíl de IA). El orden de autoría en containers: es determinante: el proveedor helm emite los contenedores en el orden declarado; la primera clave (aquí, main) es el contenedor de destino predeterminado para kubectl logs y herramientas similares.
apiVersion: aggrega.ai/v1beta1kind: Workloadreplicas: {{ optional .infra `replicas` 2 }}containers: main: image: "{{ .values.app_image }}" ports: app: {{ optional .values `app_port` 8080 }} variables: UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}" sidecar: image: "{{ .values.sidecar_image }}" ports: proxy: {{ optional .values `proxy_port` 9000 }} variables: PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"services: external: type: ClusterIP ports: proxy: {{ optional .values `proxy_port` 9000 }}El Service expone el puerto del sidecar (no el del contenedor principal) y enruta el tráfico externo a través del sidecar hacia el contenedor principal mediante localhost. Los dos contenedores comparten el espacio de nombres de red del pod, por lo que localhost:<port> llega directamente al contenedor par. Para los sidecars que necesitan inyección de credenciales (el patrón canónico del guardarraíl de IA), la credencial suele estar en el bloque attachments: del sidecar en lugar del del contenedor principal, lo que mantiene la credencial circunscrita al perímetro del proceso del sidecar.
Elección del patrón
Los tres patrones corresponden a aspectos distintos de la forma de entrega:
- Servidor con métricas: servicios de larga duración que el clúster mantiene activos; varias exposiciones de Service para separar el tráfico.
- Trabajo por lotes: ejecución acotada; sin exposición de Service; se apoya en un ConfigMap emitido por la Recipe o en un estado externo para la entrada.
- Par con sidecar: pod de varios contenedores con espacio de nombres de red compartido; el Service del sidecar expone el aspecto transversal.
Un cuarto patrón, el servidor con estado con volumen persistente, establece form: stateful y declara almacenamiento por réplica mediante volumes.<name>.persistentTemplate; el proveedor helm emite un StatefulSet para la forma con estado (consulta providers/helm.md). El patrón tiene una forma idéntica a «servidor con métricas» con form: stateful, un volumen persistentTemplate adicional y exactamente un servicio type: Headless que gobierne el StatefulSet (sin él la compilación se detiene); los autores que lo necesiten adaptan el Patrón 1 con las tres declaraciones.
Referencias cruzadas
- ../../architecture/16-recipe-input-composition.md: función arquitectónica del tipo Workload y superficie completa del esquema.
- ../entities/recipe.md: cómo se compone
workload:con los otros dos tipos de entrada de la Recipe. - ../entities/component.md: autoría de
featuresSchemaa la que hacen referencia los bloquesattachments:del Workload. - ../entities/featurerecipe.md: recursos auxiliares a nivel de Feature que acompañan a los Workloads.
- ../vocabulary/data-pillars.md: contrato de acceso a los pilares para la evaluación de plantillas.
- ../templates/expansion-matrix.md: dónde encaja la evaluación del Workload en la matriz de evaluación de plantillas.