MappingLibrary
Uma MappingLibrary é uma entidade de catálogo que contém fragmentos de template Go reutilizáveis. Recipes e FeatureRecipes que compartilham um documento valuesMapping: inteiro — os valores que várias Recipes que usam o mesmo chart passam a ele, cada uma — o declaram uma vez em uma biblioteca e o referenciam no momento do consumo por meio de uma diretiva valuesMapping: { $import: ... }. A entidade de biblioteca é de nível 3: opcional, para catálogos que precisam reutilizar mappings entre Recipes. Catálogos sem conteúdo de template repetido são publicados sem nenhuma MappingLibrary.
O papel da MappingLibrary
Arquitetos de plataforma escrevem 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 implantável; é um namespace de definições. Autores de Recipe e FeatureRecipe referenciam entradas da biblioteca por 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 no seu próprio ritmo; autores que não precisam de conteúdo de template compartilhado nunca encontram a entidade de biblioteca.
Envelope da entidade
Uma entidade MappingLibrary traz 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 versionamento semântico estrito. O conteúdo da biblioteca fica sob spec.mappings, um mapa obrigatório que deve 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 mecanismo de templates da Recipe que a consome, no contexto de renderização da Recipe, então ela lê os pilares em minúsculas que o próprio valuesMapping: de uma Recipe lê — .values, .infra, .context e os demais — 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 define: uma entrada que o lê interrompe o build, nomeando a referência.
Escrevendo entradas de mapping
Cada entrada de mapping é um fragmento de template Go escrito como uma string YAML. O fragmento é opaco para o envelope da entidade — o compilador armazena a string literalmente no carregamento da MappingLibrary e a analisa no momento do consumo, quando uma Recipe ou FeatureRecipe importa a entrada via valuesMapping: { $import: ... }. A importação substitui todo o valuesMapping: da Recipe — o mapa $import: não traz nenhuma outra chave —, de modo que uma entrada é um documento de valores completo, e não um trecho inserido em um.
Fragmentos curtos cabem em uma única linha:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'Fragmentos de várias linhas usam o escalar de estilo literal do YAML (|) para que quebras de linha e 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" . }} os invoca; pipelines e funções são suportados conforme o pacote padrão do Go text/template.
Modo de autoria único
A MappingLibrary é publicada 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 inteiramente em template Go, e o próprio conteúdo delas é avaliado pelo mesmo mecanismo de templates Go que resolve uma entrada importada, de modo 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.
Autores que precisam de mais expressividade do que o vocabulário de composição dos templates Go oferece compõem em um nível mais alto — Components ou Features que envolvem as entradas da biblioteca com sua própria variação substancial — em vez de recorrer a uma linguagem de autoria paralela dentro da própria MappingLibrary.
Convenções de nomenclatura
Nomes de bibliotecas e chaves de entradas de mapping seguem PascalCase. O JSON Schema do envelope da entidade aplica a convenção em duas posições por meio 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 viapropertyNames.
Uma MappingLibrary com uma chave fora de PascalCase em spec.mappings falha na validação do envelope no carregamento do workspace. A aplicação é estrutural: as chaves das entradas de mapping aparecem no fragmento de referência #/mappings/<name>; chaves fora de PascalCase se propagariam por todo consumidor que importa a entrada.
A uniformidade de nomes mantém legível o fragmento #/mappings/<name>: #/mappings/ProbeBlock se entende num relance.
Referenciando entradas de biblioteca
Autores de Recipe e FeatureRecipe referenciam uma entrada de mapping 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 mapping do #/schemas/<name> da SchemaLibrary. A referência usa o mesmo modelo de identidade por nome simples que o $ref: da SchemaLibrary — <Library>#/mappings/<name>, sem nenhum host de registry. A versão é fornecida pelo lockfile de cada Release (nome + versão + digest do conteúdo); um autor pode declarar um piso opcional de versão mínima como <Library>:<version>#/mappings/<name> (o separador de versão é :, igual aos mappings de recipe/feature e ao pin do lockfile), e a localização física é vinculada 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 próprio 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: vale apenas para a entrada inteira; não é uma função de template no 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 umas às outras livremente. Uma cadeia que volta sobre si mesma é interrompida quando a Recipe que a consome é renderizada, com um diagnóstico que nomeia cada passo do ciclo.
Posicionamento nos tiers
A MappingLibrary é de nível 3 no modelo de documentação por níveis de entidades — opcional para catálogos que precisam reutilizar mappings entre Recipes. Catálogos sem conteúdo de template repetido são publicados sem nenhuma entidade MappingLibrary; a marcação de nível sinaliza “avançado; pule se não precisar” para a navegação na documentação, não uma capacidade. O compilador trata a MappingLibrary de maneira uniforme em relação aos demais 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 publicação de uma versão.
O tipo de biblioteca combina naturalmente com a SchemaLibrary no nível do catálogo — a SchemaLibrary contém definições de schema reutilizáveis; a MappingLibrary contém fragmentos de template reutilizáveis. Catálogos que precisam das duas publicam as duas; catálogos que não precisam de nenhuma não publicam 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 traz conteúdovaluesMapping:simples que se beneficia de ser escrito inline — a Recipe permanece autocontida e o autor lê o conteúdo do mapeamento junto com o resto da Recipe. A MappingLibrary ajuda quando o MESMO fragmento aparece em muitas Recipes; para mapeamentos pontuais, escrever inline é a escolha certa. -
Não é um lugar para conteúdo de schema. Definições de schema (JSON Schema 2020-12) pertencem à SchemaLibrary; fragmentos de template pertencem a este lugar. Os tipos de biblioteca se dividem 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. 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 envolvem as entradas da biblioteca com sua própria variação. A própria entidade de biblioteca não traz 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 cobre o mesmo caso de uso.