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

WorkloadLibrary

Uma WorkloadLibrary é uma entidade de catálogo que contém fragmentos de template de Workload reutilizáveis. As Recipes e FeatureRecipes que implementam a mesma forma de workload — um servidor que expõe métricas, um job batch, um par com sidecar — declaram essa forma uma vez numa biblioteca e referenciam-na no momento do consumo através de uma diretiva workload: { $import: ... }. A entidade de biblioteca é de Nível 3: opcional para catálogos que precisam de reutilizar workloads entre Recipes. Os catálogos cujas Recipes têm cada uma a sua própria forma de workload distinta são disponibilizados sem nenhuma WorkloadLibrary.

O papel da WorkloadLibrary

Os 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 implementável; é um espaço de nomes de definições. Os autores de Recipes e FeatureRecipes referenciam as entradas da biblioteca através de 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 anexos comportamentais. As WorkloadLibraries codificam apenas conteúdo de Workload — a forma de workload que o fornecedor sintetiza em manifestos nativos do fornecedor. Manter os três papéis distintos permite que cada tipo de entidade evolua ao seu próprio ritmo; os autores que não precisam de conteúdo de workload partilhado nunca encontram a entidade de biblioteca.

Envelope da entidade

Uma entidade WorkloadLibrary tem o envelope de catálogo habitual. apiVersion: aggrega.ai/v1beta1 e kind: WorkloadLibrary marcam o tipo de entidade; metadata.name é um identificador em PascalCase; metadata.version segue estritamente o controlo semântico de versões. Ambos são obrigatórios. metadata.description, metadata.labels e metadata.annotations são opcionais — as etiquetas e as anotações são metadados opacos declarados pelo autor, transportados para que aquilo que lê a biblioteca possa fazer correspondência com eles, e o compilador não interpreta os seus valores. O conteúdo da biblioteca fica em spec.workloads, um mapa obrigatório que tem de declarar pelo menos uma entrada.

O envelope é fechado nos três níveis — a raiz do documento, metadata e spec rejeitam cada um as 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 de Workload

Cada entrada é um fragmento de template Go escrito como string YAML. A saída renderizada da entrada é um documento Workload completo — contém os seus próprios apiVersion: aggrega.ai/v1beta1 e kind: Workload — porque o campo workload: de uma Recipe aceita um Workload completo, e não um fragmento inserido noutro, e a importação substitui todo o campo. 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 nessa altura; o parser de templates é executado no momento do consumo, quando uma Recipe ou FeatureRecipe importa a entrada. Armazenar o fragmento literalmente preserva a fidelidade da autoria para nova emissão, e significa que um erro de template surge onde a entrada é consumida e o 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 as quebras de linha e a indentação sobrevivam ao percurso de 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 tem de ser um escalar de string. Escrever um mapeamento ou uma sequência onde deve estar o corpo é rejeitado — o corpo da entrada é texto de template, não YAML estruturado que o compilador percorre.

Todo o vocabulário de composição do template Go está disponível dentro de uma entrada: {{ define "name" }}...{{ end }} declara blocos reutilizáveis dentro de uma única biblioteca, {{ template "name" . }} invoca-os, e os pipelines e as funções seguem o pacote text/template da biblioteca standard do Go. 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, em avaliação de templates.

O provider de destino tem de suportar a síntese de workloads. Uma Recipe que importe uma entrada de biblioteca mas esteja associada a um provider que não consegue sintetizar um Workload é interrompida de forma explícita no momento da renderização, em vez de emitir uma forma degradada; o catálogo da biblioteca standard declara workloadSchema nos providers que a suportam, como contrato documentado.

Modo de autoria único

A WorkloadLibrary é disponibilizada 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 ao nível da biblioteca.

O motivo é a uniformidade da superfície de consumo. As Recipes e FeatureRecipes são integralmente em template Go, e o seu próprio conteúdo é avaliado pelo mesmo motor de templates Go que resolve um fragmento importado. Uma superfície de autoria paralela obrigaria os autores a mudar de modelo de avaliação dentro da renderização de uma única Recipe — um modelo para o conteúdo próprio da Recipe, outro para qualquer entrada de biblioteca importada. Manter a superfície uniforme significa que os autores aprendem um modelo de avaliação e aplicam-no em todo o lado.

