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

MappingLibrary

Uma MappingLibrary é uma entidade de catálogo que contém fragmentos de template Go reutilizáveis. As Recipes e FeatureRecipes que partilham um documento valuesMapping: inteiro — os valores que várias Recipes que obtêm o mesmo chart lhe passam, cada uma — declaram-no uma vez numa biblioteca e referenciam-no no momento do consumo através de uma diretiva valuesMapping: { $import: ... }. A entidade de biblioteca é de nível 3: opcional, para catálogos que precisam de reutilizar mapeamentos entre Recipes. Os catálogos sem conteúdo de template repetido são disponibilizados sem nenhuma MappingLibrary.

O papel da MappingLibrary

Os arquitetos de plataforma criam MappingLibraries para centralizar fragmentos de template Go que se repetem nas Recipes e FeatureRecipes do catálogo. Uma biblioteca não é uma instrução de build implementável; é um espaço de nomes de definições. Os autores de Recipe e FeatureRecipe referenciam entradas de biblioteca através de uma diretiva $import:, escrita uma vez e consumida onde quer que a importação seja resolvida.

A divisão entre «biblioteca» e «consumidor» é intencional. As Recipes codificam instruções de build (source, valuesMapping, artifacts). As FeatureRecipes codificam anexações comportamentais. As MappingLibraries codificam apenas fragmentos de template — o conteúdo de template Go que outras entidades consomem no momento da renderização. 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 template partilhado nunca encontram a entidade de biblioteca.

Envelope da entidade

Uma entidade MappingLibrary tem o envelope padrão do catálogo. apiVersion: aggrega.ai/v1beta1 e kind: MappingLibrary marcam o tipo de entidade; metadata.name é um identificador em PascalCase; metadata.version segue um versionamento semântico estrito. O conteúdo da biblioteca fica sob spec.mappings, um mapa obrigatório que tem de declarar pelo menos uma entrada.

apiVersion: aggrega.ai/v1beta1
kind: MappingLibrary
metadata:
name: BaseMappings
version: 1.0.0
spec:
mappings:
SimpleValues: 'image: {{ .values.image }}'
Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'

Uma entrada é avaliada pelo próprio motor de templates da Recipe que a consome, no contexto de renderização da Recipe, pelo que lê os pilares em minúsculas que o próprio valuesMapping: de uma Recipe lê — .values, .infra, .context e os restantes — e usa as mesmas funções, como o helper optional, sensível à presença, para uma chave ausente. .Values, a grafia do Helm para os valores do chart, não é uma raiz que esse contexto defina: uma entrada que o lê interrompe o build, indicando a referência.

Criar entradas de mapeamento

Cada entrada de mapeamento é um fragmento de template Go criado como uma string YAML. O fragmento é opaco para o envelope da entidade — o compilador guarda a string literalmente no carregamento da MappingLibrary e analisa-a no momento do consumo, quando uma Recipe ou FeatureRecipe importa a entrada através de valuesMapping: { $import: ... }. A importação substitui todo o valuesMapping: da Recipe — o mapa $import: não contém nenhuma outra chave —, pelo que uma entrada é um documento de valores completo e não um excerto inserido num documento.

Os fragmentos curtos cabem numa única linha:

spec:
mappings:
AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'

Os fragmentos com várias linhas usam o escalar de estilo literal do YAML (|) para que as quebras de linha e a indentação sobrevivam à ida e volta:

spec:
mappings:
ProbeBlock: |
readinessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}
livenessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}

Todo o vocabulário de composição dos templates Go está disponível dentro dos fragmentos: {{ define "name" }}...{{ end }} declara blocos reutilizáveis dentro de uma única biblioteca; {{ template "name" . }} invoca-os; os pipelines e as funções são suportados segundo o pacote Go padrão text/template.

Modo de autoria único

A MappingLibrary é disponibilizada com um único modo de criação: templates Go. spec não aceita nenhuma superfície de criação paralela nem nenhuma via de escape de expressividade ao nível da biblioteca.

A razão é a uniformidade da superfície de consumo. As Recipes e FeatureRecipes são inteiramente em template Go, e o seu próprio conteúdo é avaliado pelo mesmo motor de templates Go que resolve uma entrada importada, pelo que uma entrada se lê exatamente como o próprio texto da Recipe e os autores aprendem um único modelo de avaliação. O vocabulário de composição dos templates Go — {{ define }} e {{ template }} dentro de uma biblioteca, e a diretiva $import: no momento do consumo — fornece os blocos reutilizáveis e a invocação parametrizada de que uma biblioteca precisa.

Os autores que precisem de expressividade além do que o vocabulário de composição dos templates Go oferece compõem a um nível superior — Components ou Features que encapsulam as entradas da biblioteca com a sua própria variação substantiva — em vez de escalarem para uma linguagem de criação paralela dentro da própria MappingLibrary.

Convenções de nomenclatura

