Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

ArtifactLibrary

Une ArtifactLibrary est une entité de catalogue qui contient des bundles d’artefacts réutilisables — des ensembles nommés de fichiers de sortie auxiliaires qui vont ensemble. Les Recipes et FeatureRecipes qui émettent les mêmes ressources d’appui — une CRD avec son RBAC et une ConfigMap, une NetworkPolicy associée à un HPA — déclarent cet ensemble une seule fois dans une bibliothèque et y font référence au moment de la consommation via une entrée artifacts: dont la valeur est une directive $import:. L’entité bibliothèque relève du Tier 3 : facultative, pour les catalogues qui ont besoin de réutiliser des artefacts entre Recipes. Les catalogues dont chaque Recipe porte ses propres fichiers auxiliaires sont livrés sans aucune ArtifactLibrary.

Le rôle de l’ArtifactLibrary

Les architectes de plateforme rédigent des ArtifactLibraries pour centraliser les manifestes auxiliaires récurrents dans les Recipes et FeatureRecipes du catalogue. Une bibliothèque n’est pas une instruction de build déployable ; c’est un espace de noms de définitions. Les auteurs de Recipe et de FeatureRecipe font référence à un bundle par une directive $import:, écrite une fois et consommée partout où l’import est résolu.

Ce qui distingue ce type de bibliothèque des trois autres, c’est la granularité d’une entrée. Une entrée de SchemaLibrary est un schéma, une entrée de MappingLibrary est un fragment de template et une entrée de WorkloadLibrary est un document Workload — chacune un corps unique consommé en un seul endroit. Une entrée d’ArtifactLibrary est un ensemble de fichiers, car les ressources qu’elle regroupe ne sont utiles qu’ensemble : importer une CRD sans son RBAC produit un ensemble de manifestes qui ne fonctionne pas. C’est pourquoi un bundle est l’unité de réutilisation et qu’un seul point de consommation se développe en plusieurs sorties.

Enveloppe de l’entité

Une entité ArtifactLibrary porte l’enveloppe standard du catalogue. apiVersion: aggrega.ai/v1beta1 et kind: ArtifactLibrary indiquent le type d’entité ; metadata.name est un identifiant en PascalCase ; metadata.version suit un versionnage sémantique strict. Tous deux sont obligatoires. metadata.description, metadata.labels et metadata.annotations sont facultatifs — les labels et les annotations sont des métadonnées opaques déclarées par l’auteur, portées pour que tout ce qui lit la bibliothèque puisse s’y appuyer pour la correspondance, et le compilateur n’interprète pas leurs valeurs. Le contenu de la bibliothèque se trouve sous spec.artifacts, une map obligatoire qui doit déclarer au moins un bundle.

L’enveloppe est fermée aux trois niveaux — la racine du document, metadata et spec rejettent chacun les clés que le schéma ne déclare pas.

apiVersion: aggrega.ai/v1beta1
kind: ArtifactLibrary
metadata:
name: PlatformArtifacts
version: 1.0.0
spec:
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"]

Rédiger des bundles d’artefacts

spec.artifacts a deux niveaux de profondeur, et chaque niveau a un rôle distinct. La clé externe est le nom du bundle — l’identifiant auquel un consommateur fait référence. Les clés internes sont des noms de fichiers, et chaque valeur interne est le corps en Go template émis dans ce fichier. Un bundle doit déclarer au moins un fichier.

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"

Le corps d’un fichier est un fragment de Go template rédigé sous forme de chaîne YAML. Comme un manifeste tient sur plusieurs lignes, les corps de fichiers utilisent le scalaire de style littéral de YAML (|) afin que les sauts de ligne et l’indentation survivent à l’aller-retour. La valeur d’une entrée de bundle doit être un mappage de nom de fichier vers un corps de type chaîne ; écrire une simple chaîne là où le bundle est attendu, ou une séquence, est rejeté — le niveau qu’un consommateur importe est le bundle, et non un fichier isolé.