Os autores que precisem de expressividade para além do vocabulário de composição do template Go compõem a um nível superior — Components ou Features que envolvem as entradas da biblioteca com a sua própria variação substantiva — em vez de recorrerem a uma segunda linguagem de autoria dentro da biblioteca.

Convenções de nomenclatura

Os nomes de bibliotecas e as chaves das entradas de workload seguem PascalCase. O JSON Schema do envelope da entidade impõe a convenção em duas posições através de restrições de padrão:

  • metadata.name corresponde a ^[A-Z][A-Za-z0-9]*$.
  • As chaves do mapa spec.workloads correspondem ao mesmo padrão através de propertyNames.

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

A uniformidade de nomenclatura mantém o fragmento #/workloads/<name> legível: #/workloads/BatchJob lê-se num relance.

Referenciar entradas da biblioteca

Os autores de Recipes e FeatureRecipes referenciam uma entrada de workload 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 workload do #/mappings/<name> da MappingLibrary e do #/schemas/<name> da SchemaLibrary. A referência não contém nenhum host de registo; uma forma oci://… com host é rejeitada tanto pelo esquema do envelope como no local de consumo, pelo que uma localização física de registo nunca entra no source escrito. Um autor pode indicar um limite mínimo de versão opcional como <Library>:<version>#/workloads/<name> — o separador de versão é :, tal como nos mapeamentos de recipes/features e na fixação do lockfile, e escrever @ em vez dele é 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 de conteúdo; a localização física é definida 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 ficheiro local relativo ao diretório da Recipe. As três formas distinguem-se pela forma do conteúdo, e todas produzem o mesmo Workload após a análise. Consulte 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 entre $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 toda a entrada pelo conteúdo da entrada referenciada — reutilização por identidade, não templating no local. O redirecionamento é resolvido no momento do consumo, não no carregamento da WorkloadLibrary, e é resolvido recursivamente, pelo que uma entrada importada pode ela própria ser um $import: na raiz do campo. Uma cadeia que volte sobre si própria é interrompida com um diagnóstico que indica o ciclo. $import: aplica-se apenas à entrada completa; não é uma função de template a meio de um fragmento. Para compor texto de template dentro de uma única entrada, use define / template de template 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 reportados como diagnósticos distintos, para que um autor consiga distinguir uma dependência em falta de uma entrada com erro ortográfico.

Posicionamento por nível

A WorkloadLibrary é de Nível 3 no modelo de documentação por níveis de entidade — opcional para catálogos que precisam de reutilizar workloads entre Recipes. Os catálogos cujas Recipes têm o seu próprio conteúdo de workload distinto são disponibilizados sem nenhuma entidade WorkloadLibrary; a marcação de nível sinaliza «avançado; ignorar se não for necessário» 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 de catálogo: a mesma validação de envelope no carregamento do workspace, o mesmo pipeline de publicação OCI no momento da release, a mesma fixação no lockfile por nome, versão e digest de conteúdo.

O tipo de biblioteca é um de um conjunto ao nível do catálogo — a SchemaLibrary contém definições de esquema reutilizáveis, a MappingLibrary contém fragmentos de mapeamento reutilizáveis, a ArtifactLibrary contém pacotes de artefactos reutilizáveis, a WorkloadLibrary contém conteúdo de workload reutilizável. Cada uma é opcional de forma independente; os catálogos disponibilizam as de que precisam e nenhuma das outras.

O que a WorkloadLibrary não é

Alguns equívocos comuns que vale a pena evitar:

  • Não substitui o workload: inline. A maioria das Recipes contém conteúdo de workload suficientemente específico para pertencer ao inline, onde o autor o lê junto com o resto da Recipe. Uma WorkloadLibrary ajuda quando a MESMA forma de workload 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 ficheiros auxiliares a uma ArtifactLibrary, e as definições de esquema a uma SchemaLibrary. Os tipos de biblioteca dividem-se por tipo de conteúdo, não por padrão de reutilização.

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

  • Não é reutilização paramétrica para além dos mecanismos do template Go. Os autores que precisem de variação paramétrica usam a mecânica {{ define }} + {{ template }} do template Go dentro das entradas da biblioteca, ou o contexto de pilares que a Recipe consumidora fornece. A própria entidade de biblioteca não disponibiliza nenhuma maquinaria de helpers paramétricos.