ArtifactLibrary
Una ArtifactLibrary es una entidad de catálogo que contiene bundles de artefactos reutilizables — conjuntos con nombre de archivos de salida auxiliares que van juntos. Las Recipes y FeatureRecipes que emiten los mismos recursos de apoyo — una CRD con su RBAC y un ConfigMap, una NetworkPolicy junto con un HPA — declaran ese conjunto una sola vez en una biblioteca y lo referencian en el momento del consumo mediante una entrada artifacts: cuyo valor es una directiva $import:. La entidad biblioteca es de Tier 3: opcional para los catálogos que necesitan reutilizar artefactos entre Recipes. Los catálogos cuyas Recipes llevan cada una sus propios archivos auxiliares se distribuyen sin ninguna ArtifactLibrary.
El papel de la ArtifactLibrary
Los arquitectos de plataforma escriben ArtifactLibraries para centralizar los manifiestos auxiliares 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 referencian un bundle mediante una directiva $import:, escrita una vez y consumida dondequiera que se resuelva la importación.
Lo que distingue a este tipo de biblioteca de los otros tres es la granularidad de una entrada. Una entrada de SchemaLibrary es un esquema, una entrada de MappingLibrary es un fragmento de plantilla y una entrada de WorkloadLibrary es un documento Workload — cada una un único cuerpo consumido en un único lugar. Una entrada de ArtifactLibrary es un conjunto de archivos, porque los recursos que agrupa solo son útiles juntos: importar una CRD sin su RBAC produce un conjunto de manifiestos que no funciona. Por eso un bundle es la unidad de reutilización y un único punto de consumo se expande en varias salidas.
Envoltorio de la entidad
Una entidad ArtifactLibrary lleva el envoltorio estándar del catálogo. apiVersion: aggrega.ai/v1beta1 y kind: ArtifactLibrary marcan el tipo de entidad; metadata.name es un identificador en PascalCase; metadata.version sigue un versionado semántico estricto. Ambos son obligatorios. metadata.description, metadata.labels y metadata.annotations son opcionales — las etiquetas y las anotaciones son metadatos opacos declarados por el autor, que se llevan para que lo que lea la biblioteca pueda usarlos en la coincidencia, y el compilador no interpreta sus valores. El contenido de la biblioteca se encuentra bajo spec.artifacts, un mapa obligatorio que debe declarar al menos un bundle.
El envoltorio es cerrado en los tres niveles — la raíz del documento, metadata y spec rechazan cada uno las claves que el esquema no declara.
apiVersion: aggrega.ai/v1beta1kind: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: artifacts: OperatorSupport: crd.yaml: | apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: widgets.platform.example.com spec: group: platform.example.com scope: Namespaced rbac.yaml: | apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: "{{ .context.instance_id }}-operator" rules: - apiGroups: ["platform.example.com"] resources: ["widgets"] verbs: ["get", "list", "watch"]Escribir bundles de artefactos
spec.artifacts tiene dos niveles de profundidad, y cada nivel tiene una función distinta. La clave externa es el nombre del bundle — el identificador que referencia un consumidor. Las claves internas son nombres de archivo, y cada valor interno es el cuerpo de Go template que se emite en ese archivo. Un bundle debe declarar al menos un archivo.
spec: artifacts: NetworkBaseline: deny-all.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-deny-all" spec: podSelector: {} policyTypes: ["Ingress"] allow-dns.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-allow-dns"El cuerpo de un archivo es un fragmento de Go template escrito como cadena YAML. Como un manifiesto ocupa varias líneas, los cuerpos de archivo usan el escalar de estilo literal de YAML (|) para que los saltos de línea y la sangría sobrevivan al ida y vuelta. El valor de una entrada de bundle debe ser una asignación de nombre de archivo a cuerpo de cadena; escribir una cadena simple donde va el bundle, o una secuencia, se rechaza — el nivel que importa un consumidor es el bundle, no un archivo individual.
El cuerpo es opaco para el envoltorio de la entidad. El compilador almacena cada cadena literalmente al cargar la ArtifactLibrary y no analiza allí la plantilla; el analizador de plantillas se ejecuta en el momento del consumo, cuando una Recipe o una FeatureRecipe importa el bundle. Almacenar los cuerpos literalmente preserva la fidelidad a lo escrito para la reemisión, y hace que un error de plantilla aparezca donde se consume el bundle y se conoce su contexto de pilares, en lugar de en la biblioteca.
El orden de los archivos dentro de un bundle es el que escribió el autor, conservado durante la carga y el consumo, de modo que el conjunto emitido es estable entre builds.
Todo el vocabulario de composición de Go template está disponible dentro del cuerpo de un archivo: {{ define "name" }}...{{ end }} declara bloques reutilizables, {{ template "name" . }} los invoca, y los pipelines y las funciones siguen el paquete estándar de Go text/template. El contexto de pilares que puede leer el cuerpo de un archivo — .values, .infra, .locals, .context, .features, y .workload y .source donde la Recipe consumidora los declara — es el contexto que leen las propias entradas artifacts: de la Recipe consumidora, documentado en la página Recipe bajo el campo artifacts:. Un cuerpo que lee .workload donde la Recipe consumidora no declara ningún workload:, o .source donde no declara ningún source:, se detiene con un diagnóstico que nombra la referencia que no pudo satisfacer — cada pilar se comprueba por separado, de modo que declarar uno no autoriza a leer el otro.
Un único modo de autoría
La ArtifactLibrary ofrece un único modo de autoría: Go templates. spec no acepta ninguna superficie de autoría paralela ni ninguna vía de escape de expresividad a nivel de biblioteca.
La razón es la uniformidad de la superficie de consumo. Las Recipes y FeatureRecipes son Go template de principio a fin, y su propio contenido se evalúa con el mismo motor de Go template que resuelve un bundle importado. Una superficie de autoría paralela obligaría a los autores a cambiar de modelo de evaluación dentro del renderizado de una sola Recipe — un modelo para el contenido propio de la Recipe y otro para cada bundle importado. Mantener la superficie uniforme significa que los autores aprenden un único modelo de evaluación y lo aplican en todas partes.
Los autores que necesitan una expresividad mayor que la del vocabulario de composición de Go template componen a un nivel superior — Components o Features que envuelven los bundles de la biblioteca con su propia variación sustancial — en lugar de recurrir a un segundo lenguaje de autoría dentro de la biblioteca.
Convenciones de nomenclatura
Los nombres de biblioteca y de bundle 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.artifactscoinciden con el mismo patrón mediantepropertyNames.
Una ArtifactLibrary con un nombre de bundle que no está en PascalCase no supera la validación del envoltorio al cargar el espacio de trabajo. La aplicación es estructural: los nombres de bundle aparecen en el fragmento de referencia #/artifacts/<name>, de modo que un nombre que no esté en PascalCase se propagaría a cada consumidor que importa el bundle.
La uniformidad de los nombres mantiene legible el fragmento #/artifacts/<name>: #/artifacts/OperatorSupport se entiende de un vistazo.
Los nombres de archivo dentro de un bundle son libres, siempre que cada uno nombre un archivo. No están en PascalCase y ningún patrón de esquema los restringe, porque nombran los archivos que acaba conteniendo la salida de un build — crd.yaml, deny-all.yaml, values-override.json son todos válidos. Lo que un nombre de archivo debe ser es un nombre de archivo relativo ordinario, escrito de forma simple; el build rechaza uno que no nombra un archivo propio, como describe Referenciar entradas de biblioteca. Los dos niveles se restringen de forma distinta porque sirven a lectores distintos: el nombre del bundle es un identificador que citan otras entidades, y los nombres de archivo son los que un consumidor ve dentro del directorio en el que se importa el bundle.
Referenciar entradas de biblioteca
Los autores de Recipe y FeatureRecipe referencian un bundle dentro de una entrada artifacts: cuyo valor es un mapa $import:, mediante la identidad del bundle como nombre simple:
# Inside a Recipe's spec:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport"El fragmento #/artifacts/<name> selecciona el bundle y distingue una referencia de artefactos de #/mappings/<name> de la MappingLibrary, de #/schemas/<name> de la SchemaLibrary y de #/workloads/<name> de la WorkloadLibrary. La referencia no lleva ningún host de registro; una forma con host oci://… se rechaza tanto en el esquema del envoltorio como en el punto de consumo, de modo que una ubicación física de registro nunca entra en el código fuente escrito. Un autor puede indicar un mínimo de versión opcional como <Library>:<version>#/artifacts/<name> — el separador de versión es :, igual que en los demás tipos de biblioteca y en el pin del lockfile, y escribir @ en su lugar se rechaza con un diagnóstico que nombra la referencia corregida. La versión resuelta la proporciona el lockfile de cada Release, que fija cada biblioteca consumida por nombre, versión y digest del contenido; la ubicación física se vincula en el momento de la resolución.
El bundle es dueño de sus nombres de archivo, y la clave consumidora es dueña del directorio en el que acaban. Una entrada artifacts: que importa un bundle se expande en una salida por cada archivo de ese bundle, cada una anidada bajo la clave de consumo como <key>/<filename>. La clave en el punto de consumo — operator-support arriba — nombra el consumo completo en lugar de un archivo individual; el ejemplo emite operator-support/crd.yaml y operator-support/rbac.yaml. Así, el nombre de un bundle se elige por su legibilidad en la referencia, los nombres de archivo se eligen para quien lee el directorio de salida, y ninguno tiene que coincidir con el otro. La clave de consumo está a su vez limitada a un único nombre de archivo — una letra o un dígito inicial, y luego letras, dígitos, puntos, guiones y guiones bajos, y una clave fuera de ese alfabeto no supera la validación del envoltorio — de modo que nombra exactamente un segmento de directorio, y todo lo que hay bajo ese segmento procede del bundle. Eso es lo que permite que los nombres de archivo de un bundle sean libres mientras la clave sigue siendo estricta: un nombre de archivo es único dentro de su bundle, una clave es única dentro de su documento, y la clave es el primer segmento de cada ruta que emite la entrada, de modo que dos entradas artifacts: nunca nombran la misma salida. Libre significa libre dentro de ese segmento: un nombre de archivo puede tener su propia estructura anidada — crds/widget.yaml acaba en <key>/crds/widget.yaml — pero debe ser un nombre de archivo relativo ordinario bajo la clave, escrito de forma simple, y un nombre de archivo que no lo sea detiene el build en lugar de colocar el archivo en un lugar que la Recipe consumidora nunca nombró. Eso rechaza un nombre que sube por encima de la clave o que nombra una ubicación absoluta; . o ./, y un nombre que vuelve a coincidir con la clave como x/.., que nombran el propio directorio de la clave en lugar de un archivo dentro de él; y un nombre con una / final o doble, o con una parte . o .. — x/, a//b, ./a, a/../b — que es una segunda grafía de un archivo que otro nombre puede llevar, de modo que a//b junto a a/b pondría dos archivos en una misma ruta. El diagnóstico nombra el archivo del bundle y la clave en la que se importó. Dos salidas que efectivamente llevan el mismo nombre de archivo detienen el build cuando se renderiza el nodo, lo que ocurre cuando dos tipos de entrada distintos aportan un mismo nombre de archivo. Consulta Recipe para ver cómo se compone artifacts: con los demás tipos de entrada de la Recipe y los dos modos de autoría que no usan bibliotecas, y vocabulary/cross-document-ref para la distinción más amplia entre $ref: / $import:.
Composición entre bibliotecas
El cuerpo de un archivo de bundle es contenido terminal. A diferencia de una entrada de MappingLibrary o de WorkloadLibrary, un archivo de bundle no puede ser una redirección $import: en la raíz del campo: un único hueco de archivo no tiene espacio para los varios archivos que traería otro bundle, así que el compilador rechaza esa forma en lugar de resolverla en algo que el autor no escribió. Un cuerpo cuyo primer token es $import: se detiene con un diagnóstico que nombra el bundle y el archivo.
En su lugar, la composición ocurre en el punto de consumo, donde hay espacio para ella. Una Recipe que necesita dos bundles declara dos entradas artifacts:, y cada una se expande de forma independiente:
# Inside a Recipe's spec — compose bundles where the outputs land:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport" network-baseline: $import: "PlatformArtifacts#/artifacts/NetworkBaseline"Un nombre de biblioteca desconocido y un nombre de bundle ausente de una biblioteca que sí se resuelve se notifican como diagnósticos distintos, de modo que un autor puede distinguir una dependencia que falta de un nombre de bundle mal escrito.
Ubicación en los tiers
La ArtifactLibrary es de Tier 3 en el modelo de documentación por tiers de las entidades — opcional para los catálogos que necesitan reutilizar artefactos entre Recipes. Los catálogos cuyas Recipes llevan sus propios archivos auxiliares se distribuyen sin ninguna entidad ArtifactLibrary; la marca de tier indica «avanzado; omítelo si no lo necesitas» para la navegación por la documentación, no una capacidad. El compilador trata la ArtifactLibrary de forma uniforme con los demás tipos de entidad de catálogo: la misma validación del envoltorio al cargar el espacio de trabajo, el mismo pipeline de publicación OCI en el momento de la publicación, el mismo pin en el lockfile por nombre, versión y digest del contenido.
Este tipo de biblioteca completa un conjunto a nivel de catálogo — la SchemaLibrary contiene definiciones de esquema reutilizables, la MappingLibrary fragmentos de mapeo reutilizables, la WorkloadLibrary contenido de workload reutilizable y la ArtifactLibrary bundles de artefactos reutilizables. Cada una es opcional de forma independiente; los catálogos distribuyen las que necesitan y ninguna de las demás.
Lo que la ArtifactLibrary no es
Algunos malentendidos habituales que conviene evitar:
-
No sustituye a
artifacts:en línea. La mayoría de las Recipes llevan archivos auxiliares lo bastante específicos como para estar en línea, donde el autor los lee junto con el resto de la Recipe. Una ArtifactLibrary ayuda cuando el MISMO conjunto de archivos acompaña a muchas Recipes; para contenido puntual, la escritura en línea es la opción adecuada. -
No es una forma de renombrar los archivos dentro de un bundle. Los nombres de archivo pertenecen al bundle. Un consumidor elige el directorio en el que acaban — eso es lo que hace la clave de consumo — pero no cómo se llama cada uno: un consumidor que necesita un nombre de archivo distinto usa un bundle que lo declare o escribe el archivo en línea.
-
No es un lugar para contenido de workload, de mapeo o de esquema. Un documento Workload pertenece a una WorkloadLibrary, el documento de valores de una Recipe pertenece a una MappingLibrary y las definiciones de esquema pertenecen a una SchemaLibrary. Los tipos de biblioteca se dividen por tipo de contenido, no por patrón de reutilización.
-
No es el mecanismo para recursos transversales. Los recursos auxiliares que se aplican a muchos componentes independientemente de qué Recipe los realice — un sidecar de copia de seguridad vinculado a cada almacén de datos — corresponden a la generación de recursos de la FeatureRecipe, que se vincula por Feature en lugar de por Recipe. Consulta entities/featurerecipe.md. Una ArtifactLibrary agrupa archivos que varias Recipes emiten cada una por su cuenta.
-
No es una entidad desplegable de forma independiente. Un bundle es contenido de artefactos, y el contenido de artefactos nunca es direccionable por sí solo — existe como la entrada que consume una Recipe o una FeatureRecipe. Publicar una ArtifactLibrary hace que sus bundles sean importables; no los hace desplegables.