Stack Harbor — un registry di container distribuito come un’unica release
Questo esempio compila un vero registry di container in manifest Kubernetes a partire da un unico Aggregate scritto dallo sviluppatore.
Un registry di container è composto da molti servizi che cooperano — un control plane di API e servizio di token, un blob store OCI e il suo controller, una console web, un livello di worker asincroni, uno scanner di vulnerabilità, un backend relazionale, una cache chiave-valore e un reverse proxy davanti a tutti loro. Il catalogo descrive tutto ciò come un unico Component, perché i maintainer stessi del registry pubblicano un chart Helm che lo distribuisce per intero come un’unica release, nell’ordine richiesto dai suoi servizi. Il Component dichiara il registry; la Recipe incapsula quel chart.
Il registry viene importato come modulo: un sotto-aggregato riutilizzabile che compone il Component ed esporta il suo indirizzo pubblicato. L’Aggregate di primo livello importa il modulo per nome e gli passa tre delle chiavi del registry; l’operatore dimensiona il componente del modulo nella Release.
File
| File | Ruolo |
|---|---|
aggregate.yaml | Intento dello sviluppatore: importa il modulo di registry di container (core/harbor) e gli passa tre delle chiavi del registry da propri parametri. |
manifest-helm-synth.yaml | Mappa il tipo di componente del registry sulla Recipe che incapsula il suo chart Helm, e la Feature di credenziale sulla realizzazione che legge un Secret già presente nel namespace — tranne la password dell’amministratore, che lega per nome alla realizzazione che emette un Secret dal parametro del modulo. |
release-helm-synth.yaml | Documento dell’operatore per il target Kubernetes. Nomina i Secret che contengono le tre chiavi che l’Aggregate passa verso il basso, dimensiona il componente del modulo tramite il suo ID con ambito di modulo, e gli associa la chiave di firma dei token, il segreto condiviso dei servizi e la chiave con cui sono cifrate le credenziali memorizzate, nominando i Secret che le contengono; tutto il resto è lasciato ai valori predefiniti dello schema. |
Che cosa dimostra
- Un prodotto multiservizio come un unico Component. Ciò che rende il registry un unico Component anziché diversi non è la sua dimensione, ma il punto in cui viene mantenuto il suo cablaggio: l’instradamento del reverse proxy, la chiave del servizio di token rispetto alla quale il control plane verifica ogni pull e ogni push, le impostazioni di connessione che ogni servizio legge per il backend e per la cache, la suddivisione in database logici che tiene separati gli spazi delle chiavi della cache dei servizi e l’ordine di avvio — tutto questo viene mantenuto allineato al prodotto dalle persone che lo rilasciano, all’interno del chart. Un consumatore dichiara un registry e ottiene tutti questi elementi tra loro coerenti.
- Un chart incapsulato. La Recipe nomina il chart in
source:e vi sovrappone unvaluesMapping:— il template dei valori è l’intera implementazione, e il provider Helm renderizza i template propri del chart rispetto a esso. Qui non viene sintetizzato alcun carico di lavoro. - Un input esterno fissato. Il chart è un input che il build recupera, quindi viene fissato come qualsiasi dipendenza: il lockfile registra la versione del chart, il suo URL risolto e il digest del tarball, sotto
source_artifacts. Un build eseguito su un lockfile popolato serve il chart dallo store dei contenuti e lo verifica rispetto a quel digest. - Un unico indirizzo pubblicato per un’intera piattaforma. Il reverse proxy del chart instrada il percorso del browser
/alla console e i percorsi del registry e dell’API (/v2/,/api/,/service/,/c/) al control plane, così un client di container effettua il login, il push e il pull sullo stesso host su cui un browser raggiunge la console. Quel Service è ciò cheprovides.hostpubblica, e a un consumatore non serve un secondo indirizzo per raggiungere nessuno dei due insiemi di percorsi. - Due nomi pubblici per lo stesso indirizzo. Il modulo esporta quell’unico indirizzo come
registry, l’endpoint a cui si rivolgono i client delle immagini e l’API, e comeui, l’endpoint web. Entrambi si risolvono nell’indirizzo che serve entrambi gli insiemi di percorsi, quindi un consumatore si connette al nome che descrive il suo intento. - Dimensionamento del componente di un modulo da parte dell’operatore. La Release indirizza il componente del modulo tramite il suo ID con ambito di modulo (
harbor.registry) per impostarne le risorse di calcolo, senza che l’Aggregate dello sviluppatore ripeta il dimensionamento fisico. - Regole di completezza su un valore raggruppato.
infra.computecontiene una chiave per la CPU e una per la memoria, e la Recipe si arresta su un gruppo che lascia vuota una delle due. Un control plane renderizzato con un limite di CPU e nessun limite di memoria è sostanzialmente diverso da quello descritto dai valori predefiniti dichiarati del Component, e nulla nell’output renderizzato lo direbbe — quindi il build si ferma e nomina invece la chiave mancante. Una chiave che il gruppo omette assume il valore predefinito del Component. - Sei chiavi senza valore predefinito. La chiave con cui il servizio di token firma i token del registry, insieme al suo certificato; i tre segreti con cui i servizi stessi del registry si autenticano tra loro e firmano lo stato dei caricamenti; la chiave contro la falsificazione delle richieste; e la chiave con cui il control plane cifra le credenziali memorizzate non hanno alcun valore predefinito: una chiave posseduta da ogni lettore del catalogo permetterebbe a chiunque di emettere token di cui il registry si fida o di leggere ciò che archivia. Il Component dichiara quegli slot obbligatori, quindi un build che ne lascia vuoto uno si arresta e nomina lo slot. Il build non legge nessuno dei sei valori e non ne renderizza nessuno: ogni carico di lavoro legge ciascuno di essi da un Secret che nomina.
- Tre chiavi che la Release associa. Il modulo non associa né la chiave di firma dei token, né il segreto condiviso del control plane, né la chiave con cui sono cifrate le credenziali memorizzate, quindi la Release associa tutte e tre al componente del modulo,
token_key,core_secretesecret_key, ciascuna tramitecore/referenced-secretconinfra.originche nomina un Secret, e il Manifest lega la Feature ak8s-existing-secret. Il control plane monta la chiave di firma dei token e la chiave di cifratura dai Secret che esse nominano, e i servizi leggono il segreto condiviso dal proprio. - Credenziali che il modulo popola. La password dell’account amministratore, la chiave contro la falsificazione delle richieste tra siti, il segreto condiviso del livello dei worker e il segreto dello stato dei caricamenti del blob store sono anch’essi slot di credenziale del Component, e il modulo popola ciascuno da un proprio parametro (
admin_password,csrf_key,jobservice_secret,registry_http_secret) tramite la Feature di credenzialecore/referenced-secret, così ogni carico di lavoro li legge da un Secret per nome. Poiché il modulo associa quella Feature, il Manifest la mappa. Nemmeno nel modulo le tre chiavi hanno un valore predefinito, quindi l’Aggregate dichiara propri parametri e li passa verso il basso tramiteaggregates.harbor.parameters, la Release li soddisfa ek8s-existing-secretlegge ciascuno come il nome di un Secret che esiste già nel namespace; una Release che non fornisce alcun valore arresta il build, nominando il parametro. Questo esempio lascia la password dell’amministratore al valore predefinito di sviluppo del modulo, e il Manifest lega per nome quell’unica associazione ak8s-secret-from-parameter, che emette un Secret che la contiene. Le password rimanenti vengono scritte nella configurazione che la Release renderizza, quindi si sostituiscono impostando inveceinfra; se non impostate, ciascuna assume un valore di sviluppo indicato dalla Recipe. - Output deterministico su un chart che altrimenti genererebbe materiale. Lasciato a sé stesso, questo chart genera i propri segreti quando non ne viene fornito alcuno — il segreto condiviso e quello di firma dei token del control plane, i segreti del livello dei worker e del blob store, la chiave contro la falsificazione delle richieste e la password con hash del blob store, di cui ricalcola l’hash con un nuovo salt a ogni rendering. Ciascuno viene invece fornito: le sei chiavi sempre dai Secret che la Release nomina, e le password dalla credenziale associata per nome dove uno slot è popolato e da un valore di sviluppo fisso dove non lo è, così due rendering di input identico emettono byte identici.
- Immagini riproducibili. Ogni immagine eseguita dal registry è fissata a un tag esplicito. Il prodotto le rilascia tutte con un unico tag, quindi
infra.engine_versionle seleziona tutte in una volta;infra.overrides.imagesostituisce il fissaggio di un singolo servizio, einfra.overrides.image_prefixle sposta tutte insieme per una Release che esegue il pull da un mirror.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example harbor-stackPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd harbor-stackBuild
Questo workspace non contiene alcun .aggrega-config.yaml, quindi le entità della libreria standard vengono risolte dal registry dell’hub, hub.aggrega.ai, e non serve alcun flag di catalogo. La Recipe recupera un chart, quindi risolvi prima le dipendenze nel lockfile:
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlGli artefatti renderizzati finiscono sotto dist/.
Prima di applicarli, crea i sei Secret che la Release nomina nel namespace in cui il registry è distribuito: harbor-token-key, che contiene una chiave privata RSA sotto la chiave dati tls.key e un certificato su quella chiave sotto tls.crt; harbor-core-secret, che contiene un segreto di 16 caratteri sotto la chiave dati secret; harbor-secret-key, che contiene una chiave di 16 caratteri sotto secretKey; harbor-csrf-key, che contiene una chiave di 32 caratteri sotto CSRF_KEY; e harbor-jobservice-secret e harbor-registry-http-secret, che contengono un segreto di 16 caratteri sotto JOBSERVICE_SECRET e REGISTRY_HTTP_SECRET. Ad esempio:
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 registry i cui servizi non trovano questi Secret non si avvia.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella dell’area di lavoro non contiene ancora una cartella `harbor-stack`, chiama una volta lo strumento `scaffold` con `example` impostato a `harbor-stack` e senza `dir`: scrive l’esempio in una nuova cartella `harbor-stack`. Poi chiama lo strumento `build` con `workspace_root` impostato a `harbor-stack`, `release` impostato a `release-helm-synth.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `harbor-stack/dist/`.Come appare il registry composto
Il build emette le risorse che il chart definisce per questa configurazione: Deployment per il reverse proxy, la console, il control plane, il livello dei worker e il blob store; StatefulSet per il backend, la cache e lo scanner; richieste di volume persistente per il blob store e per i log del livello dei worker; le ConfigMap e i Secret che ogni servizio legge; e i Service che stanno davanti a essi. Accanto a essi la Feature di credenziale emette un Secret, harbor-zdregistry-admin-password, che contiene il valore predefinito di sviluppo del modulo per la password dell’amministratore, che il control plane legge da esso anziché dal Secret proprio del chart. Non viene emesso alcun Secret per nessuna delle sei chiavi: il control plane monta la chiave di firma dei token da harbor-token-key e la chiave di cifratura da harbor-secret-key, e i servizi leggono le altre da harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret e harbor-registry-http-secret, i Secret che la Release nomina.
Esattamente uno di quei Service è l’indirizzo a cui si connettono i consumatori — 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: nginxIl suo selettore nomina il reverse proxy, ed è questo che dà al registry un unico indirizzo. port segue infra.port; il proxy dietro di esso è in ascolto sulla porta che il chart stabilisce e il Service inoltra il traffico verso di essa, quindi spostare infra.port sposta l’indirizzo pubblicato e non il listener.
Denominazione: l’impostazione che pubblica un indirizzo non è l’impostazione che dà il nome alle risorse
Questo chart ricava la maggior parte dei nomi delle sue risorse da un’impostazione di nome di primo livello e poi aggiunge loro un suffisso — il Service del control plane è <instance>-core, quello della console <instance>-portal, quello del blob store <instance>-registry, e così via per il livello dei worker, lo scanner, il backend e la cache. Nulla prende il nome dal solo nome di base.
Il Service pubblicato prende il nome da un’impostazione separata, con ambito di esposizione, il cui valore predefinito è un letterale fisso indipendente dal nome di primo livello. Una Recipe che fissasse solo l’impostazione di primo livello pubblicherebbe un indirizzo a cui nessun Service risponde, e due istanze in un unico namespace emetterebbero entrambe un Service con quel letterale fisso e andrebbero in collisione. La Recipe imposta quindi entrambe le impostazioni dall’ID dell’istanza, ed è per questo che il Service emesso sopra prende il nome dall’istanza e che provides.host nomina un indirizzo che esiste.
Vale la pena leggerlo con attenzione quando si incapsula un qualsiasi chart di piattaforma: provides.host deve nominare il Service che il chart crea effettivamente, e quale impostazione lo decide è una proprietà del chart, non una convenzione comune ai chart.
Cosa non include questa configurazione
L’Ingress del chart resta disattivato e il reverse proxy viene invece esposto come Service interno al cluster, perché il Component pubblica un indirizzo interno al cluster anziché un hostname esterno. Un unico endpoint esterno viene assemblato a livello di ingress, con instradamento verso l’indirizzo che questo modulo esporta. La sicurezza del trasporto è disattivata, perché la sorgente dei certificati propria del chart genera un’autorità di certificazione e un certificato firmato al momento del rendering, che due rendering di input identico non riprodurrebbero. Il monitor del Prometheus operator è disattivato.
Anche le metriche del registry sono disattivate. Il values.metrics_enabled del Component le attiva per il control plane, il livello dei worker, il blob store e un exporter aggiuntivo, e pubblica i quattro Service affinché uno scraper li scopra; la stessa impostazione del chart apre anche il listener di debug del blob store — profilazione, tracce di esecuzione e variabili di runtime, senza alcun controllo del chiamante — a ogni chiamante interno al cluster. Il modulo lascia quel valore al suo predefinito false, quindi questo esempio non renderizza alcuna metrica; un Aggregate che dichiara direttamente il Component può impostarlo. L’immagine dell’exporter è comunque fissata insieme alle altre.