Stack Harbor — un registre de conteneurs déployé comme une seule release
Cet exemple compile un véritable registre de conteneurs en manifestes Kubernetes à partir d’un seul Aggregate écrit par le développeur.
Un registre de conteneurs se compose de nombreux services qui coopèrent — un plan de contrôle composé de l’API et du service de jetons, un magasin de blobs OCI et son contrôleur, une console web, un niveau de workers asynchrones, un scanner de vulnérabilités, un backend relationnel, un cache clé-valeur et un reverse proxy placé devant eux. Le catalogue décrit tout cela comme un seul Component, car les mainteneurs du registre eux-mêmes publient un chart Helm qui le déploie en entier comme une seule release, dans l’ordre dont ses services ont besoin. Le Component déclare le registre ; la Recipe encapsule ce chart.
Le registre est importé comme un module : un sous-agrégat réutilisable qui compose le Component et exporte son adresse publiée. L’Aggregate de plus haut niveau importe le module par son nom et lui transmet trois des clés du registre ; l’opérateur dimensionne le composant du module dans la Release.
Fichiers
| Fichier | Rôle |
|---|---|
aggregate.yaml | Intention du développeur : importe le module de registre de conteneurs (core/harbor) et lui transmet trois des clés du registre depuis des paramètres qui lui sont propres. |
manifest-helm-synth.yaml | Associe le type de composant du registre à la Recipe qui encapsule son chart Helm, et la Feature d’informations d’identification à la réalisation qui lit un Secret déjà présent dans le namespace — sauf le mot de passe de l’administrateur, qu’il lie par son nom à la réalisation qui émet un Secret à partir du paramètre du module. |
release-helm-synth.yaml | Enregistrement de l’opérateur pour la cible Kubernetes. Nomme les Secrets contenant les trois clés que l’Aggregate transmet vers le bas, dimensionne le composant du module par son ID à portée de module, et lui rattache la clé de signature des jetons, le secret partagé des services et la clé avec laquelle les informations d’identification stockées sont chiffrées, en nommant les Secrets qui les contiennent ; tout le reste est laissé aux valeurs par défaut du schéma. |
Ce qu’il démontre
- Un produit multiservice comme un seul Component. Ce qui fait du registre un seul Component plutôt que plusieurs n’est pas sa taille, mais l’endroit où son câblage est maintenu : le routage du reverse proxy, la clé du service de jetons par rapport à laquelle le plan de contrôle vérifie chaque pull et chaque push, les paramètres de connexion que chaque service lit pour le backend et le cache, la répartition en bases de données logiques qui sépare les espaces de clés du cache des services, et l’ordre de démarrage — tout cela est maintenu en phase avec le produit par les personnes qui le livrent, dans le chart. Un consommateur déclare un registre et obtient tous ces éléments en accord.
- Un chart encapsulé. La Recipe nomme le chart dans
source:et y superpose unvaluesMapping:— le modèle de valeurs constitue toute l’implémentation, et le fournisseur Helm rend les modèles propres au chart par rapport à lui. Aucune charge de travail n’est synthétisée ici. - Une entrée externe épinglée. Le chart est une entrée que le build récupère, il est donc épinglé comme toute dépendance : le fichier de verrouillage enregistre la version du chart, son URL résolue et le digest de l’archive tar, sous
source_artifacts. Un build sur un fichier de verrouillage rempli sert le chart depuis le magasin de contenu et le vérifie par rapport à ce digest. - Une seule adresse publiée pour toute une plateforme. Le reverse proxy du chart route le chemin de navigateur
/vers la console et les chemins du registre et de l’API (/v2/,/api/,/service/,/c/) vers le plan de contrôle, si bien qu’un client de conteneurs s’authentifie et effectue ses push et ses pull sur le même hôte que celui par lequel un navigateur atteint la console. Ce Service est ce queprovides.hostpublie, et un consommateur n’a besoin d’aucune seconde adresse pour atteindre l’un ou l’autre ensemble de chemins. - Deux noms publics pour elle. Le module exporte cette adresse unique sous le nom
registry, l’endpoint auquel s’adressent les clients d’images et l’API, et sous le nomui, l’endpoint web. Les deux se résolvent vers l’adresse qui sert les deux ensembles de chemins, si bien qu’un consommateur se connecte au nom qui décrit son intention. - Dimensionnement du composant d’un module par l’opérateur. La Release adresse le composant du module par son ID à portée de module (
harbor.registry) pour définir les ressources de calcul, sans que l’Aggregate du développeur ne reprenne le dimensionnement physique. - Règles de complétude sur une valeur groupée.
infra.computeporte une clé de CPU et une clé de mémoire, et la Recipe s’arrête sur un groupe qui laisse l’une ou l’autre vide. Un plan de contrôle rendu avec une limite de CPU et sans limite de mémoire diffère sensiblement de celui que décrivent les valeurs par défaut déclarées du Component, et rien dans la sortie rendue ne le signalerait — le build s’arrête donc et nomme plutôt la clé manquante. Une clé que le groupe omet prend la valeur par défaut du Component. - Six clés sans valeur par défaut. La clé avec laquelle le service de jetons signe les jetons du registre, avec son certificat ; les trois secrets avec lesquels les propres services du registre s’authentifient entre eux et signent l’état des téléversements ; la clé anti-falsification de requêtes ; et la clé avec laquelle le plan de contrôle chiffre les informations d’identification stockées n’ont aucune valeur par défaut : une clé que détiendrait chaque lecteur du catalogue permettrait à n’importe qui d’émettre des jetons auxquels le registre fait confiance ou de lire ce qu’il stocke. Le Component déclare ces slots obligatoires, si bien qu’un build qui en laisse un vide s’arrête et nomme le slot. Le build ne lit aucune des six valeurs et n’en rend aucune : chaque charge de travail lit chacune depuis un Secret qu’elle nomme.
- Trois clés que rattache la Release. Le module ne rattache ni la clé de signature des jetons, ni le secret partagé du plan de contrôle, ni la clé avec laquelle les informations d’identification stockées sont chiffrées, si bien que la Release rattache les trois au composant du module,
token_key,core_secretetsecret_key, chacune viacore/referenced-secretavecinfra.originnommant un Secret, et le Manifest lie la Feature àk8s-existing-secret. Le plan de contrôle monte la clé de signature des jetons et la clé de chiffrement depuis les Secrets qu’elles nomment, et les services lisent le secret partagé depuis le leur. - Des informations d’identification que remplit le module. Le mot de passe du compte administrateur, la clé anti-falsification de requêtes intersites, le secret partagé du niveau des workers et le secret d’état des téléversements du magasin de blobs sont eux aussi des slots d’informations d’identification du Component, et le module remplit chacun depuis un paramètre qui lui est propre (
admin_password,csrf_key,jobservice_secret,registry_http_secret) via la Feature d’informations d’identificationcore/referenced-secret, si bien que chaque charge de travail les lit depuis un Secret par son nom. Comme le module rattache cette Feature, le Manifest la mappe. Les trois clés n’ont pas non plus de valeur par défaut dans le module, si bien que l’Aggregate déclare des paramètres qui lui sont propres et les transmet vers le bas viaaggregates.harbor.parameters, la Release les remplit, etk8s-existing-secretlit chacun comme le nom d’un Secret qui existe déjà dans le namespace ; une Release qui ne fournit aucune valeur arrête le build, en nommant le paramètre. Cet exemple laisse le mot de passe de l’administrateur à la valeur par défaut de développement du module, et le Manifest lie par son nom ce seul rattachement àk8s-secret-from-parameter, qui émet un Secret le contenant. Les mots de passe restants sont écrits dans la configuration que rend la Release, si bien qu’on les remplace plutôt en définissantinfra; non définis, chacun prend une valeur de développement que la Recipe indique. - Une sortie déterministe sur un chart qui générerait sinon du contenu. Livré à lui-même, ce chart génère ses propres secrets lorsqu’aucun n’est fourni — les secrets partagé et de signature des jetons du plan de contrôle, les secrets du niveau des workers et du magasin de blobs, la clé anti-falsification de requêtes, et le mot de passe haché du magasin de blobs, qu’il hache à nouveau avec un sel neuf à chaque rendu. Chacun est fourni à la place : les six clés toujours depuis les Secrets que nomme la Release, et les mots de passe depuis l’information d’identification rattachée par son nom là où un slot est rempli et depuis une valeur de développement fixe là où il ne l’est pas, si bien que deux rendus d’une entrée identique émettent des octets identiques.
- Images reproductibles. Chaque image qu’exécute le registre est épinglée sur un tag explicite. Le produit les livre toutes sous un seul tag, si bien que
infra.engine_versionles sélectionne toutes à la fois ;infra.overrides.imageremplace l’épinglage d’un seul service, etinfra.overrides.image_prefixles déplace ensemble pour une Release qui tire depuis un miroir.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example harbor-stackElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd harbor-stackBuild
Cet espace de travail ne contient aucun .aggrega-config.yaml, si bien que les entités de la bibliothèque standard sont résolues depuis le registre du hub, hub.aggrega.ai, et aucune option de catalogue n’est nécessaire. La Recipe récupère un chart, résolvez donc d’abord les dépendances dans le fichier de verrouillage :
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlLes artefacts rendus atterrissent sous dist/.
Avant de les appliquer, créez les six Secrets que nomme la Release dans le namespace où le registre est déployé : harbor-token-key, contenant une clé privée RSA sous la clé de données tls.key et un certificat sur cette clé sous tls.crt ; harbor-core-secret, contenant un secret de 16 caractères sous la clé de données secret ; harbor-secret-key, contenant une clé de 16 caractères sous secretKey ; harbor-csrf-key, contenant une clé de 32 caractères sous CSRF_KEY ; et harbor-jobservice-secret et harbor-registry-http-secret, contenant un secret de 16 caractères sous JOBSERVICE_SECRET et REGISTRY_HTTP_SECRET. Par exemple :
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \ -keyout tls.key -out tls.crtkubectl create secret tls harbor-token-key --key tls.key --cert tls.crtkubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"Un registre dont les services ne trouvent pas ces Secrets ne démarre pas.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `harbor-stack`, appelez une fois l’outil `scaffold` avec `example` défini sur `harbor-stack` et sans `dir` : il écrit l’exemple dans un nouveau dossier `harbor-stack`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `harbor-stack`, `release` défini sur `release-helm-synth.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi les fichiers écrits par le build ; ils se trouvent sous `harbor-stack/dist/`.À quoi ressemble le registre composé
Le build émet les ressources que le chart définit pour cette configuration : des Deployments pour le reverse proxy, la console, le plan de contrôle, le niveau des workers et le magasin de blobs ; des StatefulSets pour le backend, le cache et le scanner ; des demandes de volume persistant pour le magasin de blobs et pour les journaux du niveau des workers ; les ConfigMaps et les Secrets que lit chaque service ; et les Services placés devant eux. À côté d’eux, la Feature d’informations d’identification émet un Secret, harbor-zdregistry-admin-password, portant la valeur par défaut de développement du module pour le mot de passe de l’administrateur, que le plan de contrôle lit depuis celui-ci plutôt que depuis le Secret propre au chart. Aucun Secret n’est émis pour aucune des six clés : le plan de contrôle monte la clé de signature des jetons depuis harbor-token-key et la clé de chiffrement depuis harbor-secret-key, et les services lisent les autres depuis harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret et harbor-registry-http-secret, les Secrets que nomme la Release.
Exactement un de ces Services est l’adresse à laquelle se connectent les consommateurs — dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml :
apiVersion: v1kind: Servicemetadata: name: harbor-zdregistry [… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]spec: type: ClusterIP ports: - name: http port: 80 targetPort: 8080 selector: release: harbor-zdregistry app: "harbor" component: nginxSon sélecteur nomme le reverse proxy, et c’est ce qui donne au registre une adresse unique. port suit infra.port ; le proxy derrière lui écoute sur le port que fixe le chart et le Service transfère le trafic vers lui, si bien que modifier infra.port déplace l’adresse publiée et non l’écouteur.
Nommage : le réglage qui publie une adresse n’est pas le réglage qui nomme les ressources
Ce chart dérive la plupart des noms de ses ressources d’un réglage de nom de premier niveau, puis leur ajoute un suffixe — le Service du plan de contrôle est <instance>-core, celui de la console <instance>-portal, celui du magasin de blobs <instance>-registry, et ainsi de suite pour le niveau des workers, le scanner, le backend et le cache. Rien n’est nommé d’après le nom seul.
Le Service publié est nommé par un réglage distinct, à portée d’exposition, dont la valeur par défaut propre est un littéral fixe indépendant du nom de premier niveau. Une Recipe qui ne fixerait que le réglage de premier niveau publierait une adresse à laquelle aucun Service ne répond, et deux instances dans un même namespace émettraient toutes deux un Service sous ce littéral fixe et entreraient en collision. La Recipe définit donc les deux réglages à partir de l’ID d’instance, ce qui explique pourquoi le Service émis ci-dessus est nommé d’après l’instance et pourquoi provides.host nomme une adresse qui existe.
Cela vaut la peine d’être lu attentivement lorsque vous encapsulez un chart de plateforme quel qu’il soit : provides.host doit nommer le Service que le chart crée réellement, et le réglage qui en décide est une propriété du chart plutôt qu’une convention commune aux charts.
Ce que cette configuration n’inclut pas
L’Ingress du chart reste désactivé et le reverse proxy est exposé à la place comme un Service interne au cluster, car le Component publie une adresse interne au cluster plutôt qu’un nom d’hôte externe. Un endpoint externe unique est assemblé au niveau de l’ingress, avec un routage vers l’adresse qu’exporte ce module. La sécurité du transport est désactivée, car la source de certificats propre au chart génère une autorité de certification et un certificat signé au moment du rendu, que deux rendus d’une entrée identique ne reproduiraient pas. Le moniteur du Prometheus operator est désactivé.
Les métriques du registre sont elles aussi désactivées. Le values.metrics_enabled du Component les active pour le plan de contrôle, le niveau des workers, le magasin de blobs et un exporteur ajouté, et publie les quatre Services pour qu’un scraper les découvre ; le même paramètre du chart ouvre aussi l’écouteur de débogage du magasin de blobs — profilage, traces d’exécution et variables du runtime, sans vérification de l’appelant — à tout appelant interne au cluster. Le module laisse cette valeur à sa valeur par défaut false, si bien que cet exemple ne rend aucune métrique ; un Aggregate qui déclare lui-même le Component peut la définir. L’image de l’exporteur est néanmoins épinglée avec les autres.