Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Workload

O papel arquitetural do tipo Workload — por que ele existe, como ele se compõe com os outros dois tipos de entrada de uma Recipe (sourced e artifacts) e toda a superfície do esquema — está em ../../architecture/16-recipe-input-composition.md. Esta página cobre a superfície de autoria do Workload: como um autor de Recipe escreve o conteúdo de um Workload, o que o compilador avalia e quando, como os campos do Workload interagem com o featuresSchema do Component e quais pilares os templates dentro de um Workload podem ler.

Local de autoria

O conteúdo de um Workload é escrito inline ou a partir de um arquivo, dentro de uma Recipe ou de uma FeatureRecipe (consulte FeatureRecipe). Uma Recipe declara no máximo um workload:; uma FeatureRecipe também declara 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.yaml

Ambas 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 compartilhado 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 arquivos, $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 independente. Não existe diretório catalog/workload/; a gramática de Workload existe apenas como conteúdo que uma Recipe ou FeatureRecipe consome — escrito inline, em um arquivo ao lado dela ou em uma entrada de uma WorkloadLibrary. As declarações apiVersion e kind dentro do YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) identificam o conteúdo incorporado para a validação do esquema; elas não tornam o Workload endereçável de forma independente.

Avaliação de templates

O conteúdo de um Workload é processado como template Go com o contexto completo dos 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 subetapa de Workload da renderização, resolve .infra.replicas em relação ao 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, então um template de Workload os lê, já resolvidos, em .locals.

Acesso aos pilares dentro de templates de Workload:

  • .values — payload cognitivo escrito pelo desenvolvedor e declarado no Aggregate.
  • .infra — dimensionamento físico escrito por Ops e declarado na Release.
  • .parameters — já interpolados na resolução; visíveis por meio de .values / .infra sempre que o desenvolvedor ou Ops tenham referenciado .parameters.<name> no que escreveram.
  • .locals — estado privado da Recipe resolvido no preâmbulo de locals e publicado na resolução das fontes; disponível em todo ponto 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 provedor que nomeia os recursos sintetizados conforme a identidade.
  • .context.rendered_name — o nome que um provedor que deriva por conta própria o nome dos recursos sintetizados dá a eles, como o nome de release do helm; presente apenas onde o provedor informa um. Consulte ../templates/rendered-resource-names.md.
  • .context.inject — o pipe de injeção após a interceptação, já reescrito por qualquer injectMapping de FeatureRecipe durante o mapeamento da injeção.
  • .context.uses — as arestas de topologia enriquecidas que saem deste nó, cada uma carregando os provides, os labels e as anotações em cascata resolvidos do destino e, em .context.uses.<alias>.features.<slot>, as vinculações que essa conexão carrega.
  • .features — as vinculações próprias do nó, cada uma carregando o seu type, values, infra e os provides resolvidos. Uma vinculação nomeada conforme um slot que o Component declara em featuresSchema preenche esse slot (veja abaixo). Uma vinculação que uma conexão carrega não está entre elas; ela é lida sob a sua conexão, e um Workload a entrega nomeando a conexão (consulte Entregando uma credencial que uma conexão carrega).

Consulte ../vocabulary/data-pillars.md para o contrato completo de acesso aos pilares e ../templates/expansion-matrix.md para saber onde a avaliação do Workload se situa na sequência de avaliação de templates.

Fundamentos da semântica dos campos

O esquema completo do Workload está em ../../architecture/16-recipe-input-composition.md, em “O tipo Workload”. As convenções de autoria a seguir cobrem as decisões no nível de campo que o autor de uma Recipe toma.

form

form declara a forma abstrata de controlador da carga de trabalho — o tipo de ciclo de vida em tempo de execução que ela tem, independentemente de qualquer plataforma de destino. É uma única string, uma de stateless, stateful, daemon, scheduled, task, reference, e o padrão é stateless quando omitida:

  • stateless — réplicas intercambiáveis, escaladas horizontalmente, sem identidade por réplica (o serviço comum de longa duração).
  • stateful — réplicas com identidade estável por réplica e armazenamento por réplica. Um volume persistentTemplate é um complemento dessa forma.
  • daemon — uma instância por host elegível.
  • scheduled — execuções recorrentes, acionadas por tempo.
  • task — uma única execução até a conclusão.
  • reference — nenhum contêiner próprio: o componente representa um endpoint externo, informado como endpoint (um host ou URL, repassado como está escrito) e uma port opcional. O provedor helm o emite como um Service do tipo ExternalName; o provedor compose não emite nada para ele.

A forma não carrega, por si só, nenhum tipo de recurso nativo da plataforma. Cada provedor de destino que sintetiza um Workload mapeia a forma para a sua própria forma nativa:

formKubernetes (helm)Compose
statelessDeploymentservice (sem volume persistente)
statefulStatefulSetservice + volume nomeado
daemonDaemonSetinterrompe o build
scheduledCronJobinterrompe o build
taskJobinterrompe o build

Os provedores terraform e cloudformation renderizam Recipes com origem e Recipes somente de artefatos e não sintetizam nenhum Workload: uma Recipe que declara workload: vinculada a qualquer um dos dois interrompe o build, nomeando os tipos de entrada que o provedor suporta.

Quando um provedor de destino não tem um mapeamento limpo para uma forma, o build é interrompido de forma explícita em vez de degradar a carga de trabalho para uma forma que deturpa a intenção — escolher uma forma que uma fronteira de destino não consegue expressar é um erro em tempo de build, não um rebaixamento silencioso. O provedor compose interrompe o build em daemon, scheduled e task. O provedor helm emite um CronJob para scheduled (veja schedule abaixo) e só interrompe o build quando o agendamento está ausente ou malformado.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule é o agendamento cron de uma carga de trabalho form: scheduled — o campo complementar que dá à forma recorrente a sua recorrência. É uma única string em um único formato canônico:

  • uma expressão crontab padrão 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 a cada quinze minutos), ou
  • uma das macros @hourly, @daily, @weekly, @monthly, @yearly.