Os nomes das bibliotecas e as chaves das entradas de mapeamento 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.mappings correspondem ao mesmo padrão através de propertyNames.

Uma MappingLibrary com uma chave que não está em PascalCase em spec.mappings falha a validação do envelope no carregamento do espaço de trabalho. A imposição é estrutural: as chaves das entradas de mapeamento aparecem no fragmento de referência #/mappings/<name>; chaves que não estivessem em PascalCase propagar-se-iam por todos os consumidores que importam a entrada.

A uniformidade dos nomes mantém o fragmento #/mappings/<name> legível: #/mappings/ProbeBlock lê-se num relance.

Referenciar entradas da biblioteca

Os autores de Recipe e FeatureRecipe referenciam uma entrada de mapeamento dentro de um bloco valuesMapping: { $import: ... } pela sua identidade de nome simples:

# Inside a Recipe's valuesMapping block:
spec:
valuesMapping:
$import: "BaseMappings#/mappings/ProbeBlock"

O fragmento #/mappings/<name> seleciona a entrada e distingue uma referência de mapeamento do #/schemas/<name> da SchemaLibrary. A referência usa o mesmo modelo de identidade de nome simples que o $ref: da SchemaLibrary — <Library>#/mappings/<name>, sem nenhum host de registo. A versão é fornecida pelo lockfile por Release (nome + versão + digest de conteúdo); um autor pode afirmar um mínimo de versão opcional como <Library>:<version>#/mappings/<name> (o separador de versão é :, tal como nos mapeamentos de receitas/funcionalidades e na fixação do lockfile), e a localização física é associada no momento da resolução.

Composição entre bibliotecas

Uma entrada de MappingLibrary pode ser um redirecionamento $import: na raiz do campo: o primeiro token do seu corpo é $import: <Library>#/mappings/<entry>, que substitui a entrada inteira pelo conteúdo da entrada referenciada — reutilização por identidade, não templating no local. O redirecionamento é resolvido no momento do consumo (renderização da Recipe), não no carregamento da MappingLibrary, e de forma recursiva — uma entrada importada pode ela própria ser um $import: na raiz do campo. $import: aplica-se apenas à entrada inteira; não é uma função de template a meio de um fragmento. Para compor texto de template dentro de um único fragmento, use define / template dos templates Go.

# In library A — alias an entry to a shared entry in another library:
spec:
mappings:
StandardProbe: |
$import: MonitoringLibrary#/mappings/PrometheusAnnotations

As bibliotecas podem referenciar-se umas às outras livremente. Uma cadeia que volta sobre si mesma é interrompida quando a Recipe que a consome é renderizada, com um diagnóstico que indica cada passo do ciclo.

Posicionamento por nível

A MappingLibrary é de nível 3 no modelo de documentação por níveis de entidades — opcional para catálogos que precisam de reutilizar mapeamentos entre Recipes. Os catálogos sem conteúdo de template repetido são disponibilizados sem nenhuma entidade MappingLibrary; 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 MappingLibrary uniformemente com os outros tipos de entidade de catálogo: a mesma validação do envelope no carregamento do espaço de trabalho, o mesmo pipeline de publicação OCI no momento da publicação de versões.

O tipo de biblioteca combina naturalmente com a SchemaLibrary ao nível do catálogo — a SchemaLibrary contém definições de esquemas reutilizáveis; a MappingLibrary contém fragmentos de template reutilizáveis. Os catálogos que precisam de ambas disponibilizam ambas; os catálogos que não precisam de nenhuma não disponibilizam nenhuma.

O que a MappingLibrary não é

Alguns equívocos comuns que vale a pena evitar:

  • Não substitui o valuesMapping: inline. A maioria das Recipes contém conteúdo valuesMapping: simples que beneficia de ser criado inline — a Recipe permanece autossuficiente e o autor lê o conteúdo do mapeamento a par do resto da Recipe. A MappingLibrary ajuda quando o MESMO fragmento aparece em muitas Recipes; para mapeamentos pontuais, a criação inline é a escolha certa.

  • Não é um local para conteúdo de esquemas. As definições de esquemas (JSON Schema 2020-12) pertencem à SchemaLibrary; os fragmentos de template pertencem aqui. Os tipos de biblioteca dividem-se por tipo de conteúdo, não por padrão de reutilização.

  • Não é reutilização paramétrica além dos mecanismos dos templates Go. Os autores que precisam de variação paramétrica usam a mecânica {{ define }} + {{ template arg }} dos templates Go dentro das entradas da biblioteca, ou compõem Components / Features que encapsulam as entradas da biblioteca com a sua própria variação. A própria entidade de biblioteca não tem nenhuma mecânica de helpers paramétricos (nenhum bloco templates análogo aos helpers paramétricos spec.templates da SchemaLibrary); o vocabulário de composição dos templates Go abrange o mesmo caso de utilização.