WorkloadLibrary
Una WorkloadLibrary es una entidad de catálogo que contiene fragmentos de plantilla de Workload reutilizables. Las Recipes y las FeatureRecipes que despliegan la misma forma de carga de trabajo (un servidor que expone métricas, un trabajo por lotes, un par con sidecar) declaran esa forma una sola vez en una biblioteca y hacen referencia a ella en el momento del consumo mediante una directiva workload: { $import: ... }. La entidad de biblioteca es de nivel 3: opcional para los catálogos que necesitan reutilizar cargas de trabajo entre una Recipe y otra. Los catálogos cuyas Recipes llevan cada una su propia forma de carga de trabajo distinta se distribuyen sin ninguna WorkloadLibrary.
La función de la WorkloadLibrary
Los arquitectos de plataforma escriben WorkloadLibraries para centralizar el contenido de Workload que se repite en las Recipes y las FeatureRecipes del catálogo. Una biblioteca no es una instrucción de compilación desplegable; es un espacio de nombres de definiciones. Los autores de Recipe y de 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 compilación (source, valuesMapping, artifacts). Las FeatureRecipes codifican vinculaciones de comportamiento. Las WorkloadLibraries codifican solo contenido de Workload: la forma de la carga de trabajo que el proveedor sintetiza en manifiestos nativos del proveedor. Mantener separados los tres roles permite que cada tipo de entidad evolucione a su propio ritmo; los autores que no necesitan contenido de carga de trabajo compartido nunca se encuentran con la entidad de biblioteca.
Envoltorio de la entidad
Una entidad WorkloadLibrary lleva el sobre de catálogo estándar. apiVersion: aggrega.ai/v1beta1 y kind: WorkloadLibrary 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 transportan para que lo que lea la biblioteca pueda usarlos para establecer coincidencias, y el compilador no interpreta sus valores. El contenido de la biblioteca está en spec.workloads, un mapa obligatorio que debe declarar al menos una entrada.
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: WorkloadLibrarymetadata: name: BaseWorkloads version: 1.0.0spec: workloads: SimpleServer: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }}Escribir entradas Workload
Cada entrada es un fragmento de plantilla de Go escrito como cadena YAML. La salida renderizada de la entrada es un documento Workload completo — lleva sus propios apiVersion: aggrega.ai/v1beta1 y kind: Workload — porque el campo workload: de una Recipe admite un Workload completo, no un fragmento insertado en otro que lo rodea, y la importación reemplaza el campo entero. Una entrada de MappingLibrary es completa del mismo modo: importar una reemplaza todo el valuesMapping: de la Recipe.
El cuerpo es opaco para el envoltorio de la entidad. El compilador almacena la cadena textualmente al cargar la WorkloadLibrary y no analiza la plantilla en ese momento; el analizador de plantillas se ejecuta en el momento del consumo, cuando una Recipe o una FeatureRecipe importa la entrada. Almacenar el fragmento textualmente preserva la fidelidad de la autoría para la reemisión, y hace que un error de plantilla aparezca donde se consume la entrada y se conoce su contexto de pilares, y no en la biblioteca.
Como un documento Workload ocupa varias líneas, las entradas usan el escalar de estilo literal de YAML (|) para que los saltos de línea y la sangría sobrevivan al viaje de ida y vuelta:
spec: workloads: BatchJob: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: task containers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"]El valor de una entrada debe ser un escalar de cadena. Escribir un mapa o una secuencia donde va el cuerpo se rechaza — el cuerpo de la entrada es texto de plantilla, no YAML estructurado que el compilador recorra.
Dentro de una entrada está disponible todo el vocabulario de composición de las plantillas de Go: {{ define "name" }}...{{ end }} declara bloques reutilizables dentro de una única biblioteca, {{ template "name" . }} los invoca, y las canalizaciones y funciones siguen el paquete estándar de Go text/template. El contexto de pilares que una entrada puede leer — .values, .infra, .locals, .context, .features — es el mismo contexto que lee cualquier plantilla de Workload, y está documentado en la página Workload, en la sección sobre la evaluación de plantillas.
El proveedor de destino debe admitir la síntesis de carga de trabajo. Una Recipe que importa una entrada de biblioteca pero se vincula a un proveedor que no puede sintetizar un Workload se detiene con un error explícito en el momento del renderizado, en lugar de emitir una forma degradada; el catálogo de la biblioteca estándar declara workloadSchema en los proveedores que sí la admiten, como contrato documentado.
Un único modo de autoría
La WorkloadLibrary se ofrece con un único modo de autoría: las plantillas de Go. 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 las FeatureRecipes son plantillas de Go de principio a fin, y su propio contenido se evalúa con el mismo motor de plantillas de Go que resuelve un fragmento 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, otro para cada entrada de biblioteca importada. Mantener la superficie uniforme significa que los autores aprenden un solo modelo de evaluación y lo aplican en todas partes.
Los autores que necesitan más expresividad de la que ofrece el vocabulario de composición de las plantillas de 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 recurrir a un segundo lenguaje de autoría dentro de la biblioteca.
Convenciones de nomenclatura
Los nombres de biblioteca y las claves de las entradas de carga de trabajo siguen PascalCase. El JSON Schema del envoltorio de la entidad impone 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.workloadscoinciden con el mismo patrón mediantepropertyNames.
Una WorkloadLibrary con una clave que no está en PascalCase en spec.workloads no supera la validación del envoltorio al cargar el espacio de trabajo. La aplicación es esencial: las claves de las entradas de carga de trabajo aparecen en el fragmento de referencia #/workloads/<name>, de modo que una clave que no esté en PascalCase se propagaría a cada consumidor que importe la entrada.
La uniformidad de los nombres mantiene legible el fragmento #/workloads/<name>: #/workloads/BatchJob se entiende de un vistazo.
Referenciar entradas de biblioteca
Los autores de Recipe y FeatureRecipe hacen referencia a una entrada de carga de trabajo dentro de un bloque workload: { $import: ... } mediante su identidad de nombre simple:
# Inside a Recipe's spec:spec: workload: $import: "BaseWorkloads#/workloads/SimpleServer"El fragmento #/workloads/<name> selecciona la entrada y distingue una referencia de carga de trabajo del #/mappings/<name> de MappingLibrary y del #/schemas/<name> de SchemaLibrary. La referencia no lleva ningún host de registro; una forma oci://… que incluye un host 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 declarar un mínimo de versión opcional como <Library>:<version>#/workloads/<name> — el separador de versión es :, igual que en los mapeos de recipe/feature y en el pin del lockfile, y escribir @ en su lugar se rechaza con un diagnóstico que indica 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 mismo campo workload: admite otras dos formas — una cadena de plantilla de Go en línea y un $import: de una ruta de archivo local relativa al directorio de la Recipe. Las tres formas se distinguen por la forma del contenido, y las tres producen el mismo Workload tras el análisis. Consulta Recipe para ver cómo se compone workload: con los demás tipos de entrada de la Recipe, y vocabulary/cross-document-ref para la distinción más amplia $ref: / $import:.
Composición entre bibliotecas
Una entrada de WorkloadLibrary puede ser una redirección $import: en la raíz del campo: el primer token de su cuerpo es $import: <Library>#/workloads/<entry>, que reemplaza la entrada entera por el contenido de la entrada referenciada — reutilización por identidad, no plantillas aplicadas in situ. La redirección se resuelve en el momento del consumo, no al cargar la WorkloadLibrary, y se resuelve de forma recursiva, de modo que una entrada importada puede ser a su vez un $import: en la raíz del campo. Una cadena que vuelve sobre sí misma se detiene con un diagnóstico que indica el ciclo. $import: solo se aplica a la entrada entera; no es una función de plantilla para usar a mitad de un fragmento. Para componer texto de plantilla dentro de una sola entrada, usa define / template de las plantillas de Go.
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServerUn nombre de biblioteca desconocido y un nombre de entrada ausente de una biblioteca que sí se resuelve se notifican como diagnósticos distintos, para que un autor pueda distinguir una dependencia que falta de una entrada mal escrita.
Ubicación en los tiers
La WorkloadLibrary es de nivel 3 en el modelo de documentación por niveles de entidades — opcional para los catálogos que necesitan reutilizar cargas de trabajo entre una Recipe y otra. Los catálogos cuyas Recipes llevan su propio contenido de carga de trabajo distinto se distribuyen sin ninguna entidad WorkloadLibrary; la marca de nivel indica «avanzado; omítelo si no lo necesitas» para la navegación por la documentación, no para la capacidad. El compilador trata la WorkloadLibrary de forma uniforme con los demás tipos de entidades del catálogo: la misma validación del envoltorio al cargar el espacio de trabajo, el mismo pipeline de publicación OCI al publicar una versión, el mismo anclaje en el lockfile por nombre, versión y digest del contenido.
El tipo de biblioteca es uno de un conjunto a nivel de catálogo — SchemaLibrary contiene definiciones de esquema reutilizables, MappingLibrary fragmentos de mapeo reutilizables, ArtifactLibrary paquetes de artefactos reutilizables, WorkloadLibrary contenido de carga de trabajo reutilizable. Cada uno es opcional de forma independiente; los catálogos incluyen los que necesitan y ninguno de los demás.
Lo que la WorkloadLibrary no es
Algunos malentendidos habituales que conviene evitar:
-
No sustituye al
workload:en línea. La mayoría de las Recipes llevan contenido de carga de trabajo lo bastante específico como para ir en línea, donde el autor lo lee junto con el resto de la Recipe. Una WorkloadLibrary ayuda cuando la MISMA forma de carga de trabajo aparece en muchas Recipes; para contenido puntual, la autoría en línea es la opción correcta. -
No es un lugar para fragmentos parciales. Una entrada se renderiza como un documento Workload completo. El documento de valores de una Recipe va en una MappingLibrary, un conjunto de archivos auxiliares en una ArtifactLibrary y las definiciones de esquema en una SchemaLibrary. Los tipos de biblioteca se dividen por tipo de contenido, no por patrón de reutilización.
-
No es una entidad desplegable de forma independiente. Una entrada de biblioteca es contenido Workload, y el contenido Workload nunca es direccionable por sí solo — existe como los datos de entrada que consume una Recipe o una FeatureRecipe. Publicar una WorkloadLibrary hace que sus entradas sean importables; no las hace desplegables.
-
No es reutilización paramétrica más allá de los mecanismos de las plantillas de Go. Los autores que necesitan variación paramétrica usan los mecanismos
{{ define }}+{{ template }}de las plantillas de Go dentro de las entradas de biblioteca, o el contexto de pilares que aporta la Recipe consumidora. La propia entidad de biblioteca no incluye ninguna maquinaria de ayudantes paramétricos.