MappingLibrary
Una MappingLibrary es una entidad de catálogo que contiene fragmentos de plantilla Go reutilizables. Las Recipes y FeatureRecipes que comparten un documento valuesMapping: completo — los valores que varias Recipes que obtienen el mismo chart le pasan cada una — lo declaran una vez en una biblioteca y lo referencian en el momento del consumo mediante una directiva valuesMapping: { $import: ... }. La entidad de biblioteca es de nivel 3: opcional, para los catálogos que necesitan reutilizar mappings entre Recipes. Los catálogos sin contenido de plantilla repetido se publican sin ninguna MappingLibrary.
El papel de la MappingLibrary
Los arquitectos de plataforma escriben MappingLibraries para centralizar los fragmentos de plantilla Go que se repiten en las Recipes y FeatureRecipes del catálogo. Una biblioteca no es una instrucción de build desplegable; es un espacio de nombres de definiciones. Los autores de Recipe y FeatureRecipe hacen referencia a las entradas de la biblioteca mediante una directiva $import:, escrita una vez y consumida dondequiera que se resuelva la importación.
La separación entre «biblioteca» y «consumidor» es intencionada. Las Recipes codifican instrucciones de build (source, valuesMapping, artifacts). Las FeatureRecipes codifican vinculaciones de comportamiento. Las MappingLibraries codifican solo fragmentos de plantilla — el contenido de plantilla Go que otras entidades consumen en el momento del renderizado. Mantener los tres roles separados permite que cada tipo de entidad evolucione a su propio ritmo; los autores que no necesitan contenido de plantilla compartido nunca se encuentran con la entidad de biblioteca.
Envoltorio de la entidad
Una entidad MappingLibrary lleva el envoltorio estándar del catálogo. apiVersion: aggrega.ai/v1beta1 y kind: MappingLibrary marcan el tipo de entidad; metadata.name es un identificador en PascalCase; metadata.version sigue un versionado semántico estricto. El contenido de la biblioteca se encuentra bajo spec.mappings, un mapa obligatorio que debe declarar al menos una entrada.
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: mappings: SimpleValues: 'image: {{ .values.image }}' Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'Una entrada la evalúa el propio motor de plantillas de la Recipe que la consume, sobre el contexto de renderizado de la Recipe, por lo que lee los pilares en minúsculas que lee el propio valuesMapping: de una Recipe — .values, .infra, .context y los demás — y usa las mismas funciones, como el helper optional, que tiene en cuenta la presencia, para una clave ausente. .Values, la grafía de Helm para los valores del chart, no es una raíz que ese contexto defina: una entrada que la lee detiene la compilación y nombra la referencia.
Escribir entradas de mapping
Cada entrada de mapping es un fragmento de plantilla Go escrito como una cadena YAML. El fragmento es opaco para el envoltorio de la entidad — el compilador almacena la cadena literalmente al cargar la MappingLibrary y la analiza en el momento del consumo, cuando una Recipe o FeatureRecipe importa la entrada mediante valuesMapping: { $import: ... }. La importación sustituye todo el valuesMapping: de la Recipe — el mapa $import: no lleva ninguna otra clave —, de modo que una entrada es un documento de valores completo y no un fragmento insertado en uno.
Los fragmentos cortos caben en una sola línea:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'Los fragmentos de varias líneas usan el escalar de estilo literal de YAML (|) para que los saltos de línea y la sangría sobrevivan al ida y vuelta:
spec: mappings: ProbeBlock: | readinessProbe: httpGet: path: /healthz port: {{ .values.port }} livenessProbe: httpGet: path: /healthz port: {{ .values.port }}Todo el vocabulario de composición de las plantillas Go está disponible dentro de los fragmentos: {{ define "name" }}...{{ end }} declara bloques reutilizables dentro de una misma biblioteca; {{ template "name" . }} los invoca; las canalizaciones y funciones se admiten según el paquete estándar de Go text/template.
Un único modo de autoría
MappingLibrary se publica con un único modo de autoría: plantillas Go. spec no acepta ninguna superficie de autoría paralela ni ninguna vía de escape de expresividad a nivel de biblioteca.
El motivo es la uniformidad de la superficie de consumo. Las Recipes y FeatureRecipes son plantillas Go de principio a fin, y su propio contenido se evalúa con el mismo motor de plantillas Go que resuelve una entrada importada, de modo que una entrada se lee exactamente como el propio texto de la Recipe y los autores aprenden un único modelo de evaluación. El vocabulario de composición de las plantillas Go — {{ define }} y {{ template }} dentro de una biblioteca, y la directiva $import: en el momento del consumo — proporciona los bloques reutilizables y la invocación parametrizada que una biblioteca necesita.
Los autores que necesitan una expresividad mayor que la que ofrece el vocabulario de composición de las plantillas Go componen a un nivel superior — Components o Features que envuelven las entradas de la biblioteca con su propia variación sustancial — en lugar de pasar a un lenguaje de autoría paralelo dentro de la propia MappingLibrary.
Convenciones de nomenclatura
Los nombres de biblioteca y las claves de las entradas de mapping siguen PascalCase. El JSON Schema del envoltorio de la entidad aplica la convención en dos posiciones mediante restricciones de patrón:
metadata.namecoincide con^[A-Z][A-Za-z0-9]*$.- Las claves del mapa
spec.mappingscoinciden con el mismo patrón mediantepropertyNames.
Una MappingLibrary con una clave que no está en PascalCase en spec.mappings no supera la validación del envoltorio al cargar el workspace. La aplicación es estructural: las claves de las entradas de mapping aparecen en el fragmento de referencia #/mappings/<name>; las claves que no estuvieran en PascalCase se propagarían a todos los consumidores que importan la entrada.
La uniformidad de nombres mantiene legible el fragmento #/mappings/<name>: #/mappings/ProbeBlock se entiende de un vistazo.
Referenciar entradas de biblioteca
Los autores de Recipe y FeatureRecipe hacen referencia a una entrada de mapping dentro de un bloque valuesMapping: { $import: ... } por su identidad de nombre simple:
# Inside a Recipe's valuesMapping block:spec: valuesMapping: $import: "BaseMappings#/mappings/ProbeBlock"El fragmento #/mappings/<name> selecciona la entrada y distingue una referencia de mapping del #/schemas/<name> de la SchemaLibrary. La referencia usa el mismo modelo de identidad por nombre simple que el $ref: de la SchemaLibrary — <Library>#/mappings/<name>, sin ningún host de registro. La versión la proporciona el lockfile de cada Release (nombre + versión + digest del contenido); un autor puede afirmar un mínimo de versión opcional como <Library>:<version>#/mappings/<name> (el separador de versión es :, igual que en los mappings de recipe/feature y en el pin del lockfile), y la ubicación física se vincula en el momento de la resolución.
Composición entre bibliotecas
Una entrada de MappingLibrary puede ser una redirección $import: en la raíz del campo: el primer token de su cuerpo es $import: <Library>#/mappings/<entry>, que sustituye toda la entrada por el contenido de la entrada referenciada — reutilización por identidad, no plantillas in situ. La redirección se resuelve en el momento del consumo (renderizado de la Recipe), no al cargar la MappingLibrary, y de forma recursiva — una entrada importada puede ser a su vez un $import: en la raíz del campo. $import: solo se aplica a entradas completas; no es una función de plantilla a mitad de fragmento. Para componer texto de plantilla dentro de un mismo fragmento, usa define / template de las plantillas Go.
# In library A — alias an entry to a shared entry in another library:spec: mappings: StandardProbe: | $import: MonitoringLibrary#/mappings/PrometheusAnnotationsLas bibliotecas pueden hacer referencia unas a otras libremente. Una cadena que vuelve sobre sí misma se detiene cuando se renderiza la Recipe que la consume, con un diagnóstico que nombra cada paso del ciclo.
Ubicación en los tiers
MappingLibrary es de nivel 3 en el modelo de documentación por niveles de entidades — opcional para los catálogos que necesitan reutilizar mappings entre Recipes. Los catálogos sin contenido de plantilla repetido se publican sin ninguna entidad MappingLibrary; la marca de nivel indica «avanzado; omitir si no se necesita» para la navegación de la documentación, no una capacidad. El compilador trata MappingLibrary de manera uniforme con los demás tipos de entidad de catálogo: la misma validación del envoltorio al cargar el workspace, la misma canalización de publicación OCI en el momento de publicar una versión.
El tipo de biblioteca se combina de forma natural con SchemaLibrary a nivel de catálogo — SchemaLibrary contiene definiciones de esquema reutilizables; MappingLibrary contiene fragmentos de plantilla reutilizables. Los catálogos que necesitan ambas publican ambas; los que no necesitan ninguna no publican ninguna.
Lo que no es la MappingLibrary
Algunos malentendidos habituales que conviene evitar:
-
No sustituye a
valuesMapping:en línea. La mayoría de las Recipes contienen contenidovaluesMapping:sencillo que se beneficia de escribirse en línea — la Recipe sigue siendo autónoma y el autor lee el contenido del mapeo junto con el resto de la Recipe. La MappingLibrary ayuda cuando el MISMO fragmento aparece en muchas Recipes; para mapeos puntuales, la escritura en línea es la elección correcta. -
No es un lugar para contenido de esquema. Las definiciones de esquema (JSON Schema 2020-12) van en la SchemaLibrary; los fragmentos de plantilla van aquí. Los tipos de biblioteca se dividen por tipo de contenido, no por patrón de reutilización.
-
No es reutilización paramétrica más allá de los mecanismos de las plantillas Go. Los autores que necesitan variación paramétrica usan la mecánica
{{ define }}+{{ template arg }}de las plantillas Go dentro de las entradas de la biblioteca, o componen Components / Features que envuelven las entradas de la biblioteca con su propia variación. La propia entidad de biblioteca no incluye ninguna mecánica de helpers paramétricos (ningún bloquetemplatesanálogo a los helpers paramétricosspec.templatesde la SchemaLibrary); el vocabulario de composición de las plantillas Go cubre el mismo caso de uso.