Le corps est opaque pour l’enveloppe de l’entité. Le compilateur stocke chaque chaîne telle quelle au chargement de l’ArtifactLibrary et n’y analyse pas le template ; l’analyseur de templates s’exécute au moment de la consommation, lorsqu’une Recipe ou une FeatureRecipe importe le bundle. Stocker les corps tels quels préserve la fidélité à la rédaction pour la réémission, et fait qu’une erreur de template apparaît là où le bundle est consommé et où son contexte de piliers est connu, plutôt qu’au niveau de la bibliothèque.

L’ordre des fichiers dans un bundle est celui dans lequel l’auteur les a écrits, préservé au chargement et à la consommation, de sorte que l’ensemble émis est stable d’un build à l’autre.

Tout le vocabulaire de composition de Go template est disponible dans le corps d’un fichier : {{ define "name" }}...{{ end }} déclare des blocs réutilisables, {{ template "name" . }} les invoque, et les pipelines et les fonctions suivent le paquet Go standard text/template. Le contexte de piliers que le corps d’un fichier peut lire — .values, .infra, .locals, .context, .features, ainsi que .workload et .source lorsque la Recipe consommatrice les déclare — est le contexte que lisent les propres entrées artifacts: de la Recipe consommatrice, documenté sur la page Recipe sous le champ artifacts:. Un corps qui lit .workload alors que la Recipe consommatrice ne déclare aucun workload:, ou .source alors qu’elle ne déclare aucun source:, s’arrête avec un diagnostic nommant la référence qu’il n’a pas pu satisfaire — chaque pilier est vérifié séparément, de sorte que déclarer l’un n’autorise pas à lire l’autre.

Un mode de rédaction unique

L’ArtifactLibrary propose un seul mode de rédaction : les Go templates. spec n’accepte aucune surface de rédaction parallèle ni aucune porte de sortie d’expressivité au niveau de la bibliothèque.

La raison en est l’uniformité de la surface de consommation. Les Recipes et FeatureRecipes sont entièrement en Go template, et leur propre contenu est évalué par le même moteur Go template qui résout un bundle importé. Une surface de rédaction parallèle obligerait les auteurs à changer de modèle d’évaluation au sein du rendu d’une même Recipe — un modèle pour le contenu propre de la Recipe, un autre pour chaque bundle importé. Garder la surface uniforme signifie que les auteurs apprennent un seul modèle d’évaluation et l’appliquent partout.

Les auteurs qui ont besoin d’une expressivité dépassant le vocabulaire de composition de Go template composent à un niveau supérieur — des Components ou des Features qui enveloppent les bundles de la bibliothèque avec leur propre variation substantielle — plutôt que de passer à un second langage de rédaction au sein de la bibliothèque.

Conventions de nommage

Les noms de bibliothèques et de bundles suivent le PascalCase. Le JSON Schema de l’enveloppe de l’entité impose la convention à deux endroits au moyen de contraintes de motif :

  • metadata.name correspond à ^[A-Z][A-Za-z0-9]*$.
  • Les clés de la map spec.artifacts correspondent au même motif via propertyNames.

Une ArtifactLibrary dont un nom de bundle n’est pas en PascalCase échoue à la validation de l’enveloppe au chargement de l’espace de travail. Cette contrainte est structurante : les noms de bundles apparaissent dans le fragment de référence #/artifacts/<name>, de sorte qu’un nom qui n’est pas en PascalCase se propagerait à chaque consommateur qui importe le bundle.

L’uniformité des noms garde le fragment #/artifacts/<name> lisible : #/artifacts/OperatorSupport se lit d’un coup d’œil.

Les noms de fichiers à l’intérieur d’un bundle sont libres, pourvu que chacun nomme un fichier. Ils ne sont pas en PascalCase et aucun motif de schéma ne les contraint, car ils nomment les fichiers que la sortie d’un build finit par contenir — crd.yaml, deny-all.yaml, values-override.json sont tous valides. Ce qu’un nom de fichier doit être, c’est un nom de fichier relatif ordinaire, écrit simplement ; le build refuse un nom qui ne désigne aucun fichier propre, comme le décrit Faire référence aux entrées de bibliothèque. Les deux niveaux sont contraints différemment parce qu’ils servent des lecteurs différents : le nom du bundle est un identifiant que d’autres entités citent, et les noms de fichiers sont ceux qu’un consommateur voit dans le répertoire où le bundle est importé.

