Workload
Il ruolo architetturale del tipo Workload — perché esiste, come si compone con gli altri due tipi di input delle Recipe (sourced e artifacts) e l’intera superficie dello schema — si trova in ../../architecture/16-recipe-input-composition.md. Questa pagina tratta la superficie di authoring del Workload: come un autore di Recipe scrive il contenuto di un Workload, che cosa valuta il compilatore e quando, come i campi del Workload interagiscono con il featuresSchema del Component e quali pilastri possono leggere i template all’interno di un Workload.
Dove si scrive
Il contenuto del Workload si scrive inline o da file, all’interno di una Recipe o di una FeatureRecipe (vedi FeatureRecipe). Una Recipe dichiara al massimo un workload:; allo stesso modo una FeatureRecipe ne dichiara al massimo uno proprio:
# Inline (block scalar)spec: workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload # ...oppure
# File-loaded via $import: (path relative to the Recipe directory)spec: workload: $import: ./workload/workload.yamlEntrambe le forme producono lo stesso oggetto Workload dopo il parsing; la scelta è una questione di ergonomia di authoring. Una terza forma importa un Workload condiviso tra più Recipes da una voce di una WorkloadLibrary, tramite la sua identità a nome semplice: $import: <Library>#/workloads/<entry>. Secondo il vocabolario unificato di importazione di file, $import: accetta una singola sorgente — vedi ../vocabulary/cross-document-ref.md per la distinzione più ampia tra $ref: / $import:.
Lo YAML del Workload non si scrive come entità di catalogo autonoma. Non esiste alcuna directory catalog/workload/; la grammatica del Workload esiste solo come contenuto che una Recipe o una FeatureRecipe consuma — scritto inline, in un file accanto a essa o in una voce di una WorkloadLibrary. Le dichiarazioni apiVersion e kind all’interno dello YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) identificano il contenuto incorporato ai fini della validazione dello schema; non rendono il Workload indirizzabile in modo indipendente.
Valutazione dei template
Il contenuto del Workload viene elaborato come template Go rispetto al contesto completo dei pilastri prima del parsing. Quando un autore di Recipe scrive un template come il seguente…
replicas: {{ optional .infra `replicas` 1 }}…il compilatore valuta quel template durante la sottofase Workload del rendering, risolve .infra.replicas rispetto al payload infra del nodo e analizza lo YAML risultante come documento Workload. I locals della Recipe si risolvono prima che il Workload venga valutato, quindi un template di Workload li legge, già risolti, sotto .locals.
Accesso ai pilastri all’interno dei template del Workload:
.values— payload cognitivo scritto dallo sviluppatore e dichiarato nell’Aggregate..infra— dimensionamento fisico scritto da Ops e dichiarato nella Release..parameters— già interpolati in fase di risoluzione; visibili tramite.values/.infraovunque lo sviluppatore o Ops abbiano fatto riferimento a.parameters.<name>in ciò che hanno scritto..locals— stato privato della Recipe risolto nel preambolo dei locals e pubblicato alla risoluzione delle sorgenti; disponibile in ogni punto di valutazione dei template del Workload..context.instance_id— l’ID di istanza appiattito del nodo; il prefisso dei nomi di risorsa emessi da un provider che chiama le risorse sintetizzate in base all’identità..context.rendered_name— il nome che dà alle risorse sintetizzate un provider che ne ricava il nome da sé, come il nome della release di helm; presente solo dove il provider ne riporta uno. Vedi ../templates/rendered-resource-names.md..context.inject— la pipe di iniezione successiva all’intercettazione, già riscritta da qualsiasiinjectMappingdi FeatureRecipe durante il mapping dell’iniezione..context.uses— gli archi di topologia arricchiti in uscita da questo nodo, ciascuno con iprovides, lelabelse le annotazioni a cascata risolti del target e, sotto.context.uses.<alias>.features.<slot>, le associazioni portate da quella connessione..features— le associazioni proprie del nodo, ciascuna con il suotype,values,infrae iprovidesrisolti. Un’associazione che prende il nome da uno slot che il Component dichiara infeaturesSchemariempie quello slot (vedi sotto). Un’associazione portata da una connessione non è tra queste; si legge sotto la sua connessione, e un Workload la consegna nominando la connessione (vedi Consegnare una credenziale portata da una connessione).
Vedi ../vocabulary/data-pillars.md per il contratto completo di accesso ai pilastri e ../templates/expansion-matrix.md per la posizione della valutazione del Workload nella sequenza di valutazione dei template.
Elementi essenziali della semantica dei campi
Lo schema completo del Workload si trova in ../../architecture/16-recipe-input-composition.md, nella sezione «Il tipo Workload». Le convenzioni di authoring riportate di seguito coprono le decisioni a livello di campo che l’autore di una Recipe prende.
form
form dichiara la forma astratta di controller del carico di lavoro — il tipo di ciclo di vita a runtime che ha, indipendentemente da qualsiasi piattaforma di destinazione. È una singola stringa, una tra stateless, stateful, daemon, scheduled, task, reference, e se omessa assume il valore predefinito stateless:
stateless— repliche intercambiabili, scalate orizzontalmente, senza un’identità per singola replica (il comune servizio di lunga durata).stateful— repliche con un’identità stabile per replica e uno storage per replica. Un volumepersistentTemplateè un complemento di questa forma.daemon— un’istanza per ogni host idoneo.scheduled— esecuzioni ricorrenti, attivate in base al tempo.task— una singola esecuzione fino al completamento.reference— nessun container proprio: il componente rappresenta un endpoint esterno, indicato comeendpoint(un host o un URL, passato così come è scritto) e unaportfacoltativa. Il provider helm lo emette come Service di tipoExternalName; il provider compose non emette nulla per esso.
La forma non contiene di per sé tipi di risorse nativi della piattaforma. Ogni provider di destinazione che sintetizza un Workload mappa la forma sulla propria forma nativa:
form | Kubernetes (helm) | Compose |
|---|---|---|
stateless | Deployment | service (nessun volume persistente) |
stateful | StatefulSet | service + volume con nome |
daemon | DaemonSet | interrompe la build |
scheduled | CronJob | interrompe la build |
task | Job | interrompe la build |
I provider terraform e cloudformation eseguono il rendering di Recipes con sorgente e di Recipes di soli artefatti e non sintetizzano alcun Workload: una Recipe che dichiara workload: associata a uno dei due interrompe la build, indicando i tipi di input supportati dal provider.
Quando un provider di destinazione non ha una mappatura pulita per una forma, la build si interrompe in modo esplicito anziché degradare il carico di lavoro in una forma che travisa l’intento — scegliere una forma che un confine di destinazione non può esprimere è un errore in fase di build, non un declassamento silenzioso. Il provider compose si interrompe su daemon, scheduled e task. Il provider helm emette un CronJob per scheduled (vedi schedule più avanti) e si interrompe solo quando la sua pianificazione è assente o malformata.
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 è la pianificazione cron di un carico di lavoro form: scheduled — il campo complementare che dà alla forma ricorrente la sua ricorrenza. È una singola stringa in un unico formato canonico:
- un’espressione crontab standard a 5 campi — minuto, ora, giorno del mese, mese, giorno della settimana (ad esempio
0 0 * * *per ogni giorno a mezzanotte,*/15 * * * *per ogni quindici minuti), oppure - una delle macro
@hourly,@daily,@weekly,@monthly,@yearly.
schedule è obbligatorio quando form: scheduled e ha senso solo in quel caso. Un carico di lavoro form: scheduled senza pianificazione, una pianificazione che non è né un’espressione a 5 campi né una macro riconosciuta (un’espressione a 6 campi con i secondi in testa, un token @ non riconosciuto o un campo con caratteri non validi), oppure uno schedule impostato su qualsiasi altra forma è un arresto in fase di build che indica la correzione. Il provider helm passa il valore così com’è nel campo spec.schedule del CronJob emesso.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # daily at 02:00containers: report: image: "reporter:1.0" command: ["/report"]suspend
suspend sospende la pianificazione ricorrente di un carico di lavoro form: scheduled. È un booleano e il suo valore predefinito è false. Con suspend: true la risorsa pianificata viene comunque generata con il suo schedule al proprio posto, ma nessuna esecuzione parte da quella pianificazione finché non viene ripresa, e un’esecuzione può comunque essere avviata a mano dalla risorsa. È la forma adatta a un task che deve essere eseguito solo quando qualcuno lo richiede.
Il provider helm emette il campo come spec.suspend: true del CronJob. Su Kubernetes, kubectl create job <name> --from=cronjob/<cronjob> avvia un’esecuzione dal CronJob sospeso, e la pianificazione riprende quando spec.suspend torna a essere false. suspend: false produce esattamente lo stesso output di un suspend omesso, quindi il campo non modifica alcun output finché non viene impostato. Il provider compose non ha una forma pianificata e si interrompe su qualsiasi carico di lavoro form: scheduled, sospeso o meno.
suspend: true su qualsiasi altra forma è un arresto in fase di build che indica la correzione: nessun’altra forma ha una pianificazione da sospendere.
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 singolo intero per il numero di repliche del carico di lavoro. Se omesso, il valore predefinito è 1. Usa un’espressione di template per determinare le repliche dal dimensionamento dichiarato dagli Ops:
replicas: {{ optional .infra `replicas` 1 }}containers e initContainers a confronto
containers è una mappa ordinata con il nome del container come chiave. Il container 0 (la prima chiave della mappa) conta per l’ordinamento della specifica del pod nell’output Kubernetes e per la semantica del container predefinito. initContainers è una lista ordinata di voci di init container, ciascuna con name, image e la stessa forma di authoring per variabili, secret e montaggi di volume dei container principali.
name è facoltativo in una voce di initContainers. Una voce che lo omette prende il nome init-<index>, dove l’indice è la posizione della voce nella lista, contando da 0. Poiché il nome identifica il container nell’output generato e in qualsiasi diagnostica che lo nomini, una voce a cui valga la pena fare riferimento merita un nome esplicito.
La preservazione dell’ordine dell’autore è un contratto portante del modello Workload — il compilatore emette containers, volumes, services, le ports dei container, le variables dei container e gli attachments dei container ciascuno nell’ordine in cui l’autore della Recipe li ha dichiarati, a ogni build. Gli autori di Recipe possono fare affidamento sulla forma ordinata: quando ciò che accade a runtime dipende dall’ordine (avvio dei sidecar, concatenamento $(VAR) nelle variabili d’ambiente, volumeMounts che fanno riferimento a volumi dichiarati in precedenza), l’ordine di authoring È l’ordine a runtime all’interno di ciascuna di queste collezioni. L’ambiente di un container combina due di esse, e tra le due i provider che sintetizzano scrivono prima le voci lette dalle associazioni (attachments consegnati as: env) e poi le semplici variables, ciascun tipo nell’ordine di authoring — quindi su una destinazione Kubernetes una variabile può fare riferimento, come $(NAME), a qualsiasi variabile letta da un’associazione del suo container e a qualsiasi variabile dichiarata prima di essa (vedi l’ordine dell’ambiente del provider helm). Un container che fornisce lo stesso nome sia come voce di variables sia come voce di attachments consegnata as: env interrompe la build, perché sarebbe solo quell’ordine a decidere quale dei due valori vede il processo (vedi A container gives one environment variable two values (Un container assegna due valori a una stessa variabile d’ambiente)).
L’authoring dei campi dei container segue queste convenzioni:
imageè tipicamente un’espressione di template che fa riferimento a.values.image(l’immagine selezionata dallo sviluppatore) con eventuali override.infra.*per aggiungere un prefisso di registry specifico dell’ambiente.variablesè una semplice mappa string → string per le variabili d’ambiente. La mappa unisce due fonti di dati distinte tramite espressioni di template Go: letterali del pillar dello sviluppatore (voci le cui espressioni di template leggono.values/.infra/.locals— payload che ha origine nei pillar del Component) e dati della pipe tra componenti (voci le cui espressioni di template leggono.context.inject.env.<KEY>— payload che ha origine nelprovides:di un altro componente e viene instradato attraverso la pipe della topologia). Le due fonti confluiscono nella stessa mappavariables; gli autori ne scelgono una per ogni voce a seconda che il valore sia locale al componente o derivato da un altro componente. Pattern comuni:LOG_LEVEL: "{{ .values.log_level }}"appartiene al pillar dello sviluppatore (locale al componente);DB_HOST: "{{ .context.inject.env.DB_HOST }}"appartiene alla pipe tra componenti (il valore ha origine nelprovides.hostdi un componente di destinazione, instradato attraverso la dichiarazioneuses[].inject.env.DB_HOSTdel chiamante). Entrambe le forme vengono compilate in un’unica lista Kubernetesenv:sul Deployment generato; la semantica a doppia fonte esiste solo in fase di authoring.attachmentsfa riferimento a slot dichiarati nelfeaturesSchemadel Component oppure, nominando una connessione, a uno slot dichiarato dal socket di quella connessione (vedi la sezione sull’integrazione più avanti).portsè una mappa di porte con nome (web: 8080,admin: 9901); i nomi delle porte corrispondono ai nomi di porta con ambito di container e sono referenziati daservices.<service>.ports.<portname>. Una porta che usa un trasporto diverso da quello predefinito della destinazione si scrive invece nella forma estesa — vedi Protocolli di trasporto delle porte più avanti.volumeMountsfa riferimento per nome a volumi dichiarati altrove nella sezionevolumes:del Workload.resourcesdichiara lerequestse ilimitsdel container — le quantitàcpuememorye, facoltativamente, chiavi di risorse estese per GPU e altri dispositivi (vedi Carichi di lavoro GPU e di dispositivi più avanti).healthusa la forma d’intento (http: /path,tcp: <port>,exec: [cmd, ...]) — vedi la sezione sulle health probe più avanti.
volumes
Ogni volume è esattamente di un tipo: ephemeral, configmap, secret, persistent o persistentTemplate. I tipi si escludono a vicenda all’interno di una singola dichiarazione di volume; ogni tipo ha i propri campi obbligatori:
volumes: app-config: configmap: source: "{{ .locals.app_cm }}" data: persistent: size: "10Gi" class: "gp3" cache: ephemeral: sizeLimit: "1Gi"persistentTemplate produce un PVC per replica nella traduzione in forma di StatefulSet; nella traduzione per compose degrada a un singolo volume con nome condiviso, con un avviso riportato insieme alla build. Il file generato di per sé non contiene alcuna nota della degradazione — è identico byte per byte a come sarebbe senza l’avviso.
Traduzione per provider. Ogni provider traduce le cinque varianti di volume nella propria forma nativa:
| Variante | Helm / helm-chart (K8s) | Compose | Note sulle perdite |
|---|---|---|---|
ephemeral | emptyDir: { sizeLimit } | voce tmpfs: a livello di service che indica il percorso di montaggio (in memoria) | Il tmpfs di Compose è basato sulla RAM; l’emptyDir di helm è basato per impostazione predefinita sul disco del nodo — una divergenza semantica nel supporto di archiviazione sottostante. sizeLimit non raggiunge alcuna parte dell’output compose: la voce emessa è solo il percorso di montaggio. Un sizeLimit scritto dall’autore genera un avviso unsupported-field che lo nomina, riportato insieme alla build anziché scritto nel file generato. |
configmap | Riferimento a un volume ConfigMap (consuma una risorsa ConfigMap emessa dagli artifacts: della Recipe o da una Feature) | Riferimento configs: a livello di service che nomina la configmap, montata nel percorso del montaggio del volume; la voce configs: di primo livello corrispondente proviene dagli artifacts: della Recipe | Entrambe le destinazioni fanno riferimento alla configmap per nome e nessuna delle due ne legge il contenuto, quindi la forma di authoring è simmetrica. Ciò che compose perde è la semantica di aggiornamento al rollout della ConfigMap di K8s: una config di compose è fissata al contenuto emesso dalla build. Un riferimento che nessuna voce di primo livello risolve interrompe la build anziché emettere un montaggio che a runtime resterebbe pendente. |
secret | Riferimento a un volume Secret (consuma il Secret indicato da un’associazione di credenziali — uno emesso dalla sua FeatureRecipe, o uno che esiste già) | env_file: per i secret in forma di variabili d’ambiente, o un file di secret montato in bind per i secret in forma di percorso | Compose non ha una semantica di prima classe per i Secret di Kubernetes. Un secret in forma di percorso deliberatamente non segue la strada configs: della variante configmap: una voce di config inline scriverebbe il valore del secret in chiaro nel file compose emesso, e il compilatore non risolve mai un secret in chiaro. La sorgente del bind è un percorso che l’operatore rende raggiungibile sull’host compose, al di fuori di qualsiasi ciclo di vita di CRD di recupero da vault. |
persistent | Risorsa PVC + volume.persistentVolumeClaim | Volume con nome | I volumi con nome di Compose sono un’astrazione piatta lato host; il PVC di helm supporta la dichiarazione di storage class, modalità di accesso e capacità, che compose ignora. |
persistentTemplate | StatefulSet.volumeClaimTemplates (PVC per replica; complemento di form: stateful) | Volume con nome (degradato — un singolo volume condiviso tra le repliche, con un avviso riportato) | Compose non può esprimere template per replica. Quando persistentTemplate viene tradotto per compose, viene emesso un singolo volume con nome e la fedeltà ridotta viene riportata come avviso insieme alla build anziché scritta nel file generato. I Workloads che si basano sull’isolamento dei volumi per replica non dovrebbero avere come destinazione confini solo compose. |
La forma del controller è scelta dal form del carico di lavoro, non dai suoi volumi. Uno StatefulSet viene emesso quando form: stateful; un volume persistentTemplate è un complemento di quella forma — dichiara uno storage per replica su un carico di lavoro che ha già l’identità per replica fornita da uno StatefulSet. Dichiarare un volume persistentTemplate su qualsiasi altra forma (o sul stateless predefinito) è un errore in fase di build che indica la correzione: declare form: stateful. Il contrario è consentito — un carico di lavoro form: stateful non deve necessariamente dichiarare un volume persistentTemplate. Gli autori che vogliono la semantica di StatefulSet impostano direttamente form: stateful.
Un carico di lavoro form: stateful sul provider helm richiede un Service di governo headless: dichiara esattamente un service con type: Headless nello stesso Workload. Il provider collega il serviceName dello StatefulSet a quel Service headless (fornisce le identità di rete stabili per pod di cui uno StatefulSet ha bisogno). La build si interrompe se non è dichiarato alcun service headless — uno StatefulSet non avrebbe alcun Service di governo da nominare — o se ne è dichiarato più di uno, lasciando ambiguo il Service di governo. Un carico di lavoro StatefulSet può comunque dichiarare service aggiuntivi non headless (ad esempio un service ClusterIP per l’accesso dei client) accanto all’unico service di governo headless.
Quantità di risorse
Questi valori del Workload sono quantità — importi scritti nella notazione che Kubernetes usa per le risorse: i valori resources.requests e resources.limits di un container (o di un init container) per cpu, per memory e per ogni chiave di risorsa estesa, e ephemeral.sizeLimit, persistent.size e persistentTemplate.size di un volume. Lo schema del Workload tipizza ciascuno come stringa e non ne vincola la forma. Il provider che sintetizza il Workload per una destinazione controlla ogni quantità che emette, e controlla il Workload così come lo hanno valutato i template della Recipe, quindi un valore arrivato tramite infra, un parametro della Release o qualsiasi altro input di template viene giudicato sulla stringa che ha prodotto.
Una quantità è, senza nulla prima o dopo:
- un segno facoltativo,
+o-; - un numero con almeno una cifra —
2,0.5,.5o1.; - al massimo uno tra un esponente —
eoE, un segno facoltativo, poi cifre, come in1e3o5E-2— e un suffisso di unità: un suffisso decimalen,u,m,k,M,G,T,PoE(da 10⁻⁹ fino a 10¹⁸, a passi di mille), o un suffisso binarioKi,Mi,Gi,Ti,PioEi(da 1024 fino a 1024⁶).
500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n e 4u sono quantità; lots, 1.5 cores, 1 gigabyte, 10 GB e 1e1.5 non lo sono — un esponente è un numero intero. Una E isolata dopo il numero è il suffisso decimale per 10¹⁸ (12E); seguita da cifre apre un esponente (1E3).
Questa è la forma che accetta il parser di quantità di Kubernetes stesso, con una differenza deliberata: una stringa il cui numero non ha alcuna cifra — m, Ki, +, ., e5 — viene rifiutata, mentre Kubernetes la legge come zero. Quella stringa è esattamente ciò che un template lascia quando il valore che interpola è vuoto: "{{ .infra.cpu }}m" con un cpu vuoto produce m. Rifiutarla trasforma un input vuoto in un arresto che nomina il campo, anziché in una richiesta di dimensione zero che nessuno segnala.
Che cosa fa ciascuna destinazione con una quantità:
- helm emette ogni quantità così com’è, dopo averla verificata rispetto alla forma descritta sopra. Un valore al di fuori di essa interrompe la build con un errore che nomina il nodo, il percorso del campo nel Workload —
containers.main.resources.requests.cpu,initContainers[0].resources.limits.memory,volumes.data.persistent.size— e il valore. Vedi Helm Provider → modalità Workload (sintetizzato). - compose converte
cpuememorynelle proprie unità a partire dal valore analizzato:cpusdiventa un numero decimale di core (500m→0.5) ememoryun numero esatto di byte (1.5Gi→1610612736). Un valore che non è una quantità interrompe la build, e lo stesso fa una quantità che compose non può rappresentare esattamente — un importo negativo, un importo di memoria che non è un numero intero di byte (1500m) o un importo di cpu più fine di nove cifre decimali di un core — e l’errore indica quale dei due casi ha incontrato. Un conteggionvidia.com/gpuviene letto allo stesso modo e diventa un numero di dispositivi, quindi anche un conteggio che non è un numero intero di dispositivi interrompe la build. compose non emette altre risorse estese né dimensioni di volume, quindi non controlla né le une né le altre: qualsiasi altra chiave di risorsa estesa e unephemeral.sizeLimitvengono scartati con un avviso, e una dimensione persistente non influisce in alcun modo sul suo output. Vedi Compose Provider → Risorse dei container.
Il controllo giudica solo la forma. Se un cluster può pianificare l’importo, o se l’importo è adatto al suo dispositivo, esula da esso.
services
Una mappa ordinata di esposizioni di servizio. Ogni servizio dichiara il proprio tipo (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — fin dove arrivano le sue porte — e una mappa di porte con nome. I nomi delle porte devono corrispondere ai nomi delle porte dei container dichiarati altrove nel Workload:
services: http: type: ClusterIP ports: web: 8080 # must exist in containers.<name>.portsPiù servizi su un singolo Workload sono comuni per esporre separatamente il traffico interno e quello esterno (ClusterIP interno per i consumatori all’interno del cluster, LoadBalancer per il traffico esterno, ClusterIP per lo scraping di Prometheus).
Fin dove arrivano le porte di un servizio. Lo indica il type, e ogni target lo renderizza nei propri termini:
type | Portata | helm | compose |
|---|---|---|---|
ClusterIP | i peer del carico di lavoro, sulla rete propria del target | un Service di tipo ClusterIP | non pubblica nulla; i peer raggiungono la porta sulla rete di compose |
Headless | lo stesso, senza indirizzo del cluster | un Service di tipo ClusterIP con clusterIP: None | non pubblica nulla |
NodePort | oltre la rete propria del target | un Service di tipo NodePort | ogni porta pubblicata su ogni interfaccia dell’host, come <service port>:<container port> |
LoadBalancer | oltre la rete propria del target | un Service di tipo LoadBalancer | come NodePort |
Loopback | solo l’indirizzo di loopback dell’host stesso | arresta la build, indicando il servizio | ogni porta pubblicata sull’indirizzo di loopback IPv4, come 127.0.0.1:<service port>:<container port> |
Il numero di una porta di servizio e la porta del container che essa indica sono due numeri, come lo sono port e targetPort di un Service Kubernetes: helm scrive il numero della voce come port del Service e punta alla porta del container tramite il suo nome, e compose pubblica il numero della voce sull’host verso il numero della porta del container. Dove i due numeri sono uguali, compose scrive quel numero su entrambi i lati.
Loopback è per una porta che qualcosa sulla stessa macchina raggiunge — un browser o un agente in esecuzione sull’host — e che nient’altro dovrebbe raggiungere. Su compose il binding è solo l’indirizzo di loopback IPv4: l’indirizzo di loopback IPv6 ::1 non viene associato, quindi indirizza la porta come 127.0.0.1 anziché tramite un nome che potrebbe risolversi in ::1. Un trasporto dichiarato si scrive sulla voce come su qualsiasi porta pubblicata, come in 127.0.0.1:5514:5514/udp.
Dove due voci indicano la stessa porta, prevale la portata più ampia: una porta che una voce NodePort o LoadBalancer pubblica viene pubblicata su ogni interfaccia anche quando la indica anche una voce Loopback, qualunque delle due sia dichiarata per prima.
Su helm una voce Loopback arresta la build anziché essere renderizzata come qualcosa che non è. Un Service Kubernetes non ha alcun tipo che si associ all’indirizzo di loopback di un host — su quali indirizzi dei nodi ascolta un Service NodePort è un’impostazione dell’intero cluster, non di un singolo Service — quindi un Service ClusterIP perderebbe la portata richiesta dalla voce, e uno NodePort pubblicherebbe la porta su ogni indirizzo di nodo consentito dal cluster. L’arresto indica il nodo e il servizio; vedi A service type the helm provider cannot render (Un tipo di servizio che il provider helm non può renderizzare).
Convenzione dei nomi sintetizzati. Quando il provider helm sintetizza i servizi di un Workload, il metadata.name di ogni Service viene derivato in modo deterministico dal nome che porta il controller del carico di lavoro stesso e dalla chiave di authoring del servizio. Per il Workload di un componente quel nome è il nome della release del nodo: <release name>-<service-key>. Il nome della release è l’identità del componente scritta nell’alfabeto ammesso da un nome Kubernetes — lo stesso nome rispetto a cui viene renderizzato un chart, leggibile nei template di una Recipe come {{ .context.rendered_name }} — quindi coincide con l’instance_id ovunque l’identità non contenga underscore né lettere maiuscole. Un Workload che dichiara services.http sul nodo api-server produce un Service chiamato api-server-http; lo stesso Workload sul nodo billing produce billing-http, e sul nodo my_api produce my-zuapi-http. Il nome del file di output rispecchia la stessa convenzione: <release name>-<service-key>-service.yaml. Una Recipe che pubblica l’indirizzo di un tale Service lo costruisce da {{ .context.rendered_name }}, mai da {{ .context.instance_id }}, che non indica alcun Service ovunque i due differiscano — vedi ../templates/rendered-resource-names.md.
Un Workload sintetizzato dalla FeatureRecipe di un’associazione di Feature prende il nome dall’identità composta dell’associazione stessa anziché da un nome di release: il valore che le sue risorse portano nella loro etichetta aggrega.ai/component-id, composto dal componente host e dalla chiave scritta sotto features:, dopo il prefisso iniziale cfr--. Un nome di release derivato lì sarebbe quello dell’host, e darebbe alle risorse dell’associazione il nome di quelle dell’host. Così una FeatureRecipe il cui Workload dichiara services.scrape, per un’associazione stats sul nodo front-door, produce un Deployment cfr--front-door--stats e un Service cfr--front-door--stats-scrape. Quel primo segmento non coincide mai con l’instance_id, e nessuna chiave nel contesto dei template della FeatureRecipe lo contiene: nei template di un’associazione {{ .context.rendered_name }} e {{ .context.instance_id }} indicano entrambi l’host (front-door) e {{ .attachment_name }} è la sola chiave (stats), quindi {{ .context.rendered_name }}-scrape indica il Service scrape dell’host stesso, dove l’host ne dichiara uno, e mai quello dell’associazione — vedi ../templates/rendered-resource-names.md. Il file di output si trova dietro il prefisso che porta ogni file emesso da un’associazione — il nome dell’host e quello dell’associazione, ciascuno seguito da -- — quindi quel Service viene scritto in front-door--stats--cfr--front-door--stats-scrape-service.yaml.
La convenzione ha due conseguenze pratiche. Primo, le collisioni tra nodi sono impossibili per costruzione — il prefisso del nome distingue i servizi tra tutti i nodi del confine, perché due identità distinte producono sempre due nomi di release distinti, l’identità di un’associazione contiene sia il suo host sia la sua chiave, e nessun nome di componente può iniziare con cfr-- (la build si arresta su uno che lo fa — vedi Component identity cannot be stamped on what it emits (L’identità del Component non può marcare ciò che esso emette)), quindi due Workloads che dichiarano ciascuno services.http producono risorse Service K8s distinte con nomi che non si sovrappongono. L’unico residuo è un’identità di associazione troppo lunga per il target: viene accorciata attorno a un digest dell’intero, e due identità accorciate possono in linea di principio coincidere — vedi Etichette di provenienza emesse sull’output renderizzato. Secondo, un Workload non può dichiarare due volte la stessa chiave di servizio — una mappa services: che indica due volte una chiave viene rifiutata quando lo YAML del Workload viene analizzato, e la build si arresta indicando la chiave e la sua riga.
Il rischio di collisione che rimane si trova al limite di lunghezza dei nomi K8s: i nomi dei Service Kubernetes sono limitati a 63 caratteri, e la forma sintetizzata <release name>-<service-key> può superare quel limite quando entrambi i segmenti sono lunghi. Il compilatore Aggrega non impone il limite; la build emette il Service, e Kubernetes lo rifiuta quando viene applicato. Gli autori con ID di istanza profondamente annidati (ad es. data-layer.regional.eu-west.primary) e chiavi di servizio lunghe dovrebbero mantenere la lunghezza combinata sotto i 63 caratteri. Lo stesso vale per il Workload di un’associazione: un’identità composta troppo lunga per il target viene accorciata, ma la chiave di servizio aggiunta a essa no, quindi un Service di un’associazione con una chiave lunga può comunque superare i 63 caratteri ed essere generato senza alcun arresto.
Nota specifica del Provider (compose). Il provider compose deriva depends_on automaticamente dagli archi uses dell’IR. Quelle voci vengono emesse senza condizione — hanno la semantica service_started indipendentemente dal fatto che il target dichiari un healthcheck — quindi un servizio le cui dipendenze provengono tutte da archi uses emette la lista in forma breve (depends_on: [<target>]). Condizionare una voce derivata da un arco alla salute del target non è implementato. La forma lunga viene emessa dove una voce porta effettivamente una condizione, ed è così che si esprime un’attesa su un init container; vedi providers/compose.md.
Protocolli di trasporto delle porte
Una porta di container si scrive in una di due forme equivalenti. Il solo numero è la forma breve e non dichiara alcun trasporto, quindi il target applica il proprio default — TCP su ogni target che ne ha uno:
containers: main: image: "{{ .values.image }}" ports: web: 8080La forma estesa riporta insieme il numero e il trasporto, ed è ciò che serve a una porta quando trasporta qualcosa di diverso da quel default:
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: SCTPLe due forme possono essere mescolate liberamente all’interno di una stessa mappa ports, e una porta senza trasporto da dichiarare resta nella forma breve.
Il trasporto si dichiara una sola volta, sulla porta del container. Una voce services.<service>.ports indica una porta del container e ne prende con sé il trasporto, quindi un’esposizione di servizio non può essere in disaccordo con la porta aperta dal container. Non esiste una chiave protocol su una porta di servizio, e scriverne una viene rifiutato.
Perché il campo esiste. I target di distribuzione trattano un trasporto non specificato come quello a flusso. Un componente che ha bisogno di una porta a datagrammi — media in tempo reale, telefonia, risoluzione dei nomi, reti private, un server di gioco — potrebbe altrimenti dichiarare solo il numero, e lo stack verrebbe distribuito superando ogni controllo mentre nessun client riuscirebbe a connettersi, perché il traffico è a datagrammi e la porta aperta non lo è. Dichiarare il trasporto è ciò che rende tutto questo esprimibile.
Il compilatore non interpreta il valore. Non ricava alcun trasporto dal nome di una porta e non verifica il trasporto dichiarato rispetto a ciò che il processo dietro la porta parla effettivamente: il valore è un dato che dichiari tu e che il motore del target emette. Una porta chiamata dns senza chiave protocol è una porta TCP, e una porta chiamata web che dichiara protocol: UDP è una porta UDP.
Comportamento per target.
| Target | Una porta senza trasporto dichiarato | Un trasporto dichiarato |
|---|---|---|
| helm | containerPort e la porta del Service non hanno alcuna chiave protocol | emesso testualmente come protocol: sulla porta del container e su ogni porta di Service che la indica |
| compose | pubblicata come <host>:<container>, invariata | pubblicata come <host>:<container>/tcp o /udp; SCTP non ha una grafia compose e arresta la build anziché pubblicare una porta con un trasporto diverso |
Una porta di container che nessun servizio pubblica non raggiunge alcuna parte di un file compose — è il comportamento abituale di compose per le porte dei container — quindi un trasporto dichiarato su una tale porta non ha nulla su cui essere scritto e non causa alcun arresto.
Sonde di salute — forma di intento
Ogni container dichiara le proprie sonde sotto la propria chiave health: (containers.<name>.health), in una forma di intento astratta; il Workload non ha un health di primo livello. Ogni provider traduce l’intento nella propria forma di sonda nativa al momento della sintesi.
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: 10Tre forme di intento (http:, tcp:, exec:) si escludono a vicenda all’interno di una singola dichiarazione di sonda. La risoluzione della porta per http: senza una porta esplicita prende il primo nome di porta in ordine alfabetico che il container dichiara sotto containers.<name>.ports — la stessa regola su entrambi i target, quindi una sonda legge la stessa porta qualunque dei due la renderizzi. Un container che non dichiara alcuna porta con nome non può avere una sonda HTTP: la build si arresta con un errore di traduzione che indica la sonda in questione.
Traduzione per provider. Ogni provider traduce l’intento astratto della sonda nella propria forma nativa al momento della sintesi:
| Intento | Helm (K8s) | Compose | Note sulle perdite |
|---|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" | Compose non ha una forma nativa di sonda HTTP; il wrapper CMD-SHELL dipende dalla presenza di curl nell’immagine del container. |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" | Compose non ha una forma nativa di sonda TCP; il wrapper CMD-SHELL dipende dalla presenza di nc nell’immagine del container. |
exec: [cmd, ...] | exec.command: [cmd, ...] | CMD [cmd, ...] | Corrispondenza uno a uno; entrambi i provider riportano la lista di comandi testualmente. |
I wrapper CMD-SHELL di Compose approssimano le sonde HTTP e TCP tramite predicati valutabili dalla shell. Ciò che manca a compose è la forma nativa della sonda, non i campi di temporizzazione: periodSeconds, timeoutSeconds, failureThreshold e initialDelaySeconds scritti dall’autore vengono riportati sull’healthcheck come interval, timeout, retries e start_period — la sezione «Sonde» di providers/compose.md riporta la corrispondenza campo per campo. La forma nativa exec: non ha bisogno di alcun wrapper e si traduce uno a uno su entrambi i target.
Una sonda avvolta in un wrapper viene tradotta in silenzio: nulla nel docker-compose.yaml emesso la segnala, e nessuna diagnostica riporta il wrapping. Ciò che la build riporta su questo percorso è uno slot di sonda che non raggiunge alcun output — un servizio compose ha un solo healthcheck, quindi dove un Workload dichiara più di uno tra ready:, live: e startup: viene tradotto solo lo slot preferito (live prima di ready prima di startup) e un avviso unsupported-field indica lo slot tradotto e gli slot scartati.
Nota specifica del Provider (compose). Scrivere un blocco health: su un Workload destinato a compose non condiziona l’ordinamento di depends_on alla salute: le voci depends_on del provider compose derivate dagli archi uses: usano sempre la semantica service_started, indipendentemente dal fatto che il Workload di destinazione dichiari sonde di salute. Condizionare quelle voci alla salute del target non è implementato — la forma lunga che porterebbe una tale condizione viene essa stessa emessa, per le attese sugli init container, quindi ciò che manca è la scelta di condizionare un arco alla salute, non la forma per esprimerlo. Vedi providers/compose.md per le regole di inferenza complete.
Campi pass-through in forma K8s — scheduling, serviceAccount, podSecurityContext
Lo schema Workload accetta tre campi facoltativi di primo livello che esistono principalmente per far passare primitive native di Kubernetes attraverso il provider helm, preservando la forma strutturale di Aggrega. Il provider compose traduce il sottoinsieme che ha un analogo in Compose e ignora il resto emettendo un avviso. Aggrega valida la forma esterna ma non controlla il contenuto interno (vedi Superficie di validazione più avanti) — i valori interni nativi di K8s passano testualmente nella pod spec renderizzata da helm.
scheduling
scheduling raggruppa quattro primitive di scheduling native di K8s — nodeSelector, affinity, tolerations, topologySpreadConstraints — in un unico blocco organizzato per scopo. Ogni sottocampo ha esattamente la forma del corrispondente campo della pod spec 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: "..." }Traduzione del Provider. Il provider helm passa ogni sottocampo testualmente nella pod spec renderizzata. Il provider compose non traduce nessuno dei quattro: omette l’intero blocco scheduling, e un avviso lo indica.
serviceAccount
serviceAccount è una semplice stringa che contiene il nome del ServiceAccount con cui viene eseguito il carico di lavoro:
apiVersion: aggrega.ai/v1beta1kind: WorkloadserviceAccount: "{{ .context.rendered_name }}-runner"containers: app: { image: "..." }Il nome è costruito da {{ .context.rendered_name }}, il nome della release da cui il provider helm prende il nome delle risorse proprie del carico di lavoro, quindi è un nome che il cluster accetta comunque si chiami il componente. Il campo fa riferimento a un ServiceAccount esistente; non ne crea uno. Le risorse RBAC che lo accompagnano (l’oggetto ServiceAccount stesso, più Role / RoleBinding / ClusterRole / ClusterRoleBinding) dovrebbero essere fornite tramite uno di due canali:
artifacts:della Recipe — quando l’RBAC è intrinseco a questa Recipe (la Recipe sa di aver bisogno di un Role specifico per un compito specifico).- Features con generazione di risorse — quando l’RBAC è trasversale (una FeatureRecipe Workload-Identity che associa ServiceAccount legati a IAM a ogni componente con una determinata etichetta).
Impostare serviceAccount: senza fare in modo che il ServiceAccount indicato esista produce un errore K8s a runtime al momento dell’apply, non un errore in fase di build — la validazione dello schema del carico di lavoro non verifica l’esistenza del ServiceAccount (nessun accesso allo stato del cluster in fase di compilazione, secondo l’invariante di purezza AOT).
Il provider compose ignora serviceAccount: con un avviso; Compose non ha un concetto equivalente di associazione dell’identità.
podSecurityContext
podSecurityContext contiene primitive di sicurezza a livello di pod — UID, GID, fsGroup, supplementalGroups — che si applicano a ogni container del pod:
apiVersion: aggrega.ai/v1beta1kind: WorkloadpodSecurityContext: runAsUser: 1000 runAsGroup: 3000 fsGroup: 2000 supplementalGroups: [4000, 5000]containers: app: { image: "..." }Semantica dei campi. Tutti e quattro i campi sono interi (UID/GID numerici, non stringhe); runAsUser e runAsGroup impostano l’UID/GID effettivo dei processi del container; fsGroup imposta il gruppo proprietario dei volumi montati nel pod; supplementalGroups aggiunge GID ulteriori al gruppo di processi di ogni container.
Traduzione del Provider. Il provider helm passa il blocco testualmente nella pod spec renderizzata. Il provider compose non ha un equivalente per fsGroup o supplementalGroups e omette ciascuno con un avviso; runAsUser/runAsGroup si traducono nella forma Compose user: 1000:3000 su ogni servizio prodotto dal Workload, sidecar e init container inclusi, e un runAsGroup senza un runAsUser accanto viene omesso con un avviso. Ogni container e init container ha anche un proprio securityContext — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation e capabilities.add / capabilities.drop. Il provider helm lo emette sul container; il provider compose emette readOnlyRootFilesystem come read_only, capabilities.add / capabilities.drop come cap_add / cap_drop, e runAsUser / runAsGroup come user proprio del container, che prende il posto di quello del pod; omette runAsNonRoot, allowPrivilegeEscalation e un runAsGroup scritto senza un runAsUser, con un avviso ciascuno, e avvisa anche dove il runAsUser proprio di un container lascia fuori il runAsGroup del pod. providers/compose.md riporta la corrispondenza campo per campo.
Carichi di lavoro GPU e di dispositivi
Un carico di lavoro che ha bisogno di hardware specializzato — una GPU, o un altro dispositivo fornito da un vendor — esprime due aspetti indipendenti: il runtime a livello di pod che il nodo abilitato al dispositivo espone (runtimeClassName), e la quantità per container del dispositivo che il carico di lavoro richiede (una chiave di risorsa estesa sotto resources di un container). Un tipico carico di lavoro GPU dichiara entrambi insieme, ma ciascuno sta in piedi da solo e l’uno può comparire senza l’altro.
Entrambi i campi descrivono risorse di calcolo — il pod e il container che viene eseguito sul dispositivo — quindi appartengono a un carico di lavoro che esegue container. Un carico di lavoro che porta solo un endpoint esterno e non dichiara container propri non ha alcun pod o container a cui associarli: impostare runtimeClassName su un tale carico di lavoro con il solo endpoint arresta la build, indicando runtimeClassName e la Recipe il cui Workload lo ha dichiarato, e senza container non c’è dove collocare una richiesta di risorsa di dispositivo.
runtimeClassName
runtimeClassName è una singola stringa che indica la RuntimeClass con cui viene eseguito il pod — il runtime dei container che un nodo abilitato al dispositivo espone, ad esempio un runtime GPU chiamato nvidia. È un selettore a livello di pod: si applica a ogni container del carico di lavoro. Il compilatore fa passare il nome testualmente come puntatore deterministico; il cluster lo risolve in una RuntimeClass configurata dal suo amministratore, al momento dello scheduling. Aggrega non verifica che esista una RuntimeClass corrispondente — non ha accesso allo stato del cluster in fase di compilazione — quindi un nome senza RuntimeClass configurata emerge come errore di scheduling al momento dell’apply, non come errore in fase di build.
Chiavi di risorse estese
resources.requests e resources.limits di un container contengono le normali quantità cpu e memory e, accanto a esse, chiavi di risorse estese: quantità di dispositivi con ambito di vendor o di dominio, identificate da un nome completo <domain>/<name> come nvidia.com/gpu o amd.com/gpu. Il segmento del dominio contiene almeno un punto, ed è quel punto a distinguere una chiave estesa (nvidia.com/gpu) dalle semplici quantità cpu e memory. Ogni valore è una quantità in forma di stringa ("1", "2") che il compilatore fa passare testualmente, e il provider helm ne verifica la forma prima di emetterla (vedi Quantità di risorse); il device plugin del cluster risolve e alloca il dispositivo al momento dello scheduling.
Esempio svolto — un carico di lavoro di inferenza 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"Il carico di lavoro seleziona il runtime nvidia per il proprio pod e richiede una GPU per il container inference. La quantità di GPU compare sia in requests sia in limits: un dispositivo non ammette l’oversubscription, quindi la sua richiesta e il suo limite sono impostati allo stesso valore.
Traduzione del Provider. Si tratta di concetti nativi di Kubernetes. Il provider helm emette runtimeClassName sulla pod spec renderizzata e ogni chiave di risorsa estesa testualmente sotto resources.requests / resources.limits del container, così che raggiungano il cluster attraverso l’output Kubernetes. Il provider compose riserva un conteggio nvidia.com/gpu come altrettante GPU NVIDIA sul servizio del container (vedi Compose Provider → Risorse dei container); un singolo host non ha il concetto di runtime class né un analogo per qualsiasi altra chiave di risorsa estesa, quindi un carico di lavoro che dichiara runtimeClassName o un’altra chiave viene renderizzato su un target compose senza di essa.
Esecuzione sulla rete del nodo
Per impostazione predefinita un carico di lavoro viene eseguito in un namespace di rete proprio: i suoi container vedono solo le proprie interfacce e il traffico li raggiunge attraverso la traduzione degli indirizzi della destinazione. hostNetwork: true richiede l’altra disposizione — il carico di lavoro viene eseguito nel namespace di rete del nodo stesso, quindi vede le interfacce del nodo e le porte aperte dai suoi container sono raggiungibili sugli indirizzi del nodo stesso, senza alcuna traduzione intermedia.
È ciò di cui ha bisogno un’intera classe di software. I media in tempo reale, la telefonia, le reti private virtuali e il traffico simile trasportano l’indirizzo del peer all’interno del payload, quindi un indirizzo riscritto durante il transito arriva descrivendo un luogo che il peer non può raggiungere; l’esecuzione sugli indirizzi del nodo è ciò che mantiene coerenti le due cose.
apiVersion: aggrega.ai/v1beta1kind: WorkloadhostNetwork: truecontainers: media: image: "{{ .values.image }}" ports: rtp: port: 7881 protocol: UDPChe cosa dichiara e che cosa no
hostNetwork sceglie un namespace di rete, e questo è tutto.
- Non dichiara porte. Le porte che un carico di lavoro apre si dichiarano comunque in
containers.<name>.ports, esattamente come senza di esso, e continuano a significare la stessa cosa. DichiararehostNetworknon aggiunge una porta né elimina la necessità di dichiararne una. - Non dichiara alcun numero di porte. Un’applicazione che vuole molte porte contigue — un server multimediale che dimensiona un intervallo in base al numero di processori della macchina, ad esempio — configura quell’intervallo nel proprio corpo di configurazione, a partire da valori forniti dal suo operatore, nello stesso modo in cui configura qualsiasi altra cosa che legge all’avvio. Si tratta di un’impostazione dell’applicazione e non del carico di lavoro, e non è nel contratto del carico di lavoro che risiede.
- Nulla viene dedotto. Il compilatore non legge alcun significato dal valore e non lo ricava da nient’altro: né dal nome di una porta, né dal tipo o dalle etichette di un componente, né da quante porte sono dichiarate. Un carico di lavoro viene eseguito sulla rete del nodo quando, e solo quando, lo dichiara.
Poiché descrive risorse di calcolo, hostNetwork appartiene a un carico di lavoro che esegue container. Un carico di lavoro che contiene solo un endpoint esterno non dichiara container, quindi non ha alcun namespace di rete da scegliere: dichiarare hostNetwork su un carico di lavoro con solo endpoint interrompe la compilazione, indicando hostNetwork e la Recipe il cui Workload lo ha dichiarato.
Traduzione del Provider
Il provider helm emette hostNetwork: true nella specifica del pod renderizzata, che è il modo in cui Kubernetes esprime la stessa scelta. La dichiarazione raggiunge la specifica del pod e nient’altro — i Service emessi sono identici con e senza di essa.
Il provider compose emette network_mode: host sul servizio proprio del carico di lavoro. Dal modo in cui compose modella le reti deriva una conseguenza: un servizio in quella modalità non è collegato alla rete del confine, perché compose tratta il collegamento a una rete e l’adozione del namespace dell’host come alternative anziché come aggiunte. I suoi peer quindi lo raggiungono sugli indirizzi propri dell’host invece che tramite il nome del servizio — che è ciò che significa la rete dell’host su qualsiasi destinazione — e ogni altro servizio del confine non ne è toccato.
Due forme si combinano con esso su quella destinazione. Un container sidecar segue il servizio principale sulla rete dell’host senza dichiarare nulla, perché prende il namespace del servizio principale nominandolo. Un init container no: diventa un servizio che il servizio principale attende, quindi si unisce alla rete del confine a pieno titolo invece di adottare un namespace che renderebbe circolare quell’attesa. Un carico di lavoro che dichiara sia hostNetwork sia initContainers esegue quindi il proprio servizio sulla rete del nodo mentre i suoi servizi di init restano sulla rete del confine — una disposizione più ristretta dell’unico namespace condiviso offerto dalla forma del pod, e che il provider compose segnala in un avviso unsupported-field invece di lasciarla da scoprire in fase di esecuzione.
Un carico di lavoro che non dichiara hostNetwork non contiene tale chiave nel suo output: la chiave è assente anziché emessa come false.
Integrazione delle associazioni con il featuresSchema del Component
Il blocco containers.<name>.attachments del Workload fa riferimento a slot di credenziali dichiarati nel featuresSchema del Component — oppure, per una voce che nomina una connessione, a uno slot dichiarato dal socket di quella connessione (vedi Consegnare una credenziale trasportata da una connessione); non dichiara nuovi slot. Vedi ../entities/component.md per la superficie di authoring di featuresSchema. from nomina lo slot; non è il nome del Secret generato.
Una voce containers.<name>.attachments viene renderizzata come riferimento a una risorsa Secret — un secretKeyRef di Kubernetes (per as: env) o un volume basato su un secret (per as: file) — entrambi i quali puntano al Secret per nome. Il sintetizzatore risolve quel nome e la chiave dei dati dai provides esposti dello slot: il secretKeyRef.name renderizzato della voce è il .features.<slot>.provides.name dello slot e la chiave dei dati è .features.<slot>.provides.key. L’autore della Recipe scrive solo from: <slot> e as: env; il sintetizzatore legge i provides risolti — non ricava di nuovo il nome. È la stessa lettura .features.<slot>.provides.<key> che una Recipe source usa per un existingSecret: un singolo slot di credenziali alimenta in modo identico sia un consumatore Recipe source sia un consumatore Workload sintetizzato (simmetria source/workload).
Quattro regole di validazione governano l’integrazione:
- Ogni valore
attachments.<KEY>.fromdeve corrispondere a un nome di slot dichiarato nelfeaturesSchemadel Component — oppure, su una voce che nomina una connessione, nel socket di quella connessione. Un nome di slot sconosciuto è un errore al caricamento. - Il meccanismo di consegna
as:(envofile) deve comparire nella allowlistinject:dello slot dichiarata dal Component. Un Workload che dichiaraas: fileper uno slot la cui voce difeaturesSchemaspecificainject: [env]è un errore al caricamento. - Gli slot contrassegnati con
inject: [](consegna blackbox) nelfeaturesSchemadel Component non possono comparire affatto nei blocchiattachments:del Workload. Quegli slot vengono consegnati dai meccanismi interni della Recipe (il parametroexistingSecretdi un chart Helm, ad esempio), non tramite l’esposizione nel Workload. - Lo slot referenziato deve essere referenziabile — il suo riempimento deve pubblicare un localizzatore
provides(name,key) per una risorsa Secret, una emessa dalla sua realizzazione o una già esistente. Uno slot riempito da una credenziale consegnata tramite inject (una che scrive un valore nella pipe di inject e non pubblica alcun localizzatore) non ha nulla a cui puntare; farvi riferimento da una voceattachments:di un Workload è un errore al caricamento. Una credenziale consegnata tramite inject raggiunge il container attraverso la pipe di inject dello slot (una vocevariablesche legge.context.inject.env.<KEY>), non attraverso una voceattachments:.
Nota sul Provider. Helm renderizza il riferimento secretKeyRef/volume secret descritto sopra. Il provider compose non ha una primitiva nativa env-from-secret; una voce di associazione as: env su un Workload destinato a compose viene renderizzata come voce d’ambiente con valore vuoto e un avviso che nomina la voce (vedi la pagina del provider compose), mentre la regola di referenziabilità (agnostica rispetto alle capacità) continua ad applicarsi.
Esempio:
# 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 slotConsegnare una credenziale trasportata da una connessione
Il socket di un Component può dichiarare, in usesSchema.<socket>.featuresSchema, gli slot che ogni connessione collegata attraverso di esso riempie — così un componente che raggiunge diverse destinazioni ha una credenziale per connessione anziché una per tutte. Un’associazione di questo tipo non è tra le .features proprie del componente; si trova sotto la sua connessione, in .context.uses.<alias>.features.<slot>. Una voce del Workload la consegna nominando la connessione accanto allo slot:
- su una voce
attachmentsdi un container,connection: <alias>accanto afrom: <slot>; - su una voce
envFromdi un container,connection: <alias>accanto asecret: <slot>—connectionè accettato solo accanto asecret.
Entrambe le forme sono accettate su ogni container e su ogni init container. <alias> è il nome sotto cui la connessione è scritta nel blocco uses del componente, nell’Aggregate o nella Release — la chiave con cui una Recipe legge la connessione sotto .context.uses — e <slot> è uno slot dichiarato dal socket attraverso cui quella connessione è collegata.
Prima che una qualsiasi delle regole precedenti legga il Workload, ogni voce che nomina una connessione viene riscritta sul nome che l’associazione trasportata da quella connessione in quello slot assume sul componente: l’alias, un punto e lo slot (gpt.credential). Ogni regola viene poi eseguita sulla voce riscritta esattamente come viene eseguita su una voce che nomina uno degli slot propri del Component: la allowlist inject: dello slot del socket governa as:, uno slot del socket che dichiara inject: [] non può essere referenziato, l’associazione che lo riempie deve essere referenziabile, e il provider risolve il nome del Secret e la chiave dei dati dai provides risolti di quell’associazione — così la voce di ogni connessione fa riferimento alla credenziale propria di quella connessione. Uno slot del socket che dichiara sensitive: true viene letto per la voce esattamente come la dichiarazione di uno slot del Component. La voce riscritta è ciò che il provider riceve; la chiave connection non lo raggiunge.
Tre voci vengono rifiutate, ciascuna indicando ciò che ha nominato:
- una voce che nomina una connessione che il componente non traccia — il rifiuto nomina la connessione, lo slot e le connessioni che il componente traccia;
- una voce che nomina uno slot che il socket della connessione non dichiara — il rifiuto nomina lo slot, la connessione, il socket e gli slot che dichiara;
- una voce che scrive essa stessa il nome composto (
from: gpt.credential). Lo slot di una connessione si nomina nominando la connessione, quindi il nome composto non è mai un secondo modo per raggiungerlo.
Una connessione che non trasporta alcuna associazione nello slot lascia la voce senza nulla da referenziare, e la regola di referenziabilità la rifiuta. Un Workload renderizzato da una FeatureRecipe è vincolato agli slot dichiarati dalla Feature che implementa, che non raggiungono nessuna delle connessioni del componente host, quindi una voce lì che nomina una connessione viene rifiutata in quanto ne nomina una che il componente non traccia.
Esempio:
# 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: envSu helm, MODEL_KEY_GPT viene renderizzato come un secretKeyRef che nomina il Secret pubblicato dalla credenziale della connessione gpt, e MODEL_KEY_NIM come quello pubblicato dalla credenziale della connessione nim. Su compose, una voce as: env che nomina una connessione viene emessa con un valore vuoto e lo stesso avviso di supporto parziale che riceve una voce che nomina uno degli slot propri del Component.
Superficie di validazione
Ogni Workload viene validato al caricamento della Recipe, prima che venga eseguito qualsiasi rendering. La validazione ha due fasi:
- Validazione dello schema. Il valore del Workload viene unificato con lo schema Workload
aggrega.ai/v1beta1incorporato. Gli errori riportano il percorso del campo e il vincolo violato (ad esempio,.containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). La validazione dello schema impone ogni tipo, enum, intervallo e disgiunzione dichiarati nello schema — inclusi ilformdel controller a insieme chiuso (uno trastateless,stateful,daemon,scheduled,task,reference), iltypedel servizio a insieme chiuso (uno traClusterIP,Headless,NodePort,LoadBalancer,Loopback), l’intervallo intero delle porte (1..65535), la disgiunzione della forma della probe (esattamente uno trahttp,tcp,exec) e la disgiunzione della variante del volume (esattamente uno traephemeral,configmap,secret,persistent,persistentTemplate). - Validazione dei riferimenti incrociati. I riferimenti di associazione del Workload vengono verificati rispetto al
featuresSchemadel Component — e, per una voce che nomina una connessione, rispetto agli slot dichiarati dal socket di quella connessione — (appartenenza allo slot, allowlist di consegnaas:, esclusione blackbox) e rispetto ai provides risolti di ogni slot referenziato (referenziabilità — il riempimento deve pubblicarename/key). Si tratta di controlli tra entità che una validazione basata solo sullo schema non può eseguire.
Entrambe le fasi producono la stessa forma di messaggio con prefisso CATALOG_ERROR; i fallimenti interrompono la compilazione prima che venga prodotto qualsiasi output di rendering. Gli autori di Recipe ricevono un riscontro mirato che identifica il campo esatto che ha fallito e il vincolo che lo ha rifiutato.
I campi pass-through in forma K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, le liste items all’interno dei volumi ConfigMap e Secret, gli hook httpGet del lifecycle) vengono validati solo strutturalmente — lo schema di Aggrega vincola la loro presenza e la loro forma esterna, ma la forma interna di questi valori definiti dall’API K8s è responsabilità del provider (il provider helm li passa alla specifica del pod K8s alla lettera; il provider compose li rifiuta o li degrada a seconda dei casi). Un Workload che usa un valore affinity malformato supera la validazione di Aggrega e fa invece emergere l’errore durante la sintesi del provider.
Allo stesso modo, per lo schema le quantità di risorse sono stringhe: nessuna delle due fasi ne verifica la forma. Lo fa il provider che sintetizza, sul Workload valutato, e si interrompe su un valore al di fuori della forma di quantità — vedi Quantità di risorse.
Le risorse ausiliarie stanno fuori dal Workload
Il Workload descrive solo la forma del carico di lavoro — container, volumi, servizi, repliche, scheduling, contesto di sicurezza, service account. Non ha un campo additionalResources né dichiarazioni inline di ConfigMap / Secret / CRD.
Gli autori di Recipe emettono le risorse ausiliarie attraverso due canali esterni al Workload:
artifacts:a livello di Recipe — per le risorse intrinseche a questa Recipe (una specifica ConfigMap a cui fa riferimento il Workload della Recipe, una registrazione di CRD una tantum di cui la Recipe ha bisogno). Il campo è una mappa di voci con nome; ogni voce è scritta inline o caricata tramite un$import:per voce. Vedi la sezione sul meccanismo degli artefatti in ../../architecture/16-recipe-input-composition.md per le tre modalità di authoring.- Features con generazione di risorse — per esigenze trasversali associate tramite i selettori della Release (una Feature ServiceMonitor associata a ogni componente con metriche esposte, una Feature NetworkPolicy associata a ogni carico di lavoro di produzione). Vedi ../entities/featurerecipe.md per la superficie di authoring della FeatureRecipe.
Il Workload resta concentrato sulla forma del carico di lavoro; i manifest ausiliari trasversali e quelli intrinseci alla Recipe hanno le proprie sedi di authoring.
Pattern comuni di Workload
Lo schema Workload è ampio — copre server HTTP a container singolo, pattern sidecar multi-container, catene di init container, job batch e servizi stateful con volumi persistenti. Tre pattern ricorrono abbastanza spesso da rendere uno spreco scrivere il boilerplate da zero per ogni Recipe. I blocchi seguenti sono modelli da copiare e incollare che gli autori di Recipe possono adattare a componenti specifici.
Un pattern condiviso da più Recipes può essere pubblicato una volta come voce di una WorkloadLibrary e importato con $import: <Library>#/workloads/<entry>; i modelli qui riportati sono punti di partenza da adattare, o da pubblicare in quel modo.
Pattern 1 — Server con esposizione delle metriche
Una tipica applicazione web che serve il traffico applicativo su una porta ed espone metriche raccolte da Prometheus su una porta separata. Due servizi nel Workload — uno per l’applicazione, uno per le metriche — mantengono nettamente separabili la policy del service mesh e la configurazione del bilanciatore di carico.
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 }}Il servizio delle metriche viene tipicamente annotato per il rilevamento da parte di Prometheus tramite un’associazione di Feature sulla superficie della Release (ad es. feature.aggrega.ai/prometheus-scrape: "true"); il Workload stesso resta privo di annotazioni di scrape specifiche del provider.
Pattern 2 — Job batch
Un carico di lavoro che viene eseguito fino al completamento invece di servire traffico indefinitamente. Il pattern imposta form: task, omette del tutto services: — i job batch non espongono porte — e si affida alla forma di task del provider di destinazione (un Job Kubernetes sul provider helm; il provider compose non ha una forma di task e si interrompe su form: task). Il provider helm fissa una restartPolicy del pod valida per un Job (Never a meno che il container non dichiari OnFailure), poiché un pod di Job non può usare il valore predefinito 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"Il volume di configurazione fa riferimento a una ConfigMap che la Recipe dovrebbe emettere accanto al Workload tramite artifacts: (vedi «Le risorse ausiliarie stanno fuori dal Workload» sopra) — il Workload stesso dichiara solo il lato del consumo. L’identità le dà il nome su un provider che nomina il carico di lavoro in base all’identità, come fa compose; con helm, che nomina le risorse del carico di lavoro in base al nome della release, costruisci invece il nome della ConfigMap — qui e nell’artefatto — a partire da {{ .context.rendered_name }}, così che sia un nome che il cluster accetta comunque si chiami il componente.
Pattern 3 — Coppia con sidecar
Un pod a due container in cui il container principale gestisce la logica applicativa e il sidecar gestisce un’esigenza trasversale (terminazione TLS, invio dei log, proxy del service mesh, guardrail AI). L’ordine di authoring in containers: è determinante — il provider helm emette i container nell’ordine dichiarato; la prima chiave (qui, main) è il container predefinito di destinazione per kubectl logs e strumenti simili.
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 }}Il Service espone la porta del sidecar (non quella del container principale), instradando il traffico esterno attraverso il sidecar verso il container principale tramite localhost. I due container condividono il namespace di rete del pod, quindi localhost:<port> raggiunge direttamente il container peer. Per i sidecar che necessitano dell’iniezione di credenziali (il pattern canonico del guardrail AI), la credenziale si trova tipicamente nel blocco attachments: del sidecar anziché in quello del container principale — mantenendo la credenziale circoscritta al perimetro del processo del sidecar.
Scelta del pattern
I tre pattern corrispondono a esigenze distinte sulla forma di rilascio:
- Server con metriche — servizi di lunga durata che il cluster mantiene attivi; più esposizioni di Service per separare il traffico.
- Job batch — esecuzione limitata; nessuna esposizione di Service; si basa su una ConfigMap emessa dalla Recipe o su uno stato esterno per l’input.
- Coppia con sidecar — pod multi-container con namespace di rete condiviso; il Service del sidecar espone l’esigenza trasversale.
Un quarto pattern — server stateful con volume persistente — imposta form: stateful e dichiara lo storage per replica tramite volumes.<name>.persistentTemplate; il provider helm emette uno StatefulSet per la forma stateful (vedi providers/helm.md). Il pattern ha forma identica a «server con metriche» con form: stateful, un volume persistentTemplate aggiuntivo e esattamente un servizio type: Headless che governa lo StatefulSet (senza di esso la compilazione si interrompe); gli autori che ne hanno bisogno adattano il Pattern 1 con tutte e tre le dichiarazioni.
Riferimenti incrociati
- ../../architecture/16-recipe-input-composition.md — ruolo architetturale del tipo Workload e superficie completa dello schema.
- ../entities/recipe.md — come
workload:si compone con gli altri due tipi di input della Recipe. - ../entities/component.md — authoring di
featuresSchemaa cui fanno riferimento i blocchiattachments:del Workload. - ../entities/featurerecipe.md — risorse ausiliarie a livello di Feature che affiancano i Workloads.
- ../vocabulary/data-pillars.md — contratto di accesso ai pilastri per la valutazione dei template.
- ../templates/expansion-matrix.md — dove si colloca la valutazione del Workload nella matrice di valutazione dei template.