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

WorkloadLibrary

Uma WorkloadLibrary é uma entidade de catálogo que contém fragmentos de template de Workload reutilizáveis. Recipes e FeatureRecipes que implantam a mesma forma de carga de trabalho — um servidor que expõe métricas, um job em lote, um par com sidecar — declaram essa forma uma única vez em uma biblioteca e a referenciam no momento do consumo por meio de uma diretiva workload: { $import: ... }. A entidade de biblioteca é de nível 3: opcional para catálogos que precisam reutilizar cargas de trabalho entre uma Recipe e outra. Catálogos cujas Recipes trazem cada uma sua própria forma de carga de trabalho distinta são distribuídos sem nenhuma WorkloadLibrary.

O papel da WorkloadLibrary

Arquitetos de plataforma escrevem WorkloadLibraries para centralizar o conteúdo de Workload que se repete nas Recipes e FeatureRecipes do catálogo. Uma biblioteca não é uma instrução de compilação implantável; ela é um namespace de definições. Os autores de Recipe e de FeatureRecipe referenciam entradas da biblioteca por uma diretiva $import:, escrita uma vez e consumida onde quer que a importação seja resolvida.

A separação entre “biblioteca” e “consumidor” é intencional. As Recipes codificam instruções de compilação (source, valuesMapping, artifacts). As FeatureRecipes codificam vinculações de comportamento. As WorkloadLibraries codificam apenas conteúdo de Workload — a forma da carga de trabalho que o provedor sintetiza em manifestos nativos do provedor. Manter os três papéis distintos permite que cada tipo de entidade evolua no próprio ritmo; os autores que não precisam de conteúdo de carga de trabalho compartilhado nunca encontram a entidade de biblioteca.

Envelope da entidade

Uma entidade WorkloadLibrary carrega o envelope de catálogo padrão. apiVersion: aggrega.ai/v1beta1 e kind: WorkloadLibrary marcam o tipo de entidade; metadata.name é um identificador em PascalCase; metadata.version segue versionamento semântico estrito. Ambos são obrigatórios. metadata.description, metadata.labels e metadata.annotations são opcionais — rótulos e anotações são metadados opacos declarados pelo autor, carregados para que aquilo que lê a biblioteca possa usá-los para correspondência, e o compilador não interpreta seus valores. O conteúdo da biblioteca fica em spec.workloads, um mapa obrigatório que deve declarar pelo menos uma entrada.

O envelope é fechado nos três níveis — a raiz do documento, metadata e spec rejeitam, cada um, chaves que o esquema não declara.

apiVersion: aggrega.ai/v1beta1
kind: WorkloadLibrary
metadata:
name: BaseWorkloads
version: 1.0.0
spec:
workloads:
SimpleServer: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}

Escrever entradas Workload

Cada entrada é um fragmento de template Go escrito como string YAML. A saída renderizada da entrada é um documento Workload completo — ele traz seus próprios apiVersion: aggrega.ai/v1beta1 e kind: Workload — porque o campo workload: de uma Recipe aceita um Workload completo, não um fragmento inserido em outro ao redor, e a importação substitui o campo inteiro. Uma entrada de MappingLibrary é completa da mesma forma: importar uma substitui todo o valuesMapping: da Recipe.

O corpo é opaco para o envelope da entidade. O compilador armazena a string literalmente no carregamento da WorkloadLibrary e não analisa o template ali; o analisador de templates é executado no momento do consumo, quando uma Recipe ou uma FeatureRecipe importa a entrada. Armazenar o fragmento literalmente preserva a fidelidade de autoria para a reemissão, e faz com que um erro de template apareça onde a entrada é consumida e seu contexto de pilares é conhecido, e não na biblioteca.

Como um documento Workload tem várias linhas, as entradas usam o escalar de estilo literal do YAML (|) para que quebras de linha e indentação sobrevivam à ida e volta:

spec:
workloads:
BatchJob: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]

O valor de uma entrada deve ser um escalar string. Escrever um mapa ou uma sequência onde deveria ficar o corpo é rejeitado — o corpo da entrada é texto de template, não YAML estruturado que o compilador percorre.

