Workload
O papel arquitetural do tipo Workload — porque existe, como se compõe com os outros dois tipos de entrada da Recipe (com source e artefactos) e a superfície completa do esquema — encontra-se em ../../architecture/16-recipe-input-composition.md. Esta página cobre a superfície de autoria do Workload: como um autor de Recipe escreve conteúdo de Workload, o que o compilador avalia e quando, como os campos do Workload interagem com o featuresSchema do Component, e que pilares os templates dentro de um Workload podem ler.
Local de autoria
O conteúdo de Workload é escrito inline ou a partir de um ficheiro, dentro de uma Recipe ou de uma FeatureRecipe (consulte FeatureRecipe). Uma Recipe declara no máximo um workload:; uma FeatureRecipe declara igualmente no máximo um próprio:
# Inline (block scalar)spec: workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload # ...ou
# File-loaded via $import: (path relative to the Recipe directory)spec: workload: $import: ./workload/workload.yamlAmbas as formas produzem o mesmo objeto Workload após a análise; a escolha é uma questão de ergonomia de autoria. Uma terceira forma importa um Workload partilhado entre Recipes a partir de uma entrada de uma WorkloadLibrary, pela sua identidade de nome simples: $import: <Library>#/workloads/<entry>. De acordo com o vocabulário unificado de importação de ficheiros, $import: aceita uma única fonte — consulte ../vocabulary/cross-document-ref.md para a distinção mais ampla entre $ref: / $import:.
O YAML de Workload não é escrito como uma entidade de catálogo autónoma. Não existe nenhum diretório catalog/workload/; a gramática de Workload existe apenas como conteúdo que uma Recipe ou uma FeatureRecipe consome — escrito inline, num ficheiro ao lado, ou numa entrada de uma WorkloadLibrary. As declarações de apiVersion e kind dentro do YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) identificam o conteúdo incorporado para a validação do esquema; não tornam o Workload endereçável de forma independente.
Avaliação de templates
O conteúdo de Workload é processado como template Go contra o contexto completo de pilares antes da análise. Quando um autor de Recipe escreve um template como o seguinte…
replicas: {{ optional .infra `replicas` 1 }}…o compilador avalia esse template durante a subpassagem de Workload da renderização, resolve .infra.replicas contra o payload infra do nó e analisa o YAML resultante como um documento Workload. Os locals da Recipe são resolvidos antes de o Workload ser avaliado, pelo que um template de Workload os lê, já resolvidos, em .locals.
Acesso aos pilares dentro dos templates de Workload:
.values— payload cognitivo escrito pelo programador, declarado no Aggregate..infra— dimensionamento físico escrito pelas Ops, declarado na Release..parameters— já interpolado na resolução; visível através de.values/.infrasempre que o programador ou as Ops referenciaram.parameters.<name>na sua autoria..locals— estado privado da Recipe, resolvido no preâmbulo de locals e publicado na resolução do source; disponível em todos os locais de avaliação de templates de Workload..context.instance_id— o ID de instância achatado do nó; o prefixo dos nomes de recursos que emite um provider que nomeia os recursos sintetizados com base na identidade..context.rendered_name— o nome que um provider que deriva o seu próprio nome para os recursos sintetizados lhes dá, como o nome de release do helm; presente apenas quando o provider reporta um. Consulte ../templates/rendered-resource-names.md..context.inject— o pipe de injeção pós-interceção, já reescrito por qualquerinjectMappingde FeatureRecipe durante o mapeamento de inject..context.uses— as arestas de topologia enriquecidas que saem deste nó, cada uma com osprovides, aslabelse as anotações em cascata resolvidos do destino e, em.context.uses.<alias>.features.<slot>, os anexos que essa ligação contém..features— os anexos próprios do nó, cada um com o seutype,values,infraeprovidesresolvidos. Um anexo com o nome de um slot que o Component declara emfeaturesSchemapreenche esse slot (ver abaixo). Um anexo que uma ligação contém não está entre eles; é lido sob a sua ligação, e um Workload entrega-o indicando a ligação (consulte Entregar uma credencial que uma ligação contém).
Consulte ../vocabulary/data-pillars.md para o contrato completo de acesso aos pilares e ../templates/expansion-matrix.md para saber onde se situa a avaliação de Workload na sequência de avaliação de templates.
Aspetos essenciais da semântica dos campos
O esquema completo de Workload encontra-se em ../../architecture/16-recipe-input-composition.md em «O tipo Workload». As convenções de autoria abaixo cobrem as decisões ao nível dos campos que um autor de Recipe toma.
form
form declara a forma abstrata de controlador do workload — o tipo de ciclo de vida de runtime que tem, independentemente de qualquer plataforma de destino. É uma única string, uma de stateless, stateful, daemon, scheduled, task, reference, e assume stateless por predefinição quando omitida:
stateless— réplicas intermutáveis, escaladas horizontalmente, sem identidade por réplica (o serviço de longa duração comum).stateful— réplicas com identidade estável por réplica e armazenamento por réplica. Um volumepersistentTemplateacompanha esta forma.daemon— uma instância por cada host elegível.scheduled— execuções recorrentes, acionadas por tempo.task— uma única execução até à conclusão.reference— sem contentores próprios: o componente representa um endpoint externo, indicado comoendpoint(um host ou URL, passado tal como está escrito) e umaportopcional. O fornecedor helm emite-o como um Service do tipoExternalName; o fornecedor compose não emite nada para ele.
A forma não contém, ela própria, tipos de recursos nativos da plataforma. Cada fornecedor de destino que sintetiza um Workload mapeia a forma para a sua própria forma nativa:
form | Kubernetes (helm) | Compose |
|---|---|---|
stateless | Deployment | serviço (sem volume persistente) |
stateful | StatefulSet | serviço + volume com nome |
daemon | DaemonSet | interrompe a compilação |
scheduled | CronJob | interrompe a compilação |
task | Job | interrompe a compilação |
Os fornecedores terraform e cloudformation renderizam Recipes com origem e Recipes apenas de artefactos e não sintetizam nenhum Workload: uma Recipe que declare workload: associada a qualquer um deles interrompe a compilação, indicando os tipos de entrada que o fornecedor suporta.
Quando um provider de destino não tem um mapeamento limpo para uma forma, a compilação é interrompida de forma explícita em vez de degradar o workload para uma forma que deturpa a intenção — escolher uma forma que uma fronteira de destino não consegue exprimir é um erro em tempo de compilação, não uma degradação silenciosa. O provider compose é interrompido perante daemon, scheduled e task. O provider helm emite um CronJob para scheduled (consulte schedule abaixo) e só é interrompido quando o seu agendamento está ausente ou mal formado.
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 é o agendamento cron de um workload form: scheduled — o campo complementar que dá à forma recorrente a sua recorrência. É uma única string num formato canónico:
- uma expressão crontab standard de 5 campos — minuto, hora, dia do mês, mês, dia da semana (por exemplo
0 0 * * *para todos os dias à meia-noite,*/15 * * * *para cada quinze minutos), ou - uma das macros
@hourly,@daily,@weekly,@monthly,@yearly.
schedule é obrigatório quando form: scheduled e só tem significado nesse caso. Um workload form: scheduled sem agendamento, um agendamento que não seja nem uma expressão de 5 campos nem uma macro reconhecida (uma expressão de 6 campos com prefixo de segundos, um token @ não reconhecido, ou um campo com caracteres inválidos), ou um schedule definido em qualquer outra forma é uma interrupção em tempo de compilação que indica a correção. O provider helm passa o valor literalmente para o spec.schedule do CronJob emitido.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # daily at 02:00containers: report: image: "reporter:1.0" command: ["/report"]suspend
suspend suspende o agendamento recorrente de um workload form: scheduled. É um booleano e assume false por predefinição. Com suspend: true, o recurso agendado continua a ser renderizado com o seu schedule no lugar, mas nenhuma execução arranca a partir desse agendamento até que seja retomado, e uma execução pode ainda ser iniciada manualmente a partir do recurso. É essa a forma para uma tarefa que só deve ser executada quando alguém a pedir.
O fornecedor helm emite o campo como o spec.suspend: true do CronJob. No Kubernetes, kubectl create job <name> --from=cronjob/<cronjob> inicia uma execução a partir do CronJob suspenso, e o agendamento é retomado assim que spec.suspend volte a ser false. suspend: false é renderizado exatamente como um suspend omitido, pelo que o campo não altera nenhuma saída até ser definido. O fornecedor compose não tem forma agendada e interrompe a compilação em qualquer workload form: scheduled, suspenso ou não.
suspend: true em qualquer outra forma é uma interrupção em tempo de compilação que indica a correção: nenhuma outra forma tem um agendamento que ele possa 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
Um único inteiro com o número de réplicas do workload. Assume 1 por predefinição quando omitido. Use uma expressão de template para definir as réplicas a partir do dimensionamento declarado pelas Ops:
replicas: {{ optional .infra `replicas` 1 }}containers vs. initContainers
containers é um mapa ordenado indexado pelo nome do contentor. O contentor 0 (a primeira chave do mapa) é relevante para a ordenação do pod-spec na saída Kubernetes e para a semântica do contentor predefinido. initContainers é uma lista ordenada de entradas de init-containers, cada uma com name, image e a mesma forma de autoria de variáveis/segredos/montagens de volumes que os contentores principais.
name é opcional numa entrada de initContainers. Uma entrada que o omita recebe o nome init-<index>, em que o índice é a posição da entrada na lista, a contar de 0. Como o nome identifica o contentor na saída renderizada e em qualquer diagnóstico que o indique, uma entrada a que valha a pena fazer referência merece um nome explícito.
A preservação da ordem do autor é um contrato essencial do modelo de Workload — o compilador emite containers, volumes, services, os ports dos contentores, as variables dos contentores e os attachments dos contentores, cada um pela ordem em que o autor da Recipe os declarou, em cada compilação. Os autores de Recipes podem confiar na forma ordenada: quando o que acontece em runtime depende da ordem (arranque de sidecars, encadeamento $(VAR) em variáveis de ambiente, volumeMounts que referenciam volumes declarados anteriormente), a ordem de autoria É a ordem de runtime dentro de cada uma dessas coleções. O ambiente de um contentor combina duas delas, e entre as duas os fornecedores de síntese escrevem primeiro as entradas lidas de anexos (attachments entregues as: env) e depois as variables simples, cada tipo pela ordem escrita — pelo que, num destino Kubernetes, uma variável pode referenciar, como $(NAME), qualquer variável lida de anexos do seu contentor e qualquer variável declarada antes dela (consulte a ordem do ambiente do fornecedor helm). Um contentor que dê um nome tanto como entrada de variables como como entrada de attachments entregue as: env interrompe a compilação, porque só essa ordem decidiria qual dos dois valores o processo vê (consulte A container gives one environment variable two values (Um contentor dá dois valores a uma mesma variável de ambiente)).
A autoria dos campos dos contentores segue estas convenções:
imageé normalmente uma expressão de template que referencia.values.image(a imagem selecionada pelo programador) com substituições.infra.*opcionais para prefixos de registo específicos do ambiente.variablesé um mapa simples de string → string para variáveis de ambiente. O mapa combina duas fontes de dados distintas através de expressões de template Go: literais do pilar do programador (entradas cujas expressões de template leem.values/.infra/.locals— payload proveniente dos pilares do Component) e dados do pipe entre componentes (entradas cujas expressões de template leem.context.inject.env.<KEY>— payload proveniente doprovides:de outro componente e encaminhado pelo pipe da topologia). As duas fontes fluem para o mesmo mapavariables; os autores escolhem uma por entrada consoante o valor seja local ao componente ou derivado de outro componente. Padrões comuns:LOG_LEVEL: "{{ .values.log_level }}"é do pilar do programador (local ao componente);DB_HOST: "{{ .context.inject.env.DB_HOST }}"é do pipe entre componentes (o valor provém doprovides.hostde um componente de destino, encaminhado pela declaraçãouses[].inject.env.DB_HOSTdo chamador). Ambas as formas são compiladas numa única lista Kubernetesenv:no Deployment renderizado; a semântica de dupla fonte existe apenas no momento da autoria.attachmentsreferencia slots declarados nofeaturesSchemado Component ou, indicando uma ligação, um slot que o socket dessa ligação declara (consulte a secção de integração abaixo).portsé um mapa de portas com nome (web: 8080,admin: 9901); os nomes das portas correspondem aos nomes de portas no âmbito do contentor e são referenciados porservices.<service>.ports.<portname>. Uma porta que use um transporte diferente do predefinido do destino é escrita, em vez disso, na forma expandida — consulte Protocolos de transporte das portas abaixo.volumeMountsreferencia pelo nome volumes declarados noutro local, na secçãovolumes:do Workload.resourcesdeclara osrequestselimitsdo contentor — as quantidades decpuememorye, opcionalmente, chaves de recursos estendidos para GPUs e outros dispositivos (consulte Cargas de trabalho de GPU e de dispositivos abaixo).healthusa a forma de intenção (http: /path,tcp: <port>,exec: [cmd, ...]) — consulte a secção Sondas de saúde abaixo.
volumes
Cada volume é exatamente de um tipo: ephemeral, configmap, secret, persistent ou persistentTemplate. Os tipos são mutuamente exclusivos numa única declaração de volume; cada tipo tem os seus próprios campos obrigatórios:
volumes: app-config: configmap: source: "{{ .locals.app_cm }}" data: persistent: size: "10Gi" class: "gp3" cache: ephemeral: sizeLimit: "1Gi"persistentTemplate produz um PVC por réplica para a tradução com forma de StatefulSet; na tradução para compose, degrada-se num único volume com nome partilhado, com um aviso reportado juntamente com a compilação. O próprio ficheiro gerado não contém nenhuma nota sobre a degradação — é, byte a byte, o que seria sem o aviso.
Tradução por provider. Cada provider traduz as cinco variantes de volume para a sua forma nativa:
| Variante | Helm / helm-chart (K8s) | Compose | Notas sobre perdas |
|---|---|---|---|
ephemeral | emptyDir: { sizeLimit } | entrada tmpfs: ao nível do serviço que indica o caminho de montagem (em memória) | O tmpfs do Compose é suportado por RAM; o emptyDir do helm é, por predefinição, suportado pelo disco do nó — divergência semântica no meio de armazenamento subjacente. sizeLimit não chega a nenhuma parte da saída compose: a entrada emitida é apenas o caminho de montagem. Um sizeLimit escrito gera um aviso unsupported-field que o indica, reportado juntamente com a compilação em vez de escrito no ficheiro gerado. |
configmap | Referência a um volume ConfigMap (consome um recurso ConfigMap emitido pelo artifacts: da Recipe ou por uma Feature) | Referência configs: ao nível do serviço que indica o configmap, montado no caminho da montagem do volume; a entrada configs: de nível superior correspondente vem do artifacts: da Recipe | Ambos os destinos referenciam o configmap pelo nome e nenhum lê o seu conteúdo, pelo que a forma de autoria é simétrica. O que o compose perde é a semântica de atualização no rollout do ConfigMap do K8s: uma config compose fica fixa no conteúdo que a compilação emitiu. Uma referência que nenhuma entrada de nível superior resolve interrompe a compilação em vez de emitir uma montagem que ficaria pendente em runtime. |
secret | Referência a um volume Secret (consome o Secret que um anexo de credenciais indica — um que a sua FeatureRecipe emite, ou um que já existe) | env_file: para segredos com forma de variáveis de ambiente, ou um ficheiro de segredo montado por bind para segredos com forma de caminho | O Compose não tem semântica de primeira classe de Secrets do Kubernetes. Um segredo com forma de caminho deliberadamente não segue a via configs: da variante configmap: uma entrada de config inline escreveria o valor do segredo em texto simples no ficheiro compose emitido, e o compilador nunca resolve um segredo em texto simples. A origem do bind é um caminho que o operador torna acessível no host compose, fora de qualquer ciclo de vida de CRD de obtenção a partir do cofre. |
persistent | Recurso PVC + volume.persistentVolumeClaim | Volume com nome | Os volumes com nome do Compose são uma abstração plana do lado do host; o PVC do helm suporta a declaração de classe de armazenamento, modo de acesso e capacidade, que o compose ignora. |
persistentTemplate | StatefulSet.volumeClaimTemplates (PVC por réplica; acompanha form: stateful) | Volume com nome (degradado — um único volume partilhado entre réplicas, com um aviso reportado) | O Compose não consegue exprimir templates por réplica. Quando persistentTemplate é traduzido para compose, é emitido um único volume com nome e a fidelidade reduzida é comunicada como aviso juntamente com a compilação, em vez de ser escrita no ficheiro gerado. Os Workloads que dependem do isolamento de volumes por réplica não devem ter como destino fronteiras apenas compose. |
A forma do controlador é escolhida pelo form do workload, não pelos seus volumes. É emitido um StatefulSet quando form: stateful; um volume persistentTemplate acompanha essa forma — declara armazenamento por réplica num workload que já tem a identidade por réplica que um StatefulSet fornece. Declarar um volume persistentTemplate em qualquer outra forma (ou na predefinida stateless) é um erro em tempo de compilação que indica a correção: declare form: stateful. O inverso é permitido — um workload form: stateful não precisa de declarar um volume persistentTemplate. Os autores que pretendam a semântica de StatefulSet definem form: stateful diretamente.
Um workload form: stateful no provider helm exige um Service de governo headless: declare exatamente um serviço com type: Headless no mesmo Workload. O provider liga o serviceName do StatefulSet a esse Service headless (que fornece as identidades de rede estáveis por pod de que um StatefulSet precisa). A compilação é interrompida se não for declarado nenhum serviço headless — um StatefulSet não tem Service de governo para indicar — ou se for declarado mais do que um, o que deixa o Service de governo ambíguo. Um workload StatefulSet pode ainda declarar serviços adicionais não headless (por exemplo, um serviço ClusterIP para acesso de clientes) ao lado do serviço de governo headless.
Quantidades de recursos
Estes valores de Workload são quantidades — montantes escritos na notação que o Kubernetes usa para recursos: os valores de resources.requests e resources.limits de um contentor (ou init container) para cpu, para memory e para cada chave de recurso estendido, e o ephemeral.sizeLimit, persistent.size e persistentTemplate.size de um volume. O esquema de Workload tipa cada um como string e não restringe a sua forma. O provider que sintetiza o Workload para um destino verifica todas as quantidades que emite, e verifica o Workload tal como os templates da Recipe o avaliaram, pelo que um valor que chegou através de infra, de um parâmetro da Release ou de qualquer outra entrada de template é avaliado pela string em que foi renderizado.
Uma quantidade é, sem nada antes nem depois:
- um sinal opcional,
+ou-; - um número com pelo menos um dígito —
2,0.5,.5ou1.; - no máximo um de: um expoente —
eouE, um sinal opcional e depois dígitos, como em1e3ou5E-2— ou um sufixo de unidade: um sufixo decimaln,u,m,k,M,G,T,PouE(de 10⁻⁹ a 10¹⁸, em passos de mil), ou um sufixo binárioKi,Mi,Gi,Ti,PiouEi(de 1024 a 1024⁶).
500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n e 4u são quantidades; lots, 1.5 cores, 1 gigabyte, 10 GB e 1e1.5 não são — um expoente é um número inteiro. Um E isolado depois do número é o sufixo decimal para 10¹⁸ (12E); seguido de dígitos, inicia um expoente (1E3).
Esta é a forma que o próprio analisador de quantidades do Kubernetes aceita, com uma diferença deliberada: uma string cujo número não tem nenhum dígito — m, Ki, +, ., e5 — é recusada, enquanto o Kubernetes a lê como zero. Essa string é exatamente o que um template deixa quando o valor que interpola está vazio: "{{ .infra.cpu }}m" com um cpu vazio renderiza m. Recusá-la transforma uma entrada vazia numa interrupção que indica o campo, em vez de num pedido de tamanho zero que nada reporta.
O que cada destino faz com uma quantidade:
- helm emite todas as quantidades literalmente, depois de verificar cada uma em relação à forma acima. Um valor fora dela interrompe a compilação com um erro que indica o nó, o caminho do campo no Workload —
containers.main.resources.requests.cpu,initContainers[0].resources.limits.memory,volumes.data.persistent.size— e o valor. Consulte Provider Helm → modo Workload (sintetizado). - compose converte
cpuememorynas suas próprias unidades a partir do valor analisado:cpustorna-se um número decimal de núcleos (500m→0.5) ememoryum número exato de bytes (1.5Gi→1610612736). Um valor que não seja uma quantidade interrompe a compilação, tal como uma quantidade que o compose não consegue representar exatamente — um montante negativo, um montante de memória que não seja um número inteiro de bytes (1500m), ou um montante de cpu mais fino do que nove casas decimais de um núcleo — e o erro diz qual dos dois encontrou. Uma contagemnvidia.com/gpué lida da mesma forma e torna-se uma contagem de dispositivos, pelo que uma que não seja um número inteiro de dispositivos também interrompe a compilação. O compose não emite nenhum outro recurso estendido nem nenhum tamanho de volume, pelo que não verifica nenhum deles: qualquer outra chave de recurso estendido e umephemeral.sizeLimitsão descartados com um aviso, e um tamanho persistente não determina nada na sua saída. Consulte Provider Compose → Recursos dos contentores.
A verificação avalia apenas a forma. Se um cluster consegue agendar o montante, ou se o montante é adequado ao seu dispositivo, está fora do seu âmbito.
services
Um mapa ordenado de exposições de serviço. Cada serviço declara o seu tipo (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — até onde chegam as suas portas — e um mapa de portas com nome. Os nomes das portas têm de corresponder a nomes de portas de contentores declarados noutro local do Workload:
services: http: type: ClusterIP ports: web: 8080 # must exist in containers.<name>.portsVários serviços num único Workload são comuns para expor separadamente o tráfego interno e externo (ClusterIP interno para consumidores dentro do cluster, LoadBalancer para tráfego externo, ClusterIP para scraping do Prometheus).
Até onde chegam as portas de um serviço. O type indica-o, e cada destino apresenta-o nos seus próprios termos:
type | Alcance | helm | compose |
|---|---|---|---|
ClusterIP | os pares do workload, na própria rede do destino | um Service do tipo ClusterIP | não publica nada; os pares alcançam a porta na rede compose |
Headless | o mesmo, sem endereço de cluster | um Service do tipo ClusterIP com clusterIP: None | não publica nada |
NodePort | para além da própria rede do destino | um Service do tipo NodePort | cada porta publicada em todas as interfaces do host, como <service port>:<container port> |
LoadBalancer | para além da própria rede do destino | um Service do tipo LoadBalancer | o mesmo que NodePort |
Loopback | apenas o próprio endereço de loopback do host | interrompe a compilação, indicando o serviço | cada porta publicada no endereço de loopback IPv4, como 127.0.0.1:<service port>:<container port> |
O número de uma porta de serviço e a porta de contentor que ela indica são dois números, tal como o port e o targetPort de um Service Kubernetes: o helm escreve o número da entrada como o port do Service e aponta para a porta de contentor pelo seu nome, e o compose publica o número da entrada no host sobre o número da porta de contentor. Quando os dois números são iguais, o compose escreve esse número em ambos os lados.
Loopback destina-se a uma porta que algo na mesma máquina alcança — um browser ou um agente em execução no host — e que mais nada deve alcançar. No compose, a associação é apenas ao endereço de loopback IPv4: o endereço de loopback IPv6 ::1 não é associado, pelo que a porta deve ser endereçada como 127.0.0.1 e não através de um nome que possa ser resolvido para ::1. Um transporte declarado é escrito na entrada como em qualquer porta publicada, como em 127.0.0.1:5514:5514/udp.
Quando duas entradas indicam a mesma porta, prevalece o alcance mais amplo: uma porta que uma entrada NodePort ou LoadBalancer publica é publicada em todas as interfaces mesmo quando uma entrada Loopback também a indica, seja qual for a que é declarada primeiro.
No helm, uma entrada Loopback para a compilação em vez de ser renderizada como algo que não é. Um Service Kubernetes não tem nenhum tipo que se associe ao endereço de loopback de um host — os endereços de nó em que um Service NodePort escuta são uma definição de todo o cluster, não de um Service — pelo que um Service ClusterIP descartaria o alcance que a entrada pede, e um NodePort publicaria a porta em todos os endereços de nó que o cluster permite. A interrupção indica o nó e o serviço; consulte A service type the helm provider cannot render (Um tipo de serviço que o provider helm não consegue renderizar).
Convenção de nomes sintetizados. Quando o fornecedor helm sintetiza os serviços de um Workload, o metadata.name de cada Service é derivado de forma determinística a partir do nome que o próprio controlador do workload tem e da chave de autoria do serviço. Para o Workload de um componente, esse nome é o nome de release do nó: <release name>-<service-key>. O nome de release é a identidade do componente escrita no alfabeto que um nome Kubernetes admite — o mesmo nome contra o qual um chart é renderizado, legível nos templates de uma Recipe como {{ .context.rendered_name }} — pelo que é igual ao instance_id sempre que a identidade não contém sublinhados nem maiúsculas. Um Workload que declare services.http no nó api-server produz um Service chamado api-server-http; o mesmo Workload no nó billing produz billing-http, e no nó my_api produz my-zuapi-http. O nome do ficheiro de saída segue a mesma convenção: <release name>-<service-key>-service.yaml. Uma Recipe que publique o endereço desse Service constrói-o a partir de {{ .context.rendered_name }}, nunca de {{ .context.instance_id }}, que não indica nenhum Service sempre que os dois diferem — consulte ../templates/rendered-resource-names.md.
Um Workload que a FeatureRecipe de um anexo de Feature sintetiza recebe o nome da identidade composta do próprio anexo, em vez de um nome de release: o valor que os seus recursos têm na sua etiqueta aggrega.ai/component-id, composto a partir do componente anfitrião e da chave escrita sob features:, depois do cfr-- inicial. Um nome de release derivado aí seria o do anfitrião, e daria aos recursos do anexo o nome dos recursos do próprio anfitrião. Assim, uma FeatureRecipe cujo Workload declare services.scrape, para um anexo stats no nó front-door, produz um Deployment cfr--front-door--stats e um Service cfr--front-door--stats-scrape. Esse primeiro segmento nunca é igual ao instance_id, e nenhuma chave no contexto de templates da FeatureRecipe o contém: nos templates de um anexo, {{ .context.rendered_name }} e {{ .context.instance_id }} indicam ambos o anfitrião (front-door) e {{ .attachment_name }} é apenas a chave (stats), pelo que {{ .context.rendered_name }}-scrape indica o próprio Service scrape do anfitrião, quando o anfitrião declara um, e nunca o do anexo — consulte ../templates/rendered-resource-names.md. O ficheiro de saída fica atrás do prefixo que todos os ficheiros emitidos por um anexo têm — o nome do anfitrião e o do anexo, cada um seguido de -- —, pelo que esse Service é escrito em front-door--stats--cfr--front-door--stats-scrape-service.yaml.
A convenção tem duas consequências práticas. Primeiro, as colisões entre nós são impossíveis por construção — o prefixo do nome diferencia os serviços entre todos os nós da fronteira, porque duas identidades distintas chegam sempre a dois nomes de release distintos, a identidade de um anexo contém tanto o seu anfitrião como a sua chave, e nenhum nome de componente pode começar por cfr-- (o build é interrompido perante um que o faça — consulte Component identity cannot be stamped on what it emits (A identidade do Component não pode ser carimbada no que ele emite)), pelo que dois Workloads que declarem cada um services.http produzem recursos Service do K8s distintos, com nomes que não se sobrepõem. O único resíduo é uma identidade de anexo demasiado longa para o destino: é encurtada em torno de um digest do todo, e duas identidades encurtadas podem, em princípio, coincidir — consulte Etiquetas de proveniência emitidas na saída renderizada. Segundo, um Workload não pode declarar a mesma chave de serviço duas vezes — um mapa services: que indique uma chave duas vezes é recusado quando o YAML do Workload é analisado, e o build é interrompido indicando a chave e a sua linha.
O risco de colisão que permanece está no limite de comprimento de nomes do K8s: os nomes de Services Kubernetes estão limitados a 63 caracteres, e a forma sintetizada <release name>-<service-key> pode exceder esse limite quando ambos os segmentos são longos. O compilador da Aggrega não impõe o limite; o build emite o Service, e o Kubernetes rejeita-o quando é aplicado. Os autores com IDs de instância profundamente aninhados (por exemplo, data-layer.regional.eu-west.primary) e chaves de serviço longas devem manter o comprimento combinado abaixo dos 63 caracteres. O mesmo se aplica ao Workload de um anexo: uma identidade composta demasiado longa para o destino é encurtada, mas a chave de serviço que lhe é acrescentada não é, pelo que um Service de um anexo com uma chave longa pode ainda assim exceder 63 caracteres e passar pelo build sem interrupção.
Nota específica do Provider (compose). O fornecedor compose deriva depends_on automaticamente das arestas uses da IR. Essas entradas são emitidas sem condição — têm a semântica service_started, independentemente de o destino declarar um healthcheck —, pelo que um serviço cujas dependências vêm todas de arestas uses emite a lista na forma curta (depends_on: [<target>]). Condicionar uma entrada derivada de uma aresta ao estado de saúde do destino não está implementado. A forma longa é emitida onde uma entrada tem de facto uma condição, que é como se exprime uma espera por um contentor de inicialização; consulte providers/compose.md.
Protocolos de transporte das portas
Uma porta de contentor é escrita numa de duas formas equivalentes. O número simples é a forma curta e não declara nenhum transporte, pelo que o destino aplica o seu próprio predefinido — TCP em todos os destinos que têm um:
containers: main: image: "{{ .values.image }}" ports: web: 8080A forma expandida contém o número e o transporte em conjunto, e é aquilo de que uma porta precisa quando usa algo diferente desse predefinido:
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: SCTPAs duas formas podem ser misturadas livremente num mesmo mapa ports, e uma porta sem transporte a declarar fica na forma curta.
O transporte é declarado uma vez, na porta do contentor. Uma entrada services.<service>.ports indica uma porta de contentor e leva consigo o transporte dessa porta, pelo que uma exposição de serviço não pode divergir da porta que o contentor abriu. Não existe nenhuma chave protocol numa porta de serviço, e escrever uma é rejeitado.
Porque existe o campo. Os destinos de implementação tratam um transporte não especificado como o de streaming. Um componente que precise de uma porta de datagramas — multimédia em tempo real, telefonia, resolução de nomes, redes privadas, um servidor de jogos — poderia, de outra forma, declarar apenas o número, e a stack seria implementada com todas as verificações a passar sem que nenhum cliente se ligasse, porque o tráfego é de datagramas e a porta que foi aberta não é. Declarar o transporte é o que torna isso exprimível.
O compilador não interpreta o valor. Não deduz nenhum transporte a partir do nome de uma porta e não verifica o transporte declarado em relação ao que o processo por trás da porta efetivamente fala: o valor é um dado que se declara e que o motor do destino emite. Uma porta chamada dns sem chave protocol é uma porta TCP, e uma porta chamada web que declare protocol: UDP é uma porta UDP.
Comportamento por destino.
| Destino | Uma porta sem transporte declarado | Um transporte declarado |
|---|---|---|
| helm | containerPort e a porta do Service não contêm nenhuma chave protocol | emitido literalmente como protocol: na porta do contentor e em todas as portas de Service que a indicam |
| compose | publicada como <host>:<container>, sem alterações | publicada como <host>:<container>/tcp ou /udp; SCTP não tem grafia em compose e interrompe a compilação em vez de publicar uma porta que usaria um transporte diferente |
Uma porta de contentor que nenhum serviço publica não chega a nenhuma parte de um ficheiro compose — é esse o comportamento habitual do compose para portas de contentores — pelo que um transporte declarado nessa porta não tem onde ser escrito e não interrompe a compilação.
Sondas de saúde — forma de intenção
Cada contentor declara as suas sondas sob a sua própria chave health: (containers.<name>.health), numa forma de intenção abstrata; o Workload não tem health de nível superior. Cada fornecedor traduz a intenção para a sua forma de sonda nativa no momento da síntese.
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: 10As três formas de intenção (http:, tcp:, exec:) são mutuamente exclusivas numa única declaração de sonda. A resolução da porta para http: sem porta explícita usa o primeiro nome de porta, por ordem alfabética, que o contentor declara em containers.<name>.ports — a mesma regra em ambos os destinos, pelo que uma sonda lê a mesma porta seja qual for o destino que a renderiza. Um contentor que não declare nenhuma porta com nome não pode ter uma sonda HTTP: a compilação é interrompida com um erro de tradução que indica a sonda em causa.
Tradução por provider. Cada provider traduz a intenção abstrata da sonda para a sua forma nativa no momento da síntese:
| Intenção | Helm (K8s) | Compose | Notas sobre perdas |
|---|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" | O Compose não tem uma forma nativa de sonda HTTP; o wrapper CMD-SHELL depende de o curl estar presente na imagem do contentor. |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" | O Compose não tem uma forma nativa de sonda TCP; o wrapper CMD-SHELL depende de o nc estar presente na imagem do contentor. |
exec: [cmd, ...] | exec.command: [cmd, ...] | CMD [cmd, ...] | Mapeamento um para um; ambos os providers transportam a lista de comandos literalmente. |
Os wrappers CMD-SHELL do Compose aproximam as sondas HTTP e TCP através de predicados avaliáveis pela shell. O que falta ao compose é a forma nativa da sonda, não os campos de temporização: os periodSeconds, timeoutSeconds, failureThreshold e initialDelaySeconds escritos são transportados para o healthcheck como interval, timeout, retries e start_period — providers/compose.md «Sondas» contém o mapeamento campo a campo. A forma nativa exec: não precisa de nenhum wrapper e é traduzida um para um em ambos os destinos.
Uma sonda com wrapper é traduzida silenciosamente: nada no docker-compose.yaml emitido a assinala, e nenhum diagnóstico reporta o wrapper. O que a compilação reporta neste percurso é um slot de sonda que não chega a nenhuma saída — um serviço compose tem um único healthcheck, pelo que, quando um Workload declara mais do que um de ready:, live: e startup:, apenas o slot preferido é traduzido (live antes de ready antes de startup) e um aviso unsupported-field indica o slot traduzido e os slots descartados.
Nota específica do Provider (compose). Escrever um bloco health: num Workload destinado ao compose não condiciona a ordem de depends_on ao estado de saúde: as entradas depends_on do fornecedor compose derivadas de arestas uses: usam sempre a semântica service_started, independentemente de o Workload de destino declarar sondas de saúde. Condicionar essas entradas ao estado de saúde do destino não está implementado — a forma longa que teria tal condição é ela própria emitida, para esperas por contentores de inicialização, pelo que o que falta é a escolha de condicionar uma aresta ao estado de saúde, e não a forma de o exprimir. Consulte providers/compose.md para as regras de inferência completas.
Campos de passagem com forma K8s — scheduling, serviceAccount, podSecurityContext
O esquema de Workload aceita três campos opcionais de nível superior que existem principalmente para fazer passar primitivas nativas do Kubernetes pelo fornecedor helm, preservando a forma estrutural da Aggrega. O fornecedor compose traduz o subconjunto que tem um análogo em Compose e ignora o resto com um aviso emitido. A Aggrega valida a forma exterior, mas não controla o conteúdo interior (consulte Superfície de validação abaixo) — os valores interiores nativos do K8s passam literalmente para o pod spec renderizado pelo helm.
scheduling
scheduling agrupa quatro primitivas de agendamento nativas do K8s — nodeSelector, affinity, tolerations, topologySpreadConstraints — num único bloco organizado por finalidade. Cada subcampo tem exatamente a forma do campo correspondente do pod-spec do 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: "..." }Tradução pelo Provider. O fornecedor helm passa cada subcampo literalmente para o pod spec renderizado. O fornecedor compose não traduz nenhum dos quatro: omite todo o bloco scheduling, e um aviso indica-o.
serviceAccount
serviceAccount é uma string simples que contém o nome da ServiceAccount com que o workload é executado:
apiVersion: aggrega.ai/v1beta1kind: WorkloadserviceAccount: "{{ .context.rendered_name }}-runner"containers: app: { image: "..." }O nome é construído a partir de {{ .context.rendered_name }}, o nome de release com base no qual o provider helm nomeia os recursos próprios do workload, pelo que é um nome que o cluster aceita, seja qual for o nome do componente. O campo referencia uma ServiceAccount existente; não cria nenhuma. Os recursos RBAC associados (o próprio objeto ServiceAccount, mais Role / RoleBinding / ClusterRole / ClusterRoleBinding) devem ser disponibilizados por um de dois canais:
artifacts:da Recipe — quando o RBAC é intrínseco a esta Recipe (a Recipe sabe que precisa de uma Role específica para um trabalho específico).- Features com Resource Generation — quando o RBAC é transversal (uma FeatureRecipe de Workload-Identity que anexa ServiceAccounts associadas a IAM a todos os componentes com uma determinada etiqueta).
Definir serviceAccount: sem garantir que a ServiceAccount indicada existe resulta num erro K8s em runtime no momento do apply, e não num erro em tempo de compilação — a validação do esquema do workload não verifica a existência da ServiceAccount (não há acesso ao estado do cluster em tempo de compilação, de acordo com o invariante de pureza AOT).
O provider compose ignora serviceAccount: com um aviso; o Compose não tem nenhum conceito equivalente de associação de identidade.
podSecurityContext
podSecurityContext contém primitivas de segurança ao nível do pod — UID, GID, fsGroup, supplementalGroups — que se aplicam a todos os contentores do pod:
apiVersion: aggrega.ai/v1beta1kind: WorkloadpodSecurityContext: runAsUser: 1000 runAsGroup: 3000 fsGroup: 2000 supplementalGroups: [4000, 5000]containers: app: { image: "..." }Semântica dos campos. Os quatro campos são inteiros (UIDs/GIDs numéricos, não strings); runAsUser e runAsGroup definem o UID/GID efetivo dos processos do contentor; fsGroup define a titularidade de grupo dos volumes montados no pod; supplementalGroups acrescenta GIDs adicionais ao grupo de processos de cada contentor.
Tradução pelo Provider. O fornecedor helm passa o bloco literalmente para o pod spec renderizado. O fornecedor compose não tem equivalente para fsGroup nem supplementalGroups e omite cada um com um aviso; runAsUser/runAsGroup traduzem-se na forma Compose user: 1000:3000 em todos os serviços que o Workload produz, incluindo sidecars e contentores de inicialização, e um runAsGroup sem um runAsUser ao lado é omitido com um aviso. Cada contentor e contentor de inicialização tem também o seu próprio securityContext — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation e capabilities.add / capabilities.drop. O fornecedor helm emite-o no contentor; o fornecedor compose emite readOnlyRootFilesystem como read_only, capabilities.add / capabilities.drop como cap_add / cap_drop, e runAsUser / runAsGroup como o próprio user do contentor, que toma o lugar do do pod; omite runAsNonRoot, allowPrivilegeEscalation e um runAsGroup escrito sem um runAsUser, com um aviso cada, e avisa também quando o próprio runAsUser de um contentor deixa de fora o runAsGroup do pod. providers/compose.md apresenta o mapeamento campo a campo.
Cargas de trabalho de GPU e de dispositivos
Um workload que precise de hardware especializado — uma GPU, ou outro dispositivo fornecido por um fabricante — exprime duas preocupações independentes: o runtime ao nível do pod que o nó com o dispositivo expõe (runtimeClassName), e a quantidade por contentor do dispositivo que o workload reclama (uma chave de recurso estendido sob os resources de um contentor). Um workload de GPU típico declara ambos em conjunto, mas cada um é independente e qualquer um pode aparecer sem o outro.
Ambos os campos descrevem computação — o pod e o contentor que é executado no dispositivo — pelo que pertencem a um workload que executa contentores. Um workload que contenha apenas um endpoint externo e não declare contentores próprios não tem pod nem contentor a que os associar: definir runtimeClassName num workload só de endpoint interrompe a compilação, indicando runtimeClassName e a Recipe cujo Workload o declarou, e sem contentores não há onde colocar um pedido de recurso de dispositivo.
runtimeClassName
runtimeClassName é uma única string que indica a RuntimeClass com que o pod é executado — o runtime de contentores que um nó com o dispositivo expõe, por exemplo um runtime de GPU chamado nvidia. É um seletor ao nível do pod: aplica-se a todos os contentores do workload. O compilador passa o nome literalmente como um ponteiro determinístico; o cluster resolve-o para uma RuntimeClass que o seu administrador configurou, no momento do agendamento. A Aggrega não verifica se existe uma RuntimeClass correspondente — não tem acesso ao estado do cluster em tempo de compilação — pelo que um nome sem RuntimeClass configurada surge como um erro de agendamento no momento do apply, e não como um erro em tempo de compilação.
Chaves de recursos estendidos
Os resources.requests e resources.limits de um contentor contêm as quantidades habituais de cpu e memory e, a par delas, chaves de recursos estendidos: quantidades de dispositivos com âmbito de fabricante ou de domínio, indexadas por um nome totalmente qualificado <domain>/<name>, como nvidia.com/gpu ou amd.com/gpu. O segmento de domínio contém pelo menos um ponto, e é esse ponto que distingue uma chave estendida (nvidia.com/gpu) das quantidades simples cpu e memory. Cada valor é uma quantidade em string ("1", "2") que o compilador passa literalmente, e o provider helm verifica a sua forma antes de a emitir (consulte Quantidades de recursos); o plugin de dispositivos do cluster resolve e atribui o dispositivo no momento do agendamento.
Exemplo completo — um workload de inferência com 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"O workload seleciona o runtime nvidia para o seu pod e reclama uma GPU para o contentor inference. A quantidade de GPU aparece tanto em requests como em limits: um dispositivo não pode ser sobrealocado, pelo que o seu pedido e o seu limite são definidos com o mesmo valor.
Tradução por provider. Estes são conceitos nativos do Kubernetes. O provider helm emite runtimeClassName no pod spec renderizado e cada chave de recurso estendido literalmente sob os resources.requests / resources.limits do contentor, pelo que chegam ao cluster através da saída Kubernetes. O provider compose reserva uma contagem nvidia.com/gpu como esse número de GPUs NVIDIA no serviço do contentor (consulte Provider Compose → Recursos dos contentores); um único host não tem conceito de runtime class nem análogo para qualquer outra chave de recurso estendido, pelo que um workload que declare runtimeClassName ou outra chave é renderizado num destino compose sem eles.
Executar na rede do nó
Por predefinição, um workload é executado num espaço de nomes de rede próprio: os seus contentores veem apenas as suas próprias interfaces, e o tráfego chega-lhes através da tradução de endereços do destino. hostNetwork: true pede a outra disposição — o workload é executado no próprio espaço de nomes de rede do nó, pelo que vê as interfaces do nó e as portas que os seus contentores abrem são acessíveis nos próprios endereços do nó, sem nenhuma tradução pelo meio.
É disso que toda uma classe de software precisa. A multimédia em tempo real, a telefonia, as redes privadas virtuais e tráfego semelhante transportam o endereço do par dentro do payload, pelo que um endereço reescrito em trânsito chega a descrever um local que o par não consegue alcançar; executar nos endereços do nó é o que mantém os dois coerentes.
apiVersion: aggrega.ai/v1beta1kind: WorkloadhostNetwork: truecontainers: media: image: "{{ .values.image }}" ports: rtp: port: 7881 protocol: UDPO que declara e o que não declara
hostNetwork escolhe um espaço de nomes de rede, e é tudo.
- Não declara portas. As portas que um workload abre continuam a ser declaradas em
containers.<name>.ports, exatamente como sem ele, e continuam a significar o mesmo. DeclararhostNetworknão acrescenta nenhuma porta nem elimina a necessidade de declarar uma. - Não declara nenhum número de portas. Uma aplicação que pretenda muitas portas contíguas — um servidor de multimédia que dimensiona um intervalo de acordo com o número de processadores de uma máquina, por exemplo — configura esse intervalo no seu próprio corpo de configuração, a partir de valores que o seu operador fornece, da mesma forma que configura qualquer outra coisa que lê no arranque. Trata-se de uma definição da aplicação e não do workload, e o contrato do workload não é o seu lugar.
- Nada é inferido. O compilador não atribui nenhum significado ao valor e não o deriva de mais nada: nem do nome de uma porta, nem do tipo ou das etiquetas de um componente, nem de quantas portas estão declaradas. Um workload é executado na rede do nó quando, e só quando, o declara.
Como descreve computação, hostNetwork pertence a um workload que executa contentores. Um workload que contenha apenas um endpoint externo não declara contentores, pelo que não tem nenhum espaço de nomes de rede para escolher: declarar hostNetwork num workload só de endpoint interrompe a compilação, indicando hostNetwork e a Recipe cujo Workload o declarou.
Tradução pelo Provider
O provider helm emite hostNetwork: true no pod spec renderizado, que é a forma como o Kubernetes exprime a mesma escolha. A declaração chega ao pod spec e a mais nada — os Services emitidos são idênticos com e sem ela.
O provider compose emite network_mode: host no próprio serviço do workload. Daí decorre uma consequência da forma como o compose modela as redes: um serviço nesse modo não está ligado à rede da fronteira, porque o compose trata a ligação a uma rede e a adoção do espaço de nomes do host como alternativas e não como acréscimos. Os seus pares alcançam-no, portanto, nos próprios endereços do host em vez de pelo nome do serviço — que é o que a rede do host significa em qualquer destino — e todos os outros serviços da fronteira não são afetados.
Há duas formas que se combinam com ele nesse destino. Um contentor sidecar segue o serviço principal para a rede do host sem declarar nada, porque adota o espaço de nomes do serviço principal ao indicá-lo. Um init container não o faz: torna-se um serviço pelo qual o serviço principal espera, pelo que se junta à rede da fronteira por direito próprio em vez de adotar um espaço de nomes que tornaria essa espera circular. Um workload que declare tanto hostNetwork como initContainers executa, portanto, o seu próprio serviço na rede do nó enquanto os seus serviços de init permanecem na rede da fronteira — uma disposição mais restrita do que o único espaço de nomes partilhado que a forma de pod oferece, e que o provider compose indica num aviso unsupported-field em vez de a deixar para ser descoberta em runtime.
Um workload que não declare hostNetwork não tem essa chave na sua saída: a chave está ausente, em vez de ser emitida como false.
Integração dos anexos com o featuresSchema do Component
O bloco containers.<name>.attachments do Workload referencia slots de credenciais declarados no featuresSchema do Component — ou, para uma entrada que indique uma ligação, um slot que o socket dessa ligação declara (consulte Entregar uma credencial que uma ligação contém); não declara novos slots. Consulte ../entities/component.md para a superfície de autoria de featuresSchema. from indica o slot; não é o nome do Secret gerado.
Uma entrada containers.<name>.attachments é renderizada como uma referência a um recurso Secret — um secretKeyRef do Kubernetes (para as: env) ou um volume suportado por um segredo (para as: file) — ambos apontando para o Secret pelo nome. O sintetizador resolve esse nome e a chave de dados a partir dos provides expostos pelo slot: o secretKeyRef.name renderizado da entrada é o .features.<slot>.provides.name do slot e a chave de dados é .features.<slot>.provides.key. O autor da Recipe escreve apenas from: <slot> e as: env; o sintetizador lê os provides resolvidos — não volta a derivar o nome. Esta é a mesma leitura .features.<slot>.provides.<key> que uma Recipe com source usa para um existingSecret: um único slot de credenciais alimenta de forma idêntica um consumidor Recipe com source e um consumidor Workload sintetizado (simetria source/workload).
Quatro regras de validação regem a integração:
- Cada valor
attachments.<KEY>.fromtem de corresponder a um nome de slot declarado nofeaturesSchemado Component — ou, numa entrada que indique uma ligação, no socket dessa ligação. Um nome de slot desconhecido é um erro no carregamento. - O mecanismo de entrega
as:(envoufile) tem de constar da allowlistinject:do slot declarada pelo Component. Um Workload que declareas: filecontra um slot cuja entrada defeaturesSchemaespecificainject: [env]é um erro no carregamento. - Os slots marcados com
inject: [](entrega em caixa negra) nofeaturesSchemado Component não podem aparecer de todo em blocosattachments:de Workload. Esses slots são entregues pela canalização interna da Recipe (o parâmetroexistingSecretde um chart Helm, por exemplo), e não por exposição no Workload. - O slot referenciado tem de ser referenciável — o seu preenchimento tem de publicar um localizador
provides(name,key) para um recurso Secret, um que a sua realização emita ou um que já exista. Um slot preenchido por uma credencial entregue por inject (uma que escreve um valor no pipe de inject e não publica nenhum localizador) não tem nada para que apontar; referenciá-lo a partir de uma entradaattachments:de Workload é um erro no carregamento. Uma credencial entregue por inject chega ao contentor através do pipe de inject do slot (uma entrada devariablesque lê.context.inject.env.<KEY>), e não através de uma entradaattachments:.
Nota sobre o Provider. O Helm renderiza a referência secretKeyRef/volume de secret descrita acima. O fornecedor compose não tem uma primitiva nativa de ambiente a partir de um secret; uma entrada de anexo as: env num Workload destinado ao compose é renderizada como uma entrada de ambiente com valor vazio e um aviso que nomeia a entrada (consulte a página do fornecedor compose), continuando a aplicar-se a regra de referenciabilidade (agnóstica em relação às capacidades).
Exemplo:
# 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 uma credencial que uma ligação contém
O socket de um Component pode declarar, em usesSchema.<socket>.featuresSchema, os slots que cada ligação feita através dele preenche — pelo que um componente que alcança vários destinos tem uma credencial por ligação em vez de uma para todos. Um anexo deste tipo não está entre os .features próprios do componente; fica sob a sua ligação, em .context.uses.<alias>.features.<slot>. Uma entrada de Workload entrega-o indicando a ligação ao lado do slot:
- numa entrada
attachmentsde um contentor,connection: <alias>ao lado defrom: <slot>; - numa entrada
envFromde um contentor,connection: <alias>ao lado desecret: <slot>—connectionsó é aceite ao lado desecret.
Ambas as formas são aceites em todos os contentores e em todos os init containers. <alias> é o nome com que a ligação é escrita no bloco uses do componente, no Aggregate ou na Release — a chave pela qual uma Recipe lê a ligação em .context.uses — e <slot> é um slot que o socket através do qual essa ligação é feita declara.
Antes de qualquer regra acima ler o Workload, cada entrada que indique uma ligação é reescrita com o nome que o anexo que essa ligação contém nesse slot assume no componente: o alias, um ponto e o slot (gpt.credential). Todas as regras são então aplicadas à entrada reescrita exatamente como a uma entrada que indique um dos slots próprios do Component: a allowlist inject: do slot do socket rege as:, um slot de socket que declare inject: [] não pode ser referenciado, o anexo que o preenche tem de ser referenciável, e o provider resolve o nome do Secret e a chave de dados a partir dos provides resolvidos desse anexo — pelo que a entrada de cada ligação referencia a credencial própria dessa ligação. Um slot de socket que declare sensitive: true é lido para a entrada exatamente como a declaração de um slot do Component. A entrada reescrita é o que o provider recebe; a chave connection não lhe chega.
Há três entradas que são recusadas, cada uma indicando o que indicou:
- uma entrada que indique uma ligação que o componente não traça — a recusa indica a ligação, o slot e as ligações que o componente traça;
- uma entrada que indique um slot que o socket da ligação não declara — a recusa indica o slot, a ligação, o socket e os slots que declara;
- uma entrada que escreva diretamente o nome composto (
from: gpt.credential). O slot de uma ligação é indicado indicando a ligação, pelo que o nome composto nunca é uma segunda forma de o alcançar.
Uma ligação que não contenha nenhum anexo no slot deixa a entrada sem nada para referenciar, e a regra de referenciabilidade recusa-a. Um Workload que uma FeatureRecipe renderiza está limitado aos slots que a Feature que implementa declara, que não chegam a nenhuma das ligações do componente anfitrião, pelo que uma entrada aí que indique uma ligação é recusada por indicar uma que o componente não traça.
Exemplo:
# 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: envNo helm, MODEL_KEY_GPT é renderizado como um secretKeyRef que indica o Secret que a credencial da ligação gpt publicou, e MODEL_KEY_NIM o que a da ligação nim publicou. No compose, uma entrada as: env que indique uma ligação é emitida com um valor vazio e o mesmo aviso de suporte parcial que recebe uma entrada que indique um dos slots próprios do Component.
Superfície de validação
Todos os Workloads são validados no carregamento da Recipe, antes de qualquer renderização. A validação tem duas fases:
- Validação do esquema. O valor do Workload é unificado com o esquema de Workload
aggrega.ai/v1beta1incorporado. Os erros contêm o caminho do campo e a restrição violada (por exemplo,.containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). A validação do esquema impõe todos os tipos, enumerações, intervalos e disjunções declarados no esquema — incluindo oformde controlador de conjunto fechado (um destateless,stateful,daemon,scheduled,task,reference), otypede serviço de conjunto fechado (um deClusterIP,Headless,NodePort,LoadBalancer,Loopback), o intervalo inteiro de portas (1..65535), a disjunção de forma de sonda (exatamente um dehttp,tcp,exec) e a disjunção de variante de volume (exatamente um deephemeral,configmap,secret,persistent,persistentTemplate). - Validação de referências cruzadas. As referências de anexos do Workload são verificadas contra o
featuresSchemado Component — e, para uma entrada que indique uma ligação, contra os slots que o socket dessa ligação declara — (pertença ao slot, allowlist de entregaas:, exclusão de caixa negra) e contra os provides resolvidos de cada slot referenciado (referenciabilidade — o preenchimento tem de publicarname/key). Estas são verificações entre entidades que a validação apenas de esquema não consegue realizar.
Ambas as fases produzem a mesma forma de mensagem com o prefixo CATALOG_ERROR; as falhas param a compilação antes de ser produzida qualquer saída de renderização. Os autores de Recipes recebem feedback preciso que identifica o campo exato que falhou e a restrição que o rejeitou.
Os campos de passagem com forma K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, as listas items dentro de volumes ConfigMap e Secret, hooks de ciclo de vida httpGet) são validados apenas estruturalmente — o esquema da Aggrega restringe a sua presença e forma exterior, mas a forma interior destes valores definidos pela API do K8s é da responsabilidade do provider (o provider helm passa-os literalmente para o pod spec K8s; o provider compose rejeita-os ou degrada-os conforme adequado). Um Workload que use um valor affinity mal formado passa a validação da Aggrega e o erro surge, em vez disso, durante a síntese do provider.
As quantidades de recursos são strings para o esquema da mesma forma: nenhuma das fases verifica a sua forma. O provider de síntese fá-lo, sobre o Workload avaliado, e interrompe a compilação perante um valor fora da forma de quantidade — consulte Quantidades de recursos.
Os recursos auxiliares ficam fora do Workload
O Workload descreve apenas a forma do workload — contentores, volumes, serviços, réplicas, agendamento, contexto de segurança, service account. Não tem nenhum campo additionalResources nem declarações inline de ConfigMap / Secret / CRD.
Os autores de Recipes emitem recursos auxiliares através de dois canais fora do Workload:
artifacts:ao nível da Recipe — para recursos intrínsecos a esta Recipe (um ConfigMap específico que o Workload da Recipe referencia, um registo pontual de CRD de que a Recipe precisa). O campo é um mapa de entradas com nome; cada entrada é escrita inline ou carregada através de um$import:por entrada. Consulte a secção «Mecanismo de artefactos» em ../../architecture/16-recipe-input-composition.md para os três modos de autoria.- Features com Resource Generation — para preocupações transversais anexadas através de seletores da Release (uma Feature ServiceMonitor anexada a todos os componentes com métricas expostas, uma Feature NetworkPolicy anexada a todos os workloads de produção). Consulte ../entities/featurerecipe.md para a superfície de autoria da FeatureRecipe.
O Workload mantém-se focado na forma do workload; os manifestos auxiliares transversais e intrínsecos à Recipe têm os seus próprios locais de autoria.
Padrões comuns de Workload
O esquema de Workload é amplo — abrange servidores HTTP de contentor único, padrões de sidecar com vários contentores, cadeias de init containers, jobs batch e serviços stateful com volumes persistentes. Três padrões repetem-se com frequência suficiente para que escrever o boilerplate de raiz em cada Recipe seja um desperdício. Os blocos abaixo são templates para copiar e colar que os autores de Recipes podem adaptar a componentes específicos.
Um padrão que várias Recipes partilham pode ser publicado uma vez como entrada de uma WorkloadLibrary e importado com $import: <Library>#/workloads/<entry>; os modelos aqui apresentados são pontos de partida a adaptar, ou a publicar dessa forma.
Padrão 1 — servidor com exposição de métricas
Uma aplicação web típica que serve tráfego da aplicação numa porta e expõe métricas recolhidas pelo Prometheus numa porta separada. Dois serviços no Workload — um para a aplicação, outro para as métricas — mantêm a política de service mesh e a configuração do balanceador de carga claramente separáveis.
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 }}O serviço de métricas é normalmente anotado para descoberta pelo Prometheus através de um anexo de Feature na superfície da Release (por exemplo, feature.aggrega.ai/prometheus-scrape: "true"); o próprio Workload fica livre de anotações de scraping específicas do provider.
Padrão 2 — job batch
Um workload que é executado até à conclusão em vez de servir tráfego indefinidamente. O padrão define form: task, omite totalmente services: — os jobs batch não expõem portas — e depende da forma de tarefa do fornecedor de destino (um Job do Kubernetes no fornecedor helm; o fornecedor compose não tem forma de tarefa e interrompe a compilação perante form: task). O fornecedor helm fixa uma restartPolicy de pod válida para Jobs (Never, a menos que o contentor declare OnFailure), uma vez que um pod de Job não pode usar o predefinido 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"O volume de configuração referencia um ConfigMap que se espera que a Recipe emita a par do Workload através de artifacts: (consulte «Os recursos auxiliares ficam fora do Workload» acima) — o próprio Workload declara apenas o lado do consumo. A identidade dá-lhe nome num provider que nomeia o workload com base na identidade, como faz o compose; no helm, que nomeia os recursos do workload com base no nome de release, construa em vez disso o nome do ConfigMap — aqui e no artefacto — a partir de {{ .context.rendered_name }}, para que seja um nome que o cluster aceita, seja qual for o nome do componente.
Padrão 3 — par com sidecar
Um pod com dois contentores em que o contentor principal trata a lógica da aplicação e o sidecar trata uma preocupação transversal (terminação TLS, envio de logs, proxy de service mesh, guardrail de IA). A ordem do autor em containers: é essencial — o provider helm emite os contentores pela ordem declarada; a primeira chave (aqui, main) é o contentor predefinido para kubectl logs e ferramentas semelhantes.
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 }}O Service expõe a porta do sidecar (não a do contentor principal), encaminhando o tráfego externo através do sidecar para o contentor principal via localhost. Os dois contentores partilham o espaço de nomes de rede do pod, pelo que localhost:<port> alcança diretamente o contentor par. Para sidecars que precisam de injeção de credenciais (o padrão canónico de guardrail de IA), a credencial fica normalmente no bloco attachments: do sidecar e não no do contentor principal — mantendo a credencial limitada à fronteira de processo do sidecar.
Seleção de padrões
Os três padrões correspondem a preocupações distintas quanto à forma de disponibilização:
- Servidor com métricas — serviços de longa duração que o cluster mantém ativos; várias exposições de Service para separação do tráfego.
- Job batch — execução limitada; sem exposição de Service; depende de um ConfigMap emitido pela Recipe ou de estado externo como entrada.
- Par com sidecar — pod com vários contentores e espaço de nomes de rede partilhado; o Service do sidecar expõe a preocupação transversal.
Um quarto padrão — servidor stateful com volume persistente — define form: stateful e declara armazenamento por réplica através de volumes.<name>.persistentTemplate; o provider helm emite um StatefulSet para a forma stateful (consulte providers/helm.md). O padrão tem forma idêntica a «servidor com métricas», com form: stateful, um volume persistentTemplate adicional e exatamente um serviço type: Headless para governar o StatefulSet (a compilação é interrompida sem ele); os autores que precisem dele adaptam o Padrão 1 com as três declarações.
Referências cruzadas
- ../../architecture/16-recipe-input-composition.md — papel arquitetural do tipo Workload e superfície completa do esquema.
- ../entities/recipe.md — como
workload:se compõe com os outros dois tipos de entrada da Recipe. - ../entities/component.md — a autoria de
featuresSchemaque os blocosattachments:de Workload referenciam. - ../entities/featurerecipe.md — recursos auxiliares ao nível da Feature que coexistem com os Workloads.
- ../vocabulary/data-pillars.md — contrato de acesso aos pilares para a avaliação de templates.
- ../templates/expansion-matrix.md — onde se enquadra a avaliação de Workload na matriz de avaliação de templates.