Harbor-Stack — eine Container-Registry, als ein einziges Release bereitgestellt
Dieses Beispiel kompiliert eine reale Container-Registry aus einem einzigen vom Entwickler verfassten Aggregate zu Kubernetes-Manifesten.
Eine Container-Registry besteht aus vielen zusammenarbeitenden Diensten — einer Control Plane aus API und Token-Dienst, einem OCI-Blob-Store und seinem Controller, einer Webkonsole, einer asynchronen Worker-Schicht, einem Schwachstellenscanner, einem relationalen Backend, einem Key-Value-Cache und einem vorgeschalteten Reverse Proxy. Der Katalog beschreibt all das als eine Component, weil die Maintainer der Registry selbst ein Helm-Chart veröffentlichen, das das Ganze als ein einziges Release bereitstellt, in der Reihenfolge, die seine Dienste benötigen. Die Component deklariert die Registry; das Recipe kapselt dieses Chart.
Die Registry wird als Modul importiert: ein wiederverwendbares Sub-Aggregat, das die Component zusammensetzt und ihre veröffentlichte Adresse exportiert. Das Aggregate der obersten Ebene importiert das Modul über seinen Namen und übergibt ihm drei der Schlüssel der Registry; der Betreiber dimensioniert die Komponente des Moduls im Release.
Dateien
| Datei | Rolle |
|---|---|
aggregate.yaml | Entwicklerabsicht: importiert das Container-Registry-Modul (core/harbor) und übergibt ihm drei der Schlüssel der Registry aus eigenen Parametern. |
manifest-helm-synth.yaml | Ordnet den Komponententyp der Registry dem Recipe zu, das ihr Helm-Chart kapselt, und das Zugangsdaten-Feature der Realisierung, die ein bereits im Namespace vorhandenes Secret liest — außer dem Passwort des Administrators, das es über den Namen an die Realisierung bindet, die aus dem Parameter des Moduls ein Secret ausgibt. |
release-helm-synth.yaml | Betreiber-Datensatz für das Kubernetes-Ziel. Nennt die Secrets, die die drei Schlüssel enthalten, die das Aggregate nach unten weiterreicht, dimensioniert die Komponente des Moduls über ihre modulbezogene ID und bindet den Token-Signaturschlüssel, das gemeinsame Secret der Dienste und den Schlüssel, mit dem gespeicherte Zugangsdaten verschlüsselt werden, an sie an, indem es die Secrets nennt, die sie enthalten; alles andere bleibt den Schema-Voreinstellungen überlassen. |
Was es zeigt
- Ein Produkt aus mehreren Diensten als eine Component. Was die Registry zu einer Component statt zu mehreren macht, ist nicht ihre Größe, sondern der Ort, an dem ihre Verdrahtung gepflegt wird: das Routing des Reverse Proxys, der Schlüssel des Token-Dienstes, gegen den die Control Plane jeden Pull und jeden Push prüft, die Verbindungseinstellungen, die jeder Dienst für das Backend und den Cache liest, die Aufteilung in logische Datenbanken, die die Cache-Keyspaces der Dienste voneinander trennt, und die Startreihenfolge — all das wird von den Menschen, die das Produkt ausliefern, im Chart mit dem Produkt im Einklang gehalten. Ein Konsument deklariert eine Registry und erhält all dies aufeinander abgestimmt.
- Ein gekapseltes Chart. Das Recipe nennt das Chart in
source:und legt einvaluesMapping:darüber — die Werte-Vorlage ist die gesamte Implementierung, und der Helm-Provider rendert die eigenen Vorlagen des Charts gegen sie. Hier wird keine Arbeitslast synthetisiert. - Eine fixierte externe Eingabe. Das Chart ist eine Eingabe, die der Build abruft, daher wird es wie jede Abhängigkeit fixiert: Das Lockfile verzeichnet die Version des Charts, seine aufgelöste URL und den Digest des Tarballs unter
source_artifacts. Ein Build gegen ein befülltes Lockfile liefert das Chart aus dem Content-Store und verifiziert es gegen diesen Digest. - Eine veröffentlichte Adresse für eine ganze Plattform. Der Reverse Proxy des Charts routet den Browser-Pfad
/zur Konsole und die Registry- und API-Pfade (/v2/,/api/,/service/,/c/) zur Control Plane, sodass sich ein Container-Client bei demselben Host anmeldet, pusht und pullt, über den ein Browser die Konsole erreicht. Dieser Service ist das, wasprovides.hostveröffentlicht, und ein Konsument braucht keine zweite Adresse, um einen der beiden Pfadsätze zu erreichen. - Zwei öffentliche Namen dafür. Das Modul exportiert diese eine Adresse als
registry, den Endpunkt, mit dem Image-Clients und die API sprechen, und alsui, den Web-Endpunkt. Beide lösen zu der Adresse auf, die beide Pfadsätze bedient, sodass sich ein Konsument mit dem Namen verbindet, der seine Absicht beschreibt. - Dimensionierung der Komponente eines Moduls durch den Betreiber. Das Release adressiert die Komponente des Moduls über ihre modulbezogene ID (
harbor.registry), um Rechenressourcen festzulegen, ohne dass das Aggregate des Entwicklers die physische Dimensionierung wiederholt. - Vollständigkeitsregeln für einen gruppierten Wert.
infra.computeträgt einen Schlüssel für die CPU und einen für den Speicher, und das Recipe bricht bei einer Gruppe ab, die einen der beiden leer lässt. Eine Control Plane, die mit einem CPU-Limit und ohne Speicherlimit gerendert wird, unterscheidet sich wesentlich von derjenigen, die die deklarierten Voreinstellungen der Component beschreiben, und nichts in der gerenderten Ausgabe würde darauf hinweisen — daher hält der Build stattdessen an und nennt den fehlenden Schlüssel. Ein Schlüssel, den die Gruppe auslässt, übernimmt die Voreinstellung der Component. - Sechs Schlüssel ohne Voreinstellung. Der Schlüssel, mit dem der Token-Dienst die Token der Registry signiert, zusammen mit seinem Zertifikat; die drei Secrets, mit denen sich die eigenen Dienste der Registry gegenseitig authentifizieren und den Upload-Zustand signieren; der Schlüssel gegen Request-Fälschung; und der Schlüssel, mit dem die Control Plane gespeicherte Zugangsdaten verschlüsselt, haben keinen Standardwert: Ein Schlüssel, den jeder Leser des Katalogs besäße, würde es jedem erlauben, Token auszustellen, denen die Registry vertraut, oder zu lesen, was sie speichert. Die Component deklariert diese Slots als erforderlich, daher bricht ein Build, der einen davon leer lässt, ab und nennt den Slot. Der Build liest keinen der sechs Werte und rendert keinen davon: Jede Arbeitslast liest jeden aus einem Secret, das sie nennt.
- Drei Schlüssel, die das Release anbindet. Das Modul bindet weder den Token-Signaturschlüssel noch das gemeinsame Secret der Control Plane noch den Schlüssel an, mit dem gespeicherte Zugangsdaten verschlüsselt werden, daher bindet das Release alle drei an die Komponente des Moduls an,
token_key,core_secretundsecret_key, jeweils übercore/referenced-secretmitinfra.origin, das ein Secret nennt, und das Manifest bindet das Feature ank8s-existing-secret. Die Control Plane hängt den Token-Signaturschlüssel und den Verschlüsselungsschlüssel aus den Secrets ein, die sie nennen, und die Dienste lesen das gemeinsame Secret aus ihrem. - Zugangsdaten, die das Modul befüllt. Das Passwort des Administratorkontos, der Schlüssel gegen Cross-Site-Request-Fälschung, das gemeinsame Secret der Worker-Schicht und das Upload-Zustand-Secret des Blob-Stores sind ebenfalls Zugangsdaten-Slots der Component, und das Modul befüllt jeden aus einem eigenen Parameter (
admin_password,csrf_key,jobservice_secret,registry_http_secret) über das Zugangsdaten-Featurecore/referenced-secret, sodass jede Arbeitslast sie über den Namen aus einem Secret liest. Da das Modul dieses Feature anbindet, ordnet das Manifest es zu. Auch im Modul haben die drei Schlüssel keine Voreinstellung, daher deklariert das Aggregate eigene Parameter und reicht sie überaggregates.harbor.parametersnach unten weiter, das Release erfüllt sie, undk8s-existing-secretliest jeden als Namen eines Secret, das bereits im Namespace existiert; ein Release, das keinen Wert liefert, bricht den Build ab und nennt dabei den Parameter. Dieses Beispiel belässt das Administratorpasswort auf der Entwicklungs-Voreinstellung des Moduls, und das Manifest bindet diese eine Anbindung über den Namen ank8s-secret-from-parameter, das ein Secret ausgibt, das es enthält. Die übrigen Passwörter werden in die Konfiguration geschrieben, die das Release rendert, daher werden sie stattdessen durch Setzen voninfraersetzt; ungesetzt übernimmt jedes einen Entwicklungswert, den das Recipe angibt. - Deterministische Ausgabe über einem Chart, das sonst Material erzeugen würde. Sich selbst überlassen, erzeugt dieses Chart seine eigenen Secrets, wenn keine geliefert werden — das gemeinsame und das Token-Signatur-Secret der Control Plane, die Secrets der Worker-Schicht und des Blob-Stores, den Schlüssel gegen Request-Fälschung und das gehashte Passwort des Blob-Stores, das es bei jedem Rendering mit einem frischen Salt neu hasht. Stattdessen wird jedes davon geliefert: die sechs Schlüssel stets aus den Secrets, die das Release nennt, und die Passwörter aus den über den Namen angebundenen Zugangsdaten, wo ein Slot befüllt ist, und aus einem festen Entwicklungswert, wo nicht, sodass zwei Renderings identischer Eingabe byteidentische Bytes ausgeben.
- Reproduzierbare Images. Jedes Image, das die Registry ausführt, ist auf einen expliziten Tag fixiert. Das Produkt liefert sie alle unter einem Tag aus, daher wählt
infra.engine_versionalle auf einmal aus;infra.overrides.imageersetzt die Fixierung eines einzelnen Dienstes, undinfra.overrides.image_prefixverschiebt sie gemeinsam für ein Release, das aus einem Mirror pullt.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example harbor-stackDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd harbor-stackBuild
Dieser Workspace enthält kein .aggrega-config.yaml, daher werden die Entitäten der Standardbibliothek aus der Hub-Registry hub.aggrega.ai aufgelöst, und es ist kein Katalog-Flag nötig. Das Recipe ruft ein Chart ab, lösen Sie daher zuerst die Abhängigkeiten in das Lockfile auf:
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlGerenderte Artefakte landen unter dist/.
Bevor Sie sie anwenden, legen Sie die sechs Secrets, die das Release nennt, in dem Namespace an, in dem die Registry bereitgestellt wird: harbor-token-key mit einem privaten RSA-Schlüssel unter dem Datenschlüssel tls.key und einem Zertifikat über diesen Schlüssel unter tls.crt; harbor-core-secret mit einem 16-stelligen Secret unter dem Datenschlüssel secret; harbor-secret-key mit einem 16-stelligen Schlüssel unter secretKey; harbor-csrf-key mit einem 32-stelligen Schlüssel unter CSRF_KEY; und harbor-jobservice-secret und harbor-registry-http-secret mit je einem 16-stelligen Secret unter JOBSERVICE_SECRET und REGISTRY_HTTP_SECRET. Zum Beispiel:
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)"Eine Registry, deren Dienste diese Secrets nicht finden, startet nicht.
Mit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Arbeitsbereichsordner noch keinen Ordner `harbor-stack` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `harbor-stack` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `harbor-stack`. Rufen Sie dann das Tool `build` mit `workspace_root` auf `harbor-stack`, `release` auf `release-helm-synth.yaml`, `auto_pull` auf true und `write` auf true gesetzt auf. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `harbor-stack/dist/`.Wie die zusammengesetzte Registry aussieht
Der Build gibt die Ressourcen aus, die das Chart für diese Konfiguration definiert: Deployments für den Reverse Proxy, die Konsole, die Control Plane, die Worker-Schicht und den Blob-Store; StatefulSets für das Backend, den Cache und den Scanner; Persistent Volume Claims für den Blob-Store und für die Logs der Worker-Schicht; die ConfigMaps und Secrets, die jeder Dienst liest; und die Services, die ihnen vorgelagert sind. Daneben gibt das Zugangsdaten-Feature ein Secret aus, harbor-zdregistry-admin-password, das die Entwicklungs-Voreinstellung des Moduls für das Administratorpasswort enthält, die die Control Plane daraus liest statt aus dem eigenen Secret des Charts. Für keinen der sechs Schlüssel wird ein Secret ausgegeben: Die Control Plane hängt den Token-Signaturschlüssel aus harbor-token-key und den Verschlüsselungsschlüssel aus harbor-secret-key ein, und die Dienste lesen die übrigen aus harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret und harbor-registry-http-secret, den Secrets, die das Release nennt.
Genau einer dieser Services ist die Adresse, mit der sich Konsumenten verbinden — 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: nginxSein Selektor nennt den Reverse Proxy, und das gibt der Registry eine einzige Adresse. port folgt infra.port; der Proxy dahinter lauscht auf dem Port, den das Chart festlegt, und der Service leitet an ihn weiter, sodass eine Änderung von infra.port die veröffentlichte Adresse verschiebt und nicht den Listener.
Benennung: Die Stellschraube, die eine Adresse veröffentlicht, ist nicht die Stellschraube, die Ressourcen benennt
Dieses Chart leitet die meisten seiner Ressourcennamen aus einer Namens-Stellschraube der obersten Ebene ab und hängt ihnen dann Suffixe an — der Service der Control Plane ist <instance>-core, der der Konsole <instance>-portal, der des Blob-Stores <instance>-registry, und so weiter für die Worker-Schicht, den Scanner, das Backend und den Cache. Nichts wird nach dem bloßen Namen benannt.
Der veröffentlichte Service wird über eine separate, auf die Exposition bezogene Stellschraube benannt, deren eigene Voreinstellung ein festes Literal ist, unabhängig vom Namen der obersten Ebene. Ein Recipe, das nur die Stellschraube der obersten Ebene festlegt, würde eine Adresse veröffentlichen, auf die kein Service antwortet, und zwei Instanzen in einem Namespace würden beide einen Service unter diesem festen Literal ausgeben und kollidieren. Das Recipe setzt daher beide Stellschrauben aus der Instanz-ID, weshalb der oben ausgegebene Service nach der Instanz benannt ist und provides.host eine Adresse nennt, die existiert.
Es lohnt sich, dies genau zu lesen, wenn Sie ein beliebiges Plattform-Chart kapseln: provides.host muss den Service nennen, den das Chart tatsächlich erstellt, und welche Stellschraube das entscheidet, ist eine Eigenschaft des Charts und keine Konvention über Charts hinweg.
Was diese Konfiguration nicht enthält
Der Ingress des Charts bleibt ausgeschaltet, und der Reverse Proxy wird stattdessen als clusterinterner Service exponiert, weil die Component eine clusterinterne Adresse statt eines externen Hostnamens veröffentlicht. Ein einziger externer Endpunkt wird auf der Ingress-Schicht zusammengesetzt und routet zu der Adresse, die dieses Modul exportiert. Die Transportsicherheit ist ausgeschaltet, weil die eigene Zertifikatsquelle des Charts zum Renderzeitpunkt eine Zertifizierungsstelle und ein signiertes Zertifikat erzeugt, die zwei Renderings identischer Eingabe nicht reproduzieren würden. Der Monitor des Prometheus-Operators ist ausgeschaltet.
Auch die Metriken der Registry sind ausgeschaltet. values.metrics_enabled der Component schaltet sie für die Control Plane, die Worker-Schicht, den Blob-Store und einen zusätzlichen Exporter ein und veröffentlicht die vier Services, damit ein Scraper sie entdeckt; dieselbe Chart-Einstellung öffnet außerdem den Debug-Listener des Blob-Stores — Profiling, Ausführungs-Traces und Laufzeitvariablen, ohne Prüfung des Aufrufers — für jeden clusterinternen Aufrufer. Das Modul belässt diesen Wert auf seiner Voreinstellung false, daher rendert dieses Beispiel keine Metriken; ein Aggregate, das die Component selbst deklariert, kann ihn setzen. Das Image des Exporters ist trotzdem mit den übrigen fixiert.