Faire référence aux entrées de bibliothèque

Les auteurs de Recipe et de FeatureRecipe font référence à un bundle à l’intérieur d’une entrée artifacts: dont la valeur est une map $import:, par l’identité du bundle sous forme de nom simple :

# Inside a Recipe's spec:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"

Le fragment #/artifacts/<name> sélectionne le bundle et distingue une référence d’artefacts de #/mappings/<name> de la MappingLibrary, de #/schemas/<name> de la SchemaLibrary et de #/workloads/<name> de la WorkloadLibrary. La référence ne porte aucun hôte de registre ; une forme avec hôte oci://… est rejetée à la fois par le schéma de l’enveloppe et au point de consommation, de sorte qu’un emplacement physique de registre n’entre jamais dans la source rédigée. Un auteur peut indiquer un plancher de version minimale facultatif sous la forme <Library>:<version>#/artifacts/<name> — le séparateur de version est :, comme pour les autres types de bibliothèques et l’épinglage du lockfile, et écrire @ à la place est refusé avec un diagnostic nommant la référence corrigée. La version résolue est fournie par le lockfile propre à chaque Release, qui épingle chaque bibliothèque consommée par nom, version et empreinte du contenu ; l’emplacement physique est lié au moment de la résolution.

Le bundle possède ses noms de fichiers, et la clé consommatrice possède le répertoire où ils arrivent. Une entrée artifacts: qui importe un bundle se développe en une sortie par fichier de ce bundle, chacune imbriquée sous la clé de consommation sous la forme <key>/<filename>. La clé au point de consommation — operator-support ci-dessus — nomme la consommation entière plutôt qu’un fichier isolé ; l’exemple émet operator-support/crd.yaml et operator-support/rbac.yaml. Ainsi, le nom d’un bundle est choisi pour la lisibilité de la référence, les noms de fichiers pour le lecteur du répertoire de sortie, et aucun n’a à concorder avec l’autre. La clé de consommation est elle-même limitée à un seul nom de fichier — une lettre ou un chiffre en tête, puis des lettres, chiffres, points, tirets et tirets bas, une clé hors de cet alphabet échouant à la validation de l’enveloppe — de sorte qu’elle nomme exactement un segment de répertoire, et tout ce qui se trouve sous ce segment provient du bundle. C’est ce qui permet aux noms de fichiers d’un bundle de rester libres tandis que la clé reste stricte : un nom de fichier est unique au sein de son bundle, une clé est unique au sein de son document, et la clé est le premier segment de chaque chemin que l’entrée émet, de sorte que deux entrées artifacts: ne nomment jamais la même sortie. Libre signifie libre au sein de ce segment : un nom de fichier peut avoir sa propre arborescence — crds/widget.yaml arrive dans <key>/crds/widget.yaml — mais il doit être un nom de fichier relatif ordinaire sous la clé, écrit simplement, et un nom de fichier qui ne l’est pas arrête le build au lieu de placer le fichier à un endroit que la Recipe consommatrice n’a jamais nommé. Cela refuse un nom qui remonte au-dessus de la clé ou qui désigne un emplacement absolu ; . ou ./, ainsi qu’un nom qui se ramène à la clé comme x/.., qui désignent le répertoire de la clé lui-même plutôt qu’un fichier qu’il contient ; et un nom avec un / final ou doublé ou une partie . ou .. — x/, a//b, ./a, a/../b — qui est une seconde graphie d’un fichier qu’un autre nom peut porter, si bien que a//b à côté de a/b placerait deux fichiers sur un même chemin. Le diagnostic nomme le fichier du bundle et la clé sous laquelle il a été importé. Deux sorties qui portent effectivement le même nom de fichier arrêtent le build lors du rendu du nœud, ce qui se produit lorsque deux types d’entrée différents apportent un même nom de fichier. Voir Recipe pour la façon dont artifacts: se compose avec les autres types d’entrée de la Recipe et pour les deux modes de rédaction sans bibliothèque, et vocabulary/cross-document-ref pour la distinction plus large entre $ref: / $import:.

Composition entre bibliothèques

