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/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: 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.namecorresponde a^[A-Z][A-Za-z0-9]*$.- As chaves do mapa
spec.mappingscorrespondem ao mesmo padrão através depropertyNames.
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/PrometheusAnnotationsAs 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údovaluesMapping: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 blocotemplatesanálogo aos helpers paramétricosspec.templatesda SchemaLibrary); o vocabulário de composição dos templates Go abrange o mesmo caso de utilização.