Dentro de uma entrada está disponível todo o vocabulário de composição dos templates Go: {{ define "name" }}...{{ end }} declara blocos reutilizáveis dentro de uma única biblioteca, {{ template "name" . }} os invoca, e pipelines e funções seguem o pacote padrão do Go text/template. O contexto de pilares que uma entrada pode ler — .values, .infra, .locals, .context, .features — é o mesmo contexto que qualquer template de Workload lê, e está documentado na página Workload, na seção sobre avaliação de templates.

O provedor de destino precisa oferecer suporte à síntese de carga de trabalho. Uma Recipe que importa uma entrada de biblioteca mas se vincula a um provedor que não consegue sintetizar um Workload é interrompida com um erro explícito no momento da renderização, em vez de emitir uma forma degradada; o catálogo da biblioteca padrão declara workloadSchema nos provedores que oferecem esse suporte, como contrato documentado.

Modo de autoria único

A WorkloadLibrary vem com um único modo de autoria: templates Go. spec não aceita nenhuma superfície de autoria paralela nem nenhuma via de escape de expressividade no nível da biblioteca.

O motivo é a uniformidade da superfície de consumo. Recipes e FeatureRecipes são templates Go do começo ao fim, e o próprio conteúdo delas é avaliado pelo mesmo mecanismo de templates Go que resolve um fragmento importado. Uma superfície de autoria paralela obrigaria os autores a alternar entre modelos de avaliação dentro da renderização de uma única Recipe — um modelo para o conteúdo da própria Recipe, outro para cada entrada de biblioteca importada. Manter a superfície uniforme significa que os autores aprendem um único modelo de avaliação e o aplicam em todo lugar.

Autores que precisam de expressividade além do vocabulário de composição dos templates Go compõem em um nível mais alto — Components ou Features que envolvem as entradas da biblioteca com sua própria variação substantiva — em vez de recorrer a uma segunda linguagem de autoria dentro da biblioteca.

Convenções de nomenclatura

Nomes de biblioteca e chaves de entradas de carga de trabalho seguem PascalCase. O JSON Schema do envelope da entidade impõe a convenção em duas posições por meio de restrições de padrão:

  • metadata.name corresponde a ^[A-Z][A-Za-z0-9]*$.
  • As chaves do mapa spec.workloads seguem o mesmo padrão por meio de propertyNames.

Uma WorkloadLibrary com uma chave fora do PascalCase em spec.workloads falha na validação do envelope no carregamento do workspace. A imposição é essencial: as chaves das entradas de carga de trabalho aparecem no fragmento de referência #/workloads/<name>, então uma chave fora do PascalCase se propagaria por todos os consumidores que importam a entrada.

A uniformidade de nomes mantém o fragmento #/workloads/<name> legível: #/workloads/BatchJob se entende de relance.

Referenciando entradas de biblioteca

Autores de Recipe e FeatureRecipe referenciam uma entrada de carga de trabalho dentro de um bloco workload: { $import: ... } pela sua identidade de nome simples:

# Inside a Recipe's spec:
spec:
workload:
$import: "BaseWorkloads#/workloads/SimpleServer"

O fragmento #/workloads/<name> seleciona a entrada e distingue uma referência de carga de trabalho do #/mappings/<name> da MappingLibrary e do #/schemas/<name> da SchemaLibrary. A referência não traz nenhum host de registry; uma forma oci://… com host é rejeitada tanto pelo esquema do envelope quanto no ponto de consumo, de modo que uma localização física de registry nunca entra no código-fonte escrito. Um autor pode declarar um piso opcional de versão mínima como <Library>:<version>#/workloads/<name> — o separador de versão é :, como nos mapeamentos de recipe/feature e no pin do lockfile, e escrever @ no lugar é recusado com um diagnóstico que indica a referência corrigida. A versão resolvida é fornecida pelo lockfile de cada Release, que fixa cada biblioteca consumida por nome, versão e digest do conteúdo; a localização física é vinculada no momento da resolução.