schedule é obrigatório quando form: scheduled e só tem sentido nesse caso. Uma carga de trabalho form: scheduled sem agendamento, um agendamento que não é nem uma expressão de 5 campos nem uma macro reconhecida (uma expressão de 6 campos prefixada por 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 build que indica a correção. O provedor helm repassa o valor literalmente para o spec.schedule do CronJob emitido.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
report:
image: "reporter:1.0"
command: ["/report"]

suspend

suspend suspende o agendamento recorrente de uma carga de trabalho form: scheduled. É um booleano e o padrão é false. Com suspend: true, o recurso agendado continua sendo renderizado com o seu schedule no lugar, mas nenhuma execução começa a partir desse agendamento até que ele seja retomado, e uma execução ainda pode ser iniciada manualmente a partir do recurso. Essa é a forma para uma tarefa que só deve ser executada quando alguém a solicitar.

O provedor 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 volta a ser false. suspend: false é renderizado exatamente como um suspend omitido, de modo que o campo não altera nenhuma saída até ser definido. O provedor compose não tem forma agendada e interrompe o build em qualquer carga de trabalho form: scheduled, suspensa ou não.

suspend: true em qualquer outra forma é uma interrupção em tempo de build que indica a correção: nenhuma outra forma tem um agendamento para ele suspender.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
report:
image: "reporter:1.0"
command: ["/report"]

replicas

Um único inteiro para a contagem de réplicas da carga de trabalho. O padrão é 1 quando omitido. Use uma expressão de template para definir as réplicas a partir do dimensionamento declarado pelo Ops:

replicas: {{ optional .infra `replicas` 1 }}

containers versus initContainers

containers é um mapa ordenado indexado pelo nome do contêiner. O contêiner 0 (a primeira chave do mapa) importa para a ordem da especificação do pod na saída do Kubernetes e para a semântica do contêiner padrão. initContainers é uma lista ordenada de entradas de contêineres de inicialização, cada uma com name, image e a mesma forma de autoria de variáveis, secrets e montagens de volume dos contêineres principais.

name é opcional em uma entrada de initContainers. Uma entrada que o omite recebe o nome init-<index>, em que o índice é a posição da entrada na lista, contando a partir de 0. Como o nome identifica o contêiner na saída renderizada e em qualquer diagnóstico que o mencione, uma entrada à qual valha a pena se referir merece um nome explícito.

A preservação da ordem do autor é um contrato fundamental do modelo de Workload — o compilador emite containers, volumes, services, as ports dos contêineres, as variables dos contêineres e os attachments dos contêineres, cada um na ordem em que o autor da Recipe os declarou, a cada build. Os autores de Recipe podem confiar na forma ordenada: quando o que acontece em tempo de execução depende da ordem (inicialização de sidecars, encadeamento $(VAR) em variáveis de ambiente, volumeMounts que referenciam volumes declarados anteriormente), a ordem de autoria É a ordem em tempo de execução dentro de cada uma dessas coleções. O ambiente de um contêiner combina duas delas e, entre as duas, os provedores que sintetizam escrevem primeiro as entradas lidas de vinculações (attachments entregues as: env) e depois as variables simples, cada tipo na ordem escrita — de modo que, em um destino Kubernetes, uma variável pode referenciar, como $(NAME), qualquer variável lida de uma vinculação do seu contêiner e qualquer variável declarada antes dela (veja a ordem do ambiente do provedor helm). Um contêiner que dá um mesmo nome tanto como entrada de variables quanto como entrada de attachments entregue as: env interrompe o build, porque só essa ordem decidiria qual dos dois valores o processo vê (veja A container gives one environment variable two values (Um contêiner dá dois valores a uma mesma variável de ambiente)).

A autoria dos campos de contêiner segue estas convenções:

  • image normalmente é uma expressão de template que referencia .values.image (a imagem selecionada pelo desenvolvedor) com substituições .infra.* opcionais para prefixar o registry de acordo com o ambiente.
  • variables é um mapa simples string → string para variáveis de ambiente. O mapa combina duas fontes de dados distintas por meio de expressões de template Go: literais do pilar do desenvolvedor (entradas cujas expressões de template leem .values / .infra / .locals — payload originado nos pilares do Component) e dados do pipe entre componentes (entradas cujas expressões de template leem .context.inject.env.<KEY> — payload originado no provides: de outro componente e roteado pelo pipe da topologia). As duas fontes fluem para o mesmo mapa variables; os autores escolhem uma por entrada conforme o valor seja local do componente ou derivado de outro componente. Padrões comuns: LOG_LEVEL: "{{ .values.log_level }}" é do pilar do desenvolvedor (local do componente); DB_HOST: "{{ .context.inject.env.DB_HOST }}" é do pipe entre componentes (o valor se origina no provides.host de um componente de destino, roteado pela declaração uses[].inject.env.DB_HOST do chamador). Ambas as formas são compiladas em uma única lista env: do Kubernetes no Deployment renderizado; a semântica de dupla origem existe apenas no momento da autoria.
  • attachments referencia slots declarados no featuresSchema do Component ou, ao nomear uma conexão, um slot que o socket dessa conexão declara (veja a seção de integração abaixo).
  • ports é um mapa de portas nomeadas (web: 8080, admin: 9901); os nomes de porta correspondem aos nomes de porta no escopo do contêiner e são referenciados por services.<service>.ports.<portname>. Uma porta que usa um transporte diferente do padrão do destino é escrita, em vez disso, na forma expandida — veja Protocolos de transporte das portas abaixo.
  • volumeMounts referencia pelo nome volumes declarados em outro ponto da seção volumes: do Workload.
  • resources declara as requests e os limits do contêiner — as quantidades de cpu e memory e, opcionalmente, chaves de recursos estendidos para GPUs e outros dispositivos (veja Cargas de trabalho de GPU e de dispositivos abaixo).
  • health usa a forma de intenção (http: /path, tcp: <port>, exec: [cmd, ...]) — veja a seção de health probes abaixo.

volumes

Cada volume é de exatamente um tipo: ephemeral, configmap, secret, persistent ou persistentTemplate. Os tipos são mutuamente exclusivos dentro de uma ú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 na tradução com forma de StatefulSet; na tradução para compose, ele é degradado para um único volume nomeado compartilhado, com um aviso relatado junto com o build. O próprio arquivo gerado não traz nenhuma nota da degradação — ele é idêntico byte a byte ao que seria sem o aviso.

Tradução por provedor. Cada provedor traduz as cinco variantes de volume para a sua forma nativa:

VarianteHelm / helm-chart (K8s)ComposeNotas sobre perdas
ephemeralemptyDir: { sizeLimit }entrada tmpfs: no nível do service que nomeia o caminho de montagem (em memória)O tmpfs do Compose é baseado em RAM; o emptyDir do helm é baseado por padrão no disco do nó — uma divergência semântica no meio de armazenamento subjacente. sizeLimit não chega a nenhuma parte da saída do compose: a entrada emitida é apenas o caminho de montagem. Um sizeLimit escrito pelo autor gera um aviso unsupported-field que o nomeia, relatado junto com o build em vez de escrito no arquivo gerado.
configmapReferência a volume ConfigMap (consome um recurso ConfigMap emitido pelos artifacts: da Recipe ou por uma Feature)Referência configs: no nível do service que nomeia o configmap, montado no caminho da montagem do volume; a entrada configs: de nível superior correspondente vem dos artifacts: da RecipeAmbos os destinos referenciam o configmap pelo nome e nenhum lê o seu conteúdo, então 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 do compose fica fixada no conteúdo que o build emitiu. Uma referência que nenhuma entrada de nível superior resolve interrompe o build em vez de emitir uma montagem que ficaria pendente em tempo de execução.
secretReferência a volume Secret (consome o Secret que uma vinculação de credencial nomeia — um que a sua FeatureRecipe emite, ou um que já existe)env_file: para secrets com forma de variáveis de ambiente, ou um arquivo de secret montado via bind para secrets com forma de caminhoO Compose não tem uma semântica de primeira classe para Secrets do Kubernetes. Um secret com forma de caminho deliberadamente não segue a via configs: da variante configmap: uma entrada de config inline escreveria o valor do secret em texto puro no arquivo compose emitido, e o compilador nunca resolve um secret em texto puro. A origem do bind é um caminho que o operador torna acessível no host do compose, fora de qualquer ciclo de vida de CRD de busca em vault.
persistentRecurso PVC + volume.persistentVolumeClaimVolume nomeadoOs volumes nomeados do Compose são uma abstração plana do lado do host; o PVC do helm suporta a declaração de storage class, modo de acesso e capacidade, que o compose ignora.
persistentTemplateStatefulSet.volumeClaimTemplates (PVC por réplica; complemento de form: stateful)Volume nomeado (degradado — um único volume compartilhado entre as réplicas, com um aviso relatado)O Compose não consegue expressar templates por réplica. Quando persistentTemplate é traduzido para compose, um único volume nomeado é emitido e a fidelidade reduzida é relatada como aviso junto com o build em vez de escrita no arquivo gerado. Workloads que dependem do isolamento de volumes por réplica não devem ter como destino fronteiras somente compose.

A forma do controlador é escolhida pelo form da carga de trabalho, não pelos seus volumes. Um StatefulSet é emitido quando form: stateful; um volume persistentTemplate é um complemento dessa forma — ele declara armazenamento por réplica em uma carga de trabalho que já tem a identidade por réplica que um StatefulSet fornece. Declarar um volume persistentTemplate em qualquer outra forma (ou no stateless padrão) é um erro em tempo de build que indica a correção: declare form: stateful. O inverso é permitido — uma carga de trabalho form: stateful não precisa declarar um volume persistentTemplate. Os autores que querem a semântica de StatefulSet definem form: stateful diretamente.

Uma carga de trabalho form: stateful no provedor helm exige um Service de governança headless: declare exatamente um service com type: Headless no mesmo Workload. O provedor liga o serviceName do StatefulSet a esse Service headless (ele fornece as identidades de rede estáveis por pod de que um StatefulSet precisa). O build é interrompido se nenhum service headless for declarado — um StatefulSet não teria então nenhum Service de governança para nomear — ou se mais de um for declarado, deixando ambíguo o Service de governança. Uma carga de trabalho StatefulSet ainda pode declarar services adicionais não headless (por exemplo, um service ClusterIP para acesso de clientes) ao lado do único service de governança headless.

Quantidades de recursos

Esses valores do Workload são quantidades — valores escritos na notação que o Kubernetes usa para recursos: os valores resources.requests e resources.limits de um contêiner (ou de um contêiner de inicialização) para cpu, para memory e para toda chave de recurso estendido, e ephemeral.sizeLimit, persistent.size e persistentTemplate.size de um volume. O esquema do Workload tipa cada um como string e não restringe a sua forma. O provedor que sintetiza o Workload para um destino verifica cada quantidade que emite, e verifica o Workload tal como os templates da Recipe o avaliaram, de modo que um valor que chegou por infra, por um parâmetro da Release ou por qualquer outra entrada de template é julgado pela string em que foi renderizado.

Uma quantidade é, sem nada antes ou depois:

  • um sinal opcional, + ou -;
  • um número com pelo menos um dígito — 2, 0.5, .5 ou 1.;
  • no máximo um entre um expoente — e ou E, um sinal opcional e depois dígitos, como em 1e3 ou 5E-2 — e um sufixo de unidade: um sufixo decimal n, u, m, k, M, G, T, P ou E (de 10⁻⁹ até 10¹⁸, em passos de mil), ou um sufixo binário Ki, Mi, Gi, Ti, Pi ou Ei (de 1024 até 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 após o número é o sufixo decimal para 10¹⁸ (12E); seguido de dígitos, ele inicia um expoente (1E3).

Essa é a forma que o próprio parser 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 para trás quando o valor que ele interpola está vazio: "{{ .infra.cpu }}m" com um cpu vazio é renderizado como m. Recusá-la transforma uma entrada vazia em uma interrupção que nomeia o campo, em vez de uma solicitação de tamanho zero que nada relata.

O que cada destino faz com uma quantidade:

  • helm emite cada quantidade literalmente, depois de verificar cada uma em relação à forma acima. Um valor fora dela interrompe o build com um erro que nomeia 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. Veja Helm Provider → Modo Workload (sintetizado).
  • compose converte cpu e memory para as suas próprias unidades a partir do valor analisado: cpus se torna uma contagem decimal de núcleos (500m → 0.5) e memory uma contagem exata de bytes (1.5Gi → 1610612736). Um valor que não é uma quantidade interrompe o build, assim como uma quantidade que o compose não consegue representar exatamente — um valor negativo, um valor de memória que não é um número inteiro de bytes (1500m) ou um valor de cpu mais fino que nove casas decimais de um núcleo — e o erro diz qual dos dois casos encontrou. Uma contagem nvidia.com/gpu é lida da mesma forma e se torna uma contagem de dispositivos, então uma que não seja um número inteiro de dispositivos também interrompe o build. O compose não emite nenhum outro recurso estendido nem nenhum tamanho de volume, então não verifica nenhum dos dois: qualquer outra chave de recurso estendido e um ephemeral.sizeLimit são descartados com um aviso, e um tamanho persistente não molda nada na sua saída. Veja Compose Provider → Recursos de contêiner.

A verificação julga apenas a forma. Se um cluster consegue agendar o valor, ou se o valor é adequado ao seu dispositivo, fica fora dela.

services

Um mapa ordenado de exposições de serviço. Cada serviço declara seu tipo (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — até onde suas portas chegam — e um mapa de portas nomeadas. Os nomes das portas devem corresponder aos nomes das portas de contêiner declarados em outra parte do Workload:

services:
http:
type: ClusterIP
ports:
web: 8080 # must exist in containers.<name>.ports

Vários serviços em um único Workload são comuns para expor separadamente o tráfego interno e o externo (ClusterIP interno para consumidores dentro do cluster, LoadBalancer para o tráfego externo, ClusterIP para o scraping do Prometheus).

Até onde chegam as portas de um serviço. O type determina isso, e cada destino o renderiza em seus próprios termos:

typeAlcancehelmcompose
ClusterIPos pares da carga de trabalho, na própria rede do destinoum Service do tipo ClusterIPnão publica nada; os pares alcançam a porta na rede do compose
Headlesso mesmo, sem endereço de clusterum Service do tipo ClusterIP com clusterIP: Nonenão publica nada
NodePortalém da própria rede do destinoum Service do tipo NodePortcada porta publicada em todas as interfaces do host, como <service port>:<container port>
LoadBalanceralém da própria rede do destinoum Service do tipo LoadBalancero mesmo que NodePort
Loopbackapenas o próprio endereço de loopback do hostinterrompe o build, nomeando o serviçocada 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 contêiner que ela nomeia são dois números, assim como port e targetPort de um Service do Kubernetes: o helm escreve o número da entrada como o port do Service e aponta para a porta de contêiner pelo nome, e o compose publica o número da entrada no host sobre o número da porta de contêiner. Quando os dois números são iguais, o compose escreve esse número dos dois lados.

Loopback é para uma porta que algo na mesma máquina alcança — um navegador ou um agente executado no host — e que mais nada deveria alcançar. No compose, o binding é apenas o endereço de loopback IPv4: o endereço de loopback IPv6 ::1 não é vinculado, então enderece a porta como 127.0.0.1 em vez de por 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 nomeiam a mesma porta, vence 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 nomeia, qualquer que seja a declarada primeiro.

No helm, uma entrada Loopback interrompe o build em vez de ser renderizada como algo que ela não é. Um Service do Kubernetes não tem nenhum tipo que se vincule ao endereço de loopback de um host — em quais endereços de nó um Service NodePort escuta é uma configuração do cluster inteiro, não de um único Service —, então 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 nomeia o nó e o serviço; consulte A service type the helm provider cannot render (Um tipo de serviço que o provedor helm não consegue renderizar).

Convenção de nomes sintetizados. Quando o provedor helm sintetiza os serviços de um Workload, o metadata.name de cada Service é derivado de forma determinística do nome que o próprio controlador da carga de trabalho carrega 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 do Kubernetes admite — o mesmo nome com o qual um chart é renderizado, legível nos templates de uma Recipe como {{ .context.rendered_name }} —, portanto é igual ao instance_id sempre que a identidade não contém sublinhado nem letra maiúscula. Um Workload que declara 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 arquivo de saída segue a mesma convenção: <release name>-<service-key>-service.yaml. Uma Recipe que publica o endereço de um Service assim o constrói a partir de {{ .context.rendered_name }}, nunca de {{ .context.instance_id }}, que não nomeia nenhum Service sempre que os dois diferem — consulte ../templates/rendered-resource-names.md.

Um Workload que a FeatureRecipe de uma vinculação de Feature sintetiza recebe o nome da identidade composta da própria vinculação em vez de um nome de release: o valor que seus recursos carregam no label aggrega.ai/component-id, composto a partir do componente hospedeiro e da chave escrita sob features:, após o cfr-- inicial. Um nome de release derivado ali seria o do hospedeiro, e daria aos recursos da vinculação o nome dos recursos do próprio hospedeiro. Assim, uma FeatureRecipe cujo Workload declara services.scrape, para uma vinculação 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 carrega: nos templates de uma vinculação, {{ .context.rendered_name }} e {{ .context.instance_id }} nomeiam ambos o hospedeiro (front-door) e {{ .attachment_name }} é apenas a chave (stats), de modo que {{ .context.rendered_name }}-scrape nomeia o próprio Service scrape do hospedeiro, quando o hospedeiro declara um, e nunca o da vinculação — consulte ../templates/rendered-resource-names.md. O arquivo de saída fica atrás do prefixo que todo arquivo emitido por uma vinculação carrega — o nome do hospedeiro e o da vinculação, cada um seguido de -- —, de modo 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, 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 sempre chegam a dois nomes de release distintos, a identidade de uma vinculação carrega tanto o hospedeiro quanto a chave, e nenhum nome de componente pode começar com cfr-- (o build é interrompido em um que comece — consulte Component identity cannot be stamped on what it emits (A identidade do Component não pode ser carimbada no que ele emite)), de modo que dois Workloads que declaram 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 vinculação longa demais para o destino: ela é encurtada em torno de um digest do todo, e duas identidades encurtadas podem, em princípio, coincidir — consulte Labels de proveniência emitidos na saída renderizada. Segundo, um Workload não pode declarar a mesma chave de serviço duas vezes — um mapa services: que nomeia uma chave duas vezes é recusado quando o YAML do Workload é analisado, e o build é interrompido nomeando a chave e sua linha.

O risco de colisão que permanece está no limite de comprimento de nomes do K8s: os nomes de Service do Kubernetes sã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 Aggrega não impõe o limite; o build emite o Service, e o Kubernetes o rejeita quando ele é aplicado. 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 de 63 caracteres. O mesmo vale para o Workload de uma vinculação: uma identidade composta longa demais para o destino é encurtada, mas a chave de serviço anexada a ela não, de modo que um Service de vinculação com uma chave longa ainda pode exceder 63 caracteres e passar pelo build sem interrupção.

Nota específica do Provider (compose). O provedor compose deriva depends_on automaticamente das arestas uses da IR. Essas entradas são emitidas sem condição — carregam a semântica service_started independentemente de o destino declarar um healthcheck —, de modo 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 à saúde do destino não está implementado. A forma longa é emitida onde uma entrada de fato carrega uma condição, que é como se expressa uma espera por um contêiner de inicialização; consulte providers/compose.md.

Protocolos de transporte das portas

Uma porta de contêiner é escrita em uma de duas formas equivalentes. O número sozinho é a forma curta e não declara transporte, então o destino aplica o seu próprio padrão — TCP em todo destino que tenha um:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080

A forma expandida carrega o número e o transporte juntos, e é o que uma porta precisa quando transporta algo diferente desse padrão:

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: SCTP

As duas formas podem ser misturadas livremente dentro de um mesmo mapa ports, e uma porta sem transporte a declarar permanece na forma curta.

O transporte é declarado uma única vez, na porta de contêiner. Uma entrada services.<service>.ports nomeia uma porta de contêiner e leva consigo o transporte dessa porta, de modo que uma exposição de serviço não pode divergir da porta que o contêiner abriu. Não existe chave protocol em uma porta de serviço, e escrever uma é rejeitado.

Por que o campo existe. Os destinos de implantação tratam um transporte não especificado como o de fluxo. Um componente que precisa de uma porta de datagramas — mídia em tempo real, telefonia, resolução de nomes, redes privadas, um servidor de jogos — poderia, caso contrário, declarar apenas o número, e a stack seria implantada passando por todos os controles enquanto nenhum cliente se conecta, porque o tráfego é de datagramas e a porta aberta não é. Declarar o transporte é o que torna isso expressável.

O compilador não interpreta o valor. Ele não extrai nenhum transporte do nome de uma porta e não verifica o transporte declarado em relação ao que o processo por trás da porta realmente fala: o valor é um dado que você declara e que o motor do destino emite. Uma porta chamada dns sem chave protocol é uma porta TCP, e uma porta chamada web que declara protocol: UDP é uma porta UDP.

Comportamento por destino.

DestinoUma porta sem transporte declaradoUm transporte declarado
helmcontainerPort e a porta do Service não carregam chave protocolemitido literalmente como protocol: na porta de contêiner e em toda porta de Service que a nomeia
composepublicada como <host>:<container>, sem alteraçãopublicada como <host>:<container>/tcp ou /udp; SCTP não tem grafia no compose e interrompe o build em vez de publicar uma porta que carregaria um transporte diferente

Uma porta de contêiner que nenhum serviço publica não chega a nenhuma parte de um arquivo compose — esse é o comportamento habitual do compose para portas de contêiner —, então um transporte declarado em tal porta não tem onde ser escrito e não causa interrupção.

Sondas de saúde — forma de intenção

Cada contêiner declara suas sondas sob sua própria chave health: (containers.<name>.health), em uma forma de intenção abstrata; o Workload não tem health de nível superior. Cada provedor traduz a intenção para 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: 10

Três formas de intenção (http:, tcp:, exec:) são mutuamente exclusivas dentro de uma única declaração de sonda. A resolução de porta para http: sem porta explícita usa o primeiro nome de porta, em ordem alfabética, que o contêiner declara sob containers.<name>.ports — a mesma regra nos dois destinos, de modo que uma sonda lê a mesma porta, seja qual for o destino que a renderiza. Um contêiner que não declara nenhuma porta nomeada não pode carregar uma sonda HTTP: o build é interrompido com um erro de tradução que nomeia a sonda em questão.

Tradução por provedor. Cada provedor traduz a intenção abstrata de sonda para sua forma nativa no momento da síntese:

IntençãoHelm (K8s)ComposeNotas sobre perdas
http: /pathhttpGet.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 curl estar presente na imagem do contêiner.
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 nc estar presente na imagem do contêiner.
exec: [cmd, ...]exec.command: [cmd, ...]CMD [cmd, ...]Mapeamento um para um; ambos os provedores carregam a lista de comandos literalmente.

Os wrappers CMD-SHELL do Compose aproximam sondas HTTP e TCP por meio de predicados avaliáveis pelo shell. O que falta ao compose é a forma de sonda nativa, não os campos de temporização: periodSeconds, timeoutSeconds, failureThreshold e initialDelaySeconds escritos pelo autor são levados para o healthcheck como interval, timeout, retries e start_period — a seção “Sondas” de providers/compose.md traz o mapeamento campo a campo. A forma nativa exec: não precisa de wrapper algum e é traduzida um para um nos dois destinos.

Uma sonda encapsulada é traduzida silenciosamente: nada no docker-compose.yaml emitido a marca, e nenhum diagnóstico relata o encapsulamento. O que o build relata nesse caminho é um slot de sonda que não chega a nenhuma saída — um serviço do compose carrega um único healthcheck, então, quando um Workload declara mais de um entre ready:, live: e startup:, apenas o slot preferido é traduzido (live antes de ready antes de startup) e um aviso unsupported-field nomeia o slot traduzido e os slots descartados.

Nota específica do Provider (compose). Escrever um bloco health: em um Workload destinado ao compose não condiciona a ordem de depends_on à saúde: as entradas depends_on do provedor compose derivadas de arestas uses: sempre usam a semântica service_started, independentemente de o Workload de destino declarar sondas de saúde. Condicionar essas entradas à saúde do destino não está implementado — a forma longa que carregaria tal condição é ela própria emitida, para esperas por contêineres de inicialização, então o que falta é a escolha de condicionar uma aresta à saúde, e não a forma de expressá-lo. Consulte providers/compose.md para as regras de inferência completas.

Campos de repasse no formato K8s — scheduling, serviceAccount, podSecurityContext

O schema de Workload aceita três campos opcionais de nível superior que existem principalmente para passar primitivas nativas do Kubernetes pelo provedor helm preservando a forma estrutural do Aggrega. O provedor compose traduz o subconjunto que tem um análogo no Compose e ignora o resto com um aviso emitido. O Aggrega valida a forma externa, mas não fiscaliza o conteúdo interno (consulte Superfície de validação abaixo) — os valores internos 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 — em um único bloco organizado por finalidade. Cada subcampo tem exatamente a forma do campo correspondente do pod spec do Kubernetes:

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
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: ScheduleAnyway
containers:
app: { image: "..." }

Tradução pelo Provider. O provedor helm passa cada subcampo literalmente para o pod spec renderizado. O provedor compose não traduz nenhum dos quatro: omite o bloco scheduling inteiro, e um aviso o nomeia.

serviceAccount

serviceAccount é uma string simples que carrega o nome da ServiceAccount sob a qual a carga de trabalho é executada:

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .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 provedor helm nomeia os recursos da própria carga de trabalho, de modo que é um nome que o cluster aceita, seja qual for o nome do componente. O campo referencia uma ServiceAccount existente; não cria uma. Os recursos RBAC que a acompanham (o próprio objeto ServiceAccount, além de Role / RoleBinding / ClusterRole / ClusterRoleBinding) devem ser entregues por um de dois canais:

  • artifacts: da Recipe — quando o RBAC é intrínseco a esta Recipe (a Recipe sabe que precisa de um Role específico para uma tarefa específica).
  • Features com geração de recursos — quando o RBAC é transversal (uma FeatureRecipe de Workload-Identity que vincula ServiceAccounts associadas ao IAM a cada componente com um determinado label).

Definir serviceAccount: sem garantir que a ServiceAccount nomeada exista resulta em um erro do K8s em tempo de execução, no momento do apply, e não em um erro em tempo de build — a validação do schema da carga de trabalho não verifica a existência da ServiceAccount (não há acesso ao estado do cluster em tempo de compilação, conforme o invariante de pureza AOT).

O provedor compose ignora serviceAccount: com um aviso; o Compose não tem um conceito equivalente de vinculação de identidade.

podSecurityContext

podSecurityContext carrega primitivas de segurança no nível do pod — UID, GID, fsGroup, supplementalGroups — que se aplicam a todos os contêineres do pod:

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
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 contêiner; fsGroup define o grupo proprietário dos volumes montados no pod; supplementalGroups adiciona GIDs extras ao grupo de processos de cada contêiner.

Tradução pelo Provider. O provedor helm passa o bloco literalmente para o pod spec renderizado. O provedor compose não tem equivalente para fsGroup nem supplementalGroups e omite cada um com um aviso; runAsUser/runAsGroup são traduzidos para a forma do Compose user: 1000:3000 em todo serviço que o Workload produz, sidecars e contêineres de inicialização incluídos, e um runAsGroup sem um runAsUser ao lado é omitido com um aviso. Cada contêiner e contêiner de inicialização também carrega seu próprio securityContext — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation e capabilities.add / capabilities.drop. O provedor helm o emite no contêiner; o provedor compose emite readOnlyRootFilesystem como read_only, capabilities.add / capabilities.drop como cap_add / cap_drop, e runAsUser / runAsGroup como o próprio user do contêiner, que toma o lugar do do pod; ele omite runAsNonRoot, allowPrivilegeEscalation e um runAsGroup escrito sem um runAsUser, com um aviso cada, e também avisa quando o próprio runAsUser de um contêiner deixa de fora o runAsGroup do pod. providers/compose.md traz o mapeamento campo a campo.

Cargas de trabalho com GPU e dispositivos

Uma carga de trabalho que precisa de hardware especializado — uma GPU ou outro dispositivo fornecido por um fabricante — expressa duas preocupações independentes: o runtime no nível do pod que o nó habilitado para o dispositivo expõe (runtimeClassName) e a quantidade do dispositivo por contêiner que a carga de trabalho reivindica (uma chave de recurso estendido sob resources de um contêiner). Uma carga de trabalho típica com GPU declara ambos juntos, mas cada um se sustenta sozinho e qualquer um pode aparecer sem o outro.

Ambos os campos descrevem computação — o pod e o contêiner que é executado no dispositivo —, então pertencem a uma carga de trabalho que executa contêineres. Uma carga de trabalho que carrega apenas um endpoint externo e não declara contêineres próprios não tem pod nem contêiner aos quais vinculá-los: definir runtimeClassName em uma carga de trabalho assim, só de endpoint, interrompe o build, nomeando runtimeClassName e a Recipe cujo Workload o declarou, e sem contêineres não há onde colocar uma solicitação de recurso de dispositivo.

runtimeClassName

runtimeClassName é uma única string que nomeia a RuntimeClass sob a qual o pod é executado — o runtime de contêineres que um nó habilitado para o dispositivo expõe, por exemplo um runtime de GPU chamado nvidia. É um seletor no nível do pod: aplica-se a todos os contêineres da carga de trabalho. O compilador repassa o nome literalmente como um ponteiro determinístico; o cluster o resolve, no momento do agendamento, para uma RuntimeClass que seu administrador configurou. O Aggrega não verifica se existe uma RuntimeClass correspondente — ele não tem acesso ao estado do cluster em tempo de compilação —, então um nome sem RuntimeClass configurada aparece como erro de agendamento no momento do apply, e não como erro em tempo de build.

Chaves de recursos estendidos

resources.requests e resources.limits de um contêiner carregam as quantidades comuns cpu e memory e, ao lado delas, chaves de recursos estendidos: quantidades de dispositivos com escopo de fabricante ou de domínio, identificadas 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 forma de string ("1", "2") que o compilador repassa literalmente, e o provedor helm verifica sua forma antes de emiti-la (consulte Quantidades de recursos); o device plugin do cluster resolve e aloca o dispositivo no momento do agendamento.

Exemplo completo — uma carga de trabalho de inferência com GPU

apiVersion: aggrega.ai/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

A carga de trabalho seleciona o runtime nvidia para seu pod e reivindica uma GPU para o contêiner inference. A quantidade de GPU aparece tanto em requests quanto em limits: um dispositivo não admite sobrealocação, então sua solicitação e seu limite são definidos com o mesmo valor.

Tradução pelo Provider. Estes são conceitos nativos do Kubernetes. O provedor helm emite runtimeClassName no pod spec renderizado e cada chave de recurso estendido literalmente sob resources.requests / resources.limits do contêiner, de modo que chegam ao cluster pela saída do Kubernetes. O provedor compose reserva uma contagem de nvidia.com/gpu como o mesmo número de GPUs NVIDIA no serviço do contêiner (consulte Compose Provider → Recursos do contêiner); um único host não tem o conceito de runtime class nem um análogo para qualquer outra chave de recurso estendido, então uma carga de trabalho que declara runtimeClassName ou outra chave é renderizada em um destino compose sem ela.

Execução na rede do nó

Por padrão, uma carga de trabalho é executada em um namespace de rede próprio: seus contêineres veem apenas as próprias interfaces, e o tráfego chega até eles pela tradução de endereços do destino. hostNetwork: true pede o outro arranjo — a carga de trabalho é executada no próprio namespace de rede do nó, de modo que ela vê as interfaces do nó e as portas que seus contêineres abrem ficam acessíveis nos próprios endereços do nó, sem nenhuma tradução no meio.

É disso que toda uma classe de software precisa. Mídia em tempo real, telefonia, redes privadas virtuais e tráfego semelhante levam o endereço do par dentro da carga útil, de modo que um endereço reescrito em trânsito chega descrevendo um lugar que o par não consegue alcançar; executar nos endereços do nó é o que mantém os dois consistentes.

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

O que ele declara e o que não declara

hostNetwork escolhe um namespace de rede, e isso é tudo.

  • Ele não declara portas. As portas que uma carga de trabalho abre continuam sendo declaradas em containers.<name>.ports, exatamente como sem ele, e continuam significando a mesma coisa. Declarar hostNetwork não adiciona uma porta nem elimina a necessidade de declarar uma.
  • Ele não declara nenhum número de portas. Uma aplicação que quer muitas portas contíguas — um servidor de mídia que dimensiona um intervalo de acordo com o número de processadores de uma máquina, por exemplo — configura esse intervalo no próprio corpo de configuração, a partir de valores que seu operador fornece, da mesma forma que configura qualquer outra coisa que lê na inicialização. Essa é uma configuração da aplicação, não da carga de trabalho, e o contrato da carga de trabalho não é o lugar onde ela fica.
  • Nada é inferido. O compilador não lê nenhum significado no valor nem o deriva de qualquer outra coisa: nem do nome de uma porta, nem do tipo ou dos rótulos de um componente, nem de quantas portas estão declaradas. Uma carga de trabalho é executada na rede do nó quando, e somente quando, ela diz isso.

Como descreve recursos de computação, hostNetwork pertence a uma carga de trabalho que executa contêineres. Uma carga de trabalho que contém apenas um endpoint externo não declara contêineres, portanto não tem nenhum namespace de rede a escolher: declarar hostNetwork em uma carga de trabalho só de endpoint interrompe a compilação, citando hostNetwork e a Recipe cujo Workload o declarou.

Tradução pelo Provider

O provedor helm emite hostNetwork: true na especificação de pod renderizada, que é como o Kubernetes expressa a mesma escolha. A declaração chega à especificação de pod e a nada mais — os Services emitidos são idênticos com e sem ela.

O provedor compose emite network_mode: host no próprio serviço da carga de trabalho. Uma consequência decorre da forma como o compose modela redes: um serviço nesse modo não é conectado à rede da fronteira, porque o compose trata a conexão a uma rede e a adoção do namespace do host como alternativas, e não como acréscimos. Por isso seus pares o alcançam 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.

Duas formas se combinam com ele nesse destino. Um contêiner sidecar segue o serviço principal para a rede do host sem declarar nada, porque assume o namespace do serviço principal ao nomeá-lo. Um contêiner de inicialização não: ele se torna um serviço pelo qual o serviço principal espera, portanto entra na rede da fronteira por conta própria em vez de adotar um namespace que tornaria essa espera circular. Uma carga de trabalho que declara tanto hostNetwork quanto initContainers executa, portanto, o próprio serviço na rede do nó enquanto seus serviços de inicialização permanecem na rede da fronteira — um arranjo mais restrito que o único namespace compartilhado que a forma de pod oferece, e que o provedor compose aponta em um aviso unsupported-field em vez de deixar para ser descoberto em tempo de execução.

Uma carga de trabalho que não declara hostNetwork não tem essa chave na saída: a chave fica ausente em vez de ser emitida como false.

Integração das vinculações 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 nomeia uma conexão, um slot que o socket dessa conexão declara (veja Entregar uma credencial que uma conexão carrega); ele não declara novos slots. Veja ../entities/component.md para a superfície de autoria de featuresSchema. from nomeia 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 baseado em secret (para as: file) —, e ambos apontam para o Secret pelo nome. O sintetizador resolve esse nome e a chave de dados a partir dos provides expostos do 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 — ele não deriva o nome de novo. É a mesma leitura de .features.<slot>.provides.<key> que uma Recipe source usa para um existingSecret: um único slot de credencial alimenta de forma idêntica um consumidor Recipe source e um consumidor Workload sintetizado (simetria source/workload).

Quatro regras de validação regem a integração:

  • Todo valor attachments.<KEY>.from deve corresponder a um nome de slot declarado no featuresSchema do Component — ou, em uma entrada que nomeia uma conexão, no socket dessa conexão. Um nome de slot desconhecido é um erro em tempo de carga.
  • O mecanismo de entrega as: (env ou file) deve constar na lista de permissões inject: do slot declarada pelo Component. Um Workload que declara as: file para um slot cuja entrada de featuresSchema especifica inject: [env] é um erro em tempo de carga.
  • Slots marcados com inject: [] (entrega em caixa-preta) no featuresSchema do Component não podem aparecer de forma alguma em blocos attachments: de um Workload. Esses slots são entregues pelo encanamento interno da Recipe (o parâmetro existingSecret de um chart do Helm, por exemplo), não pela exposição no Workload.
  • O slot referenciado deve ser referenciável — seu preenchimento deve publicar um localizador provides (name, key) para um recurso Secret, um que sua realização emite ou um que já existe. 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 para onde apontar; referenciá-lo a partir de uma entrada attachments: de um Workload é um erro em tempo de carga. Uma credencial entregue por inject chega ao contêiner pelo pipe de inject do slot (uma entrada variables que lê .context.inject.env.<KEY>), não por uma entrada attachments:.

Nota sobre o Provider. O Helm renderiza a referência secretKeyRef/volume de secret descrita acima. O provedor compose não tem uma primitiva nativa de ambiente a partir de secret; uma entrada de vinculação as: env em um Workload destinado ao compose é renderizada como uma entrada de ambiente com valor vazio e um aviso que nomeia a entrada (veja a página do provedor compose), enquanto a regra de referenciabilidade (agnóstica em relação às capacidades) continua valendo.

Exemplo:

# In the Component catalog entity
spec:
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 Workload
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected at load time: blackbox slot

Entregar uma credencial que uma conexão carrega

O socket de um Component pode declarar, em usesSchema.<socket>.featuresSchema, os slots que cada conexão ligada por ele preenche — assim, um componente que alcança vários destinos mantém uma credencial por conexão em vez de uma para todas. Uma vinculação desse tipo não está entre as .features próprias do componente; ela fica sob sua conexão, em .context.uses.<alias>.features.<slot>. Uma entrada do Workload a entrega nomeando a conexão ao lado do slot:

  • em uma entrada attachments de um contêiner, connection: <alias> ao lado de from: <slot>;
  • em uma entrada envFrom de um contêiner, connection: <alias> ao lado de secret: <slot> — connection só é aceito ao lado de secret.

As duas formas são aceitas em todo contêiner e em todo contêiner de inicialização. <alias> é o nome sob o qual a conexão está escrita no bloco uses do componente, no Aggregate ou na Release — a chave pela qual uma Recipe lê a conexão em .context.uses — e <slot> é um slot que o socket pelo qual essa conexão está ligada declara.

Antes que qualquer regra acima leia o Workload, cada entrada que nomeia uma conexão é reescrita para o nome que a vinculação que essa conexão carrega nesse slot assume no componente: o alias, um ponto e o slot (gpt.credential). Cada regra é então executada sobre a entrada reescrita exatamente como é executada sobre uma entrada que nomeia um dos slots próprios do Component: a lista de permissões inject: do slot do socket rege as:, um slot de socket que declara inject: [] não pode ser referenciado, a vinculação que o preenche deve ser referenciável, e o provedor resolve o nome do Secret e a chave de dados a partir dos provides resolvidos dessa vinculação — assim, a entrada de cada conexão referencia a credencial própria dessa conexão. Um slot de socket que declara sensitive: true é lido para a entrada exatamente como a declaração de um slot do Component. A entrada reescrita é o que o provedor recebe; a chave connection não chega até ele.

Três entradas são recusadas, cada uma citando o que nomeou:

  • uma entrada que nomeia uma conexão que o componente não traça — a recusa cita a conexão, o slot e as conexões que o componente traça;
  • uma entrada que nomeia um slot que o socket da conexão não declara — a recusa cita o slot, a conexão, o socket e os slots que ele declara;
  • uma entrada que escreve ela mesma o nome composto (from: gpt.credential). O slot de uma conexão é nomeado nomeando a conexão, de modo que o nome composto nunca é um segundo caminho para alcançá-lo.

Uma conexão que não carrega nenhuma vinculação no slot deixa a entrada sem nada a referenciar, e a regra de referenciabilidade a recusa. Um Workload que uma FeatureRecipe renderiza fica restrito aos slots que a Feature que ela implementa declara, os quais não alcançam nenhuma das conexões do componente hospedeiro; por isso, uma entrada ali que nomeia uma conexão é recusada por nomear uma que o componente não traça.

Exemplo:

# In the Component catalog entity
spec:
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: env

No helm, MODEL_KEY_GPT é renderizado como um secretKeyRef que nomeia o Secret que a credencial da conexão gpt publicou, e MODEL_KEY_NIM como o que a da conexão nim publicou. No compose, uma entrada as: env que nomeia uma conexão é emitida com valor vazio e o mesmo aviso de suporte parcial que recebe uma entrada que nomeia um dos slots próprios do Component.

Superfície de validação

Todo Workload é validado no momento do carregamento da Recipe, antes que qualquer renderização seja executada. A validação tem duas etapas:

  • Validação do esquema. O valor do Workload é unificado com o esquema de Workload aggrega.ai/v1beta1 embutido. Os erros trazem 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 todo tipo, enumeração, intervalo e disjunção declarados no esquema — incluindo o form de controlador de conjunto fechado (um de stateless, stateful, daemon, scheduled, task, reference), o type de serviço de conjunto fechado (um de ClusterIP, Headless, NodePort, LoadBalancer, Loopback), o intervalo inteiro de portas (1..65535), a disjunção de forma da sonda (exatamente um de http, tcp, exec) e a disjunção de variante de volume (exatamente um de ephemeral, configmap, secret, persistent, persistentTemplate).
  • Validação de referências cruzadas. As referências de vinculação do Workload são verificadas em relação ao featuresSchema do Component — e, para uma entrada que nomeia uma conexão, em relação aos slots que o socket dessa conexão declara — (pertencimento ao slot, lista de permissões de entrega as:, exclusão de caixa-preta) e em relação aos provides resolvidos de cada slot referenciado (referenciabilidade — o preenchimento deve publicar name/key). São verificações entre entidades que uma validação apenas de esquema não consegue realizar.

As duas etapas produzem a mesma forma de mensagem com o prefixo CATALOG_ERROR; as falhas interrompem a compilação antes que qualquer saída de renderização seja produzida. Os autores de Recipe recebem um retorno preciso que identifica o campo exato que falhou e a restrição que o rejeitou.

Os campos repassados com forma de K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, as listas items dentro de volumes ConfigMap e Secret, os hooks de ciclo de vida httpGet) são validados apenas estruturalmente — o esquema do Aggrega restringe sua presença e sua forma externa, mas a forma interna desses valores definidos pela API do K8s é responsabilidade do provedor (o provedor helm os entrega literalmente à especificação de pod do K8s; o provedor compose os rejeita ou os degrada conforme o caso). Um Workload que usa um valor affinity malformado passa na validação do Aggrega, e o erro aparece, em vez disso, durante a síntese pelo provedor.

Da mesma forma, as quantidades de recursos são strings para o esquema: nenhuma das duas etapas verifica sua forma. Quem faz isso é o provedor que sintetiza, sobre o Workload avaliado, e ele interrompe em um valor fora da forma de quantidade — veja Quantidades de recursos.

Recursos auxiliares ficam fora do Workload

O Workload descreve apenas a forma da carga de trabalho — contêineres, volumes, serviços, réplicas, agendamento, contexto de segurança, service account. Ele não tem campo additionalResources nem declarações inline de ConfigMap / Secret / CRD.

Os autores de Recipe emitem recursos auxiliares por dois canais fora do Workload:

  • artifacts: no nível da Recipe — para recursos intrínsecos a esta Recipe (um ConfigMap específico que o Workload da Recipe referencia, um registro pontual de CRD de que a Recipe precisa). O campo é um mapa de entradas nomeadas; cada entrada é escrita inline ou carregada por um $import: por entrada. Veja a seção sobre o mecanismo de artefatos em ../../architecture/16-recipe-input-composition.md para os três modos de autoria.
  • Features com geração de recursos — para preocupações transversais vinculadas por seletores da Release (uma Feature ServiceMonitor vinculada a todo componente com métricas expostas, uma Feature NetworkPolicy vinculada a toda carga de trabalho de produção). Veja ../entities/featurerecipe.md para a superfície de autoria da FeatureRecipe.

O Workload permanece focado na forma da carga de trabalho; os manifestos auxiliares transversais e os intrínsecos à Recipe têm seus próprios lugares de autoria.

Padrões comuns de Workload

O esquema de Workload é amplo — ele cobre servidores HTTP de contêiner único, padrões sidecar com vários contêineres, cadeias de contêineres de inicialização, jobs em lote e serviços com estado com volumes persistentes. Três padrões se repetem com frequência suficiente para que escrever o boilerplate do zero para cada Recipe seja um desperdício. Os blocos abaixo são modelos para copiar e colar que os autores de Recipe podem adaptar a componentes específicos.

Um padrão que várias Recipes compartilham pode ser publicado uma vez como entrada de uma WorkloadLibrary e importado com $import: <Library>#/workloads/<entry>; os modelos aqui são pontos de partida para adaptar, ou para publicar dessa forma.

Padrão 1 — Servidor com exposição de métricas

Uma aplicação web típica que atende o tráfego da aplicação em uma porta e expõe métricas coletadas pelo Prometheus em uma 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/v1beta1
kind: Workload
replicas: {{ 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: 5
services:
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 por meio de uma vinculação 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 coleta específicas do provedor.

Padrão 2 — Job em lote

Uma carga de trabalho que é executada até a conclusão em vez de atender tráfego indefinidamente. O padrão define form: task, omite totalmente services: — jobs em lote não expõem portas — e depende da forma de tarefa do provedor de destino (um Job do Kubernetes no provedor helm; o provedor compose não tem forma de tarefa e interrompe em form: task). O provedor helm fixa uma restartPolicy de pod válida para Jobs (Never, a menos que o contêiner declare OnFailure), já que um pod de Job não pode usar o padrão Always.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
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/config
volumes:
config:
configmap:
source: "{{ .context.instance_id }}-config"

O volume de configuração referencia um ConfigMap que se espera que a Recipe emita junto com o Workload via artifacts: (veja “Recursos auxiliares ficam fora do Workload” acima) — o próprio Workload declara apenas o lado do consumo. A identidade dá o nome a ele em um provedor que nomeia a carga de trabalho com base na identidade, como faz o compose; no helm, que nomeia os recursos da carga de trabalho com base no nome da release do helm, construa o nome do ConfigMap — aqui e no artefato — a partir de {{ .context.rendered_name }}, para que seja um nome que o cluster aceite, seja qual for o nome do componente.

Padrão 3 — Par com sidecar

Um pod de dois contêineres em que o contêiner principal cuida da lógica da aplicação e o sidecar cuida de uma preocupação transversal (terminação TLS, envio de logs, proxy de service mesh, guardrail de IA). A ordem de autoria em containers: é determinante — o provedor helm emite os contêineres na ordem declarada; a primeira chave (aqui, main) é o contêiner de destino padrão para kubectl logs e ferramentas semelhantes.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ 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 contêiner principal), roteando o tráfego externo pelo sidecar até o contêiner principal via localhost. Os dois contêineres compartilham o namespace de rede do pod, de modo que localhost:<port> alcança diretamente o contêiner par. Para sidecars que precisam de injeção de credenciais (o padrão canônico de guardrail de IA), a credencial normalmente fica no bloco attachments: do sidecar em vez de no do contêiner principal — mantendo a credencial restrita ao limite do processo do sidecar.

Escolha do padrão

Os três padrões correspondem a preocupações distintas de forma de entrega:

  • Servidor com métricas — serviços de longa duração que o cluster mantém ativos; várias exposições de Service para separar o tráfego.
  • Job em lote — execução limitada; nenhuma exposição de Service; depende de um ConfigMap emitido pela Recipe ou de estado externo para a entrada.
  • Par com sidecar — pod com vários contêineres e namespace de rede compartilhado; o Service do sidecar expõe a preocupação transversal.

Um quarto padrão — servidor com estado com volume persistente — define form: stateful e declara armazenamento por réplica via volumes.<name>.persistentTemplate; o provedor helm emite um StatefulSet para a forma com estado (veja 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 precisarem dele adaptam o Padrão 1 com as três declarações.

Referências cruzadas