Le corps d’un fichier de bundle est un contenu terminal. Contrairement à une entrée de MappingLibrary ou de WorkloadLibrary, un fichier de bundle ne peut pas être une redirection $import: à la racine du champ : un emplacement de fichier unique n’a pas la place pour les plusieurs fichiers qu’apporterait un autre bundle, si bien que le compilateur rejette cette forme plutôt que de la résoudre en quelque chose que l’auteur n’a pas écrit. Un corps dont le premier jeton est $import: s’arrête avec un diagnostic nommant le bundle et le fichier.

La composition se fait plutôt au point de consommation, où il y a la place pour elle. Une Recipe qui a besoin de deux bundles déclare deux entrées artifacts:, et chacune se développe indépendamment :

# 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 nom de bibliothèque inconnu et un nom de bundle absent d’une bibliothèque qui, elle, est résolue sont signalés par des diagnostics distincts, de sorte qu’un auteur peut distinguer une dépendance manquante d’un nom de bundle mal orthographié.

Placement dans les tiers

L’ArtifactLibrary relève du Tier 3 dans le modèle de documentation par tiers des entités — facultative pour les catalogues qui ont besoin de réutiliser des artefacts entre Recipes. Les catalogues dont les Recipes portent leurs propres fichiers auxiliaires sont livrés sans aucune entité ArtifactLibrary ; le marquage de tier signale « avancé ; à ignorer si inutile » pour la navigation dans la documentation, et non une capacité. Le compilateur traite l’ArtifactLibrary de façon uniforme avec les autres types d’entités de catalogue : même validation de l’enveloppe au chargement de l’espace de travail, même pipeline de publication OCI au moment de la publication, même épinglage dans le lockfile par nom, version et empreinte du contenu.

Ce type de bibliothèque complète un ensemble au niveau du catalogue — la SchemaLibrary contient des définitions de schéma réutilisables, la MappingLibrary des fragments de mapping réutilisables, la WorkloadLibrary du contenu de workload réutilisable et l’ArtifactLibrary des bundles d’artefacts réutilisables. Chacune est facultative indépendamment ; les catalogues livrent celles dont ils ont besoin et aucune des autres.

Ce que l’ArtifactLibrary n’est pas

Quelques idées reçues courantes à écarter :

  • Pas un substitut aux artifacts: en ligne. La plupart des Recipes portent des fichiers auxiliaires suffisamment spécifiques pour rester en ligne, là où l’auteur les lit avec le reste de la Recipe. Une ArtifactLibrary est utile lorsque le MÊME ensemble de fichiers accompagne de nombreuses Recipes ; pour un contenu ponctuel, la rédaction en ligne est le bon choix.

  • Pas un moyen de renommer les fichiers à l’intérieur d’un bundle. Les noms de fichiers appartiennent au bundle. Un consommateur choisit le répertoire où ils arrivent — c’est le rôle de la clé de consommation — mais pas le nom de chacun d’eux : un consommateur qui a besoin d’un autre nom de fichier utilise un bundle qui le déclare ou rédige le fichier en ligne.

  • Pas un emplacement pour du contenu de workload, de mapping ou de schéma. Un document Workload a sa place dans une WorkloadLibrary, le document de valeurs d’une Recipe dans une MappingLibrary, et les définitions de schéma dans une SchemaLibrary. Les types de bibliothèques se répartissent par type de contenu, et non par modèle de réutilisation.

  • Pas le mécanisme des ressources transversales. Les ressources auxiliaires qui s’appliquent à de nombreux composants quelle que soit la Recipe qui les réalise — un sidecar de sauvegarde rattaché à chaque datastore — relèvent de la génération de ressources de la FeatureRecipe, qui se rattache par Feature plutôt que par Recipe. Voir entities/featurerecipe.md. Une ArtifactLibrary factorise des fichiers que plusieurs Recipes émettent chacune pour leur propre compte.

  • Pas une entité déployable indépendamment. Un bundle est du contenu d’artefacts, et le contenu d’artefacts n’est jamais adressable seul — il existe en tant qu’entrée qu’une Recipe ou une FeatureRecipe consomme. Publier une ArtifactLibrary rend ses bundles importables ; cela ne les rend pas déployables.