O mesmo campo workload: aceita duas outras formas — uma string de template Go inline e um $import: de um caminho de arquivo local relativo ao diretório da Recipe. As três formas se distinguem pelo formato do conteúdo, e as três produzem o mesmo Workload após o parsing. Veja Recipe para saber como workload: se compõe com os outros tipos de entrada da Recipe, e vocabulary/cross-document-ref para a distinção mais ampla $ref: / $import:.

Composição entre bibliotecas

Uma entrada de WorkloadLibrary pode ser um redirecionamento $import: na raiz do campo: o primeiro token do seu corpo é $import: <Library>#/workloads/<entry>, que substitui a entrada inteira pelo conteúdo da entrada referenciada — reutilização por identidade, não templating no lugar. O redirecionamento é resolvido no momento do consumo, não no carregamento da WorkloadLibrary, e é resolvido recursivamente, de modo que uma entrada importada pode ela mesma ser um $import: na raiz do campo. Uma cadeia que volta para si mesma é interrompida com um diagnóstico que indica o ciclo. $import: vale apenas para a entrada inteira; não é uma função de template para usar no meio de um fragmento. Para compor texto de template dentro de uma única entrada, use define / template dos templates Go.

# In library A — alias an entry to a shared entry in another library:
spec:
workloads:
StandardServer: |
$import: PlatformWorkloads#/workloads/MetricsServer

Um nome de biblioteca desconhecido e um nome de entrada ausente de uma biblioteca que é resolvida são relatados como diagnósticos distintos, para que um autor consiga distinguir uma dependência ausente de uma entrada com erro de digitação.

Posicionamento nos tiers

A WorkloadLibrary é de nível 3 no modelo de documentação por níveis de entidades — opcional para catálogos que precisam de reutilização de carga de trabalho entre uma Recipe e outra. Catálogos cujas Recipes trazem seu próprio conteúdo de carga de trabalho distinto são distribuídos sem nenhuma entidade WorkloadLibrary; a marcação de nível sinaliza “avançado; pule se não precisar” para a navegação na documentação, não para a capacidade. O compilador trata a WorkloadLibrary de forma uniforme com os outros tipos de entidade do catálogo: a mesma validação do envelope no carregamento do workspace, o mesmo pipeline de publicação OCI no momento de publicar uma versão, o mesmo pinning no lockfile por nome, versão e digest do conteúdo.

O tipo de biblioteca é um de um conjunto no nível do catálogo — a SchemaLibrary contém definições de esquema reutilizáveis, a MappingLibrary fragmentos de mapeamento reutilizáveis, a ArtifactLibrary pacotes de artefatos reutilizáveis, a WorkloadLibrary conteúdo de carga de trabalho reutilizável. Cada um é opcional de forma independente; os catálogos distribuem os que precisam e nenhum dos outros.

O que a WorkloadLibrary não é

Alguns equívocos comuns que vale a pena evitar:

  • Não é um substituto do workload: inline. A maioria das Recipes traz conteúdo de carga de trabalho específico o bastante para ficar inline, onde o autor o lê junto com o resto da Recipe. Uma WorkloadLibrary ajuda quando a MESMA forma de carga de trabalho aparece em muitas Recipes; para conteúdo pontual, a autoria inline é a escolha certa.

  • Não é um lugar para fragmentos parciais. Uma entrada é renderizada como um documento Workload completo. O documento de valores de uma Recipe pertence a uma MappingLibrary, um conjunto de arquivos auxiliares a uma ArtifactLibrary, e as definições de esquema a uma SchemaLibrary. Os tipos de biblioteca se dividem por tipo de conteúdo, não por padrão de reutilização.

  • Não é uma entidade implantável de forma independente. Uma entrada de biblioteca é conteúdo Workload, e conteúdo Workload nunca é endereçável por si só — ele existe como a entrada que uma Recipe ou uma FeatureRecipe consome. Publicar uma WorkloadLibrary torna suas entradas importáveis; não as torna implantáveis.

  • Não é reutilização paramétrica além dos mecanismos dos templates Go. Autores que precisam de variação paramétrica usam a mecânica {{ define }} + {{ template }} dos templates Go dentro das entradas de biblioteca, ou o contexto de pilares que a Recipe consumidora fornece. A entidade de biblioteca em si não traz nenhum mecanismo de helpers paramétricos.