Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Ein Chart in einem Git-Repository

Ein Helm-Chart muss nicht aus einer Chart-Registry stammen. Dieses Beispiel bezieht eines, das in einem Git-Repository liegt — das Beispiel-Chart hello-world des Helm-Projekts selbst — und baut daraus Kubernetes-Manifeste.

Das Aggregate des Entwicklers sagt nichts über all das. Es deklariert einen core/compute/server, und woher die Paketierung dieses Servers stammt, wird im Recipe entschieden und durch das Manifest gebunden.

Der source-Block

catalog/recipe/helm/hello-world-git/1.0.0/recipe.yaml
source:
kind: git-repository
url: https://github.com/helm/examples.git
ref: hello-world-0.1.0
module_subdir: charts/hello-world

Drei Koordinaten, und jede beantwortet eine andere Frage:

  • url — das zu klonende Repository. https://, ssh:// und git:// werden alle akzeptiert. Ein privates Repository wird über SSH durch den SSH-Agenten erreicht oder über HTTPS mit einem Eintrag für seinen Host in Ihrer netrc-Datei — machine github.com login <user> password <token>. Zugangsdaten, die in die URL selbst geschrieben sind, werden abgelehnt, wie Authentifizierung beschreibt.
  • ref — die Referenz, an der das Repository gelesen wird: ein Tag, ein Branch oder ein Commit. Sie ist das, was die Autoren des Repository benannt haben, und das ist nicht immer eine bloße Version — hier trägt der Tag zusätzlich den Namen des Charts.
  • module_subdir — das Verzeichnis innerhalb des Repository, das das Chart ist. Das Repository enthält unter diesem Pfad ein Chart, statt selbst eines zu sein, und das Verzeichnis ist Teil dessen, was das Artefakt unterscheidbar macht: Zwei Verzeichnisse eines Repository am selben Commit sind zwei Artefakte, nicht eines.

Der source-Typ nennt den Transport und den Ort, nicht das Format. Derselbe Typ ruft ein Chart, ein Terraform-Modul oder jedes andere Verzeichnis von Dateien ab; was das Verzeichnis enthält, ist Sache des konsumierenden Providers.

Was das Lockfile festhält

Nur ein Commit benennt Inhalt, der sich nicht unbemerkt ändern kann. Ein Tag oder ein Branch ist ein Name, den das Repository auf einen anderen Commit umsetzen kann, daher löst aggrega pull die Referenz auf und hält beides fest — die Referenz, die Sie geschrieben haben, und den Commit, auf den sie aufgelöst wurde:

# release-chart.lock
source_artifacts:
- kind: git-repository
url: https://github.com/helm/examples.git
module_subdir: charts/hello-world
pinned_version: f3dc419e558e6ccebce2ed447384e5d2e11de2f9
digest: sha256:2bee62cfc2efccc61d8e17efeb72f9f77ad7bd87f3ea4e50b1e4219c8d5a2c78
mediatype: application/gzip
referenced_by:
- entity: recipe
uri: helm/hello-world-git:1.0.0
field: spec.source
requested_ref: hello-world-0.1.0

Beide Hälften verdienen ihren Platz. Der Commit ist das, was der Build abruft, daher ist der Build reproduzierbar. Die Referenz ist das, worüber der Build den Eintrag nachschlägt, und das ist es, was Sie weiterhin ref: hello-world-0.1.0 im Recipe schreiben lässt und trotzdem auf genau den Commit auflöst, auf dem dieser Tag stand, als das Lockfile geschrieben wurde.

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:

Terminal window
aggrega scaffold --example chart-from-git-repository

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd chart-from-git-repository

Build

Terminal window
aggrega build --release release-chart.yaml --auto-pull

Dieses Beispiel enthält zwei Releases, daher wird das zu bauende benannt. Der erste Build braucht ein Lockfile, deshalb wird hier --auto-pull übergeben; einmal vorher aggrega pull --release release-chart.yaml auszuführen, bewirkt dasselbe und lässt jeden späteren Build ohne Flag laufen.

Das gerenderte Deployment trägt die Werte, die das Release geliefert hat, abgebildet auf die eigenen Wertnamen des Charts:

dist/app/helm/web-deployment-web-hello-world.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: web-hello-world
[… omitted: the chart's own labels, and the labels and annotations every rendered document carries]
spec:
replicas: 2
[… omitted: the selector and the pod template's own labels]
spec:
serviceAccountName: web-hello-world
securityContext: {}
containers:
- name: hello-world
securityContext: {}
image: "nginx:1.27.3"
imagePullPolicy: IfNotPresent
[… omitted: the container port and the two probes]

Jeder Build gibt eine Warnung aus:

warning: node "web": .infra key "compute" is read by no template in recipe "hello-world-git" — correct the spelling, or remove the key

Das ist zutreffend und eher lesens- als stummschaltenswert. Die Component core/compute/server bietet einen Regler für die CPU- und Speicherdimensionierung; dieses Chart stellt dafür keine Werte bereit, daher bildet das Recipe dort nichts ab. Ein sourced Recipe bildet ab, was das Chart, das es bezieht, tatsächlich akzeptiert, und der Compiler meldet den Wert, der nirgends angekommen ist, statt so zu tun, als wäre er gelandet.

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 nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `chart-from-git-repository` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `chart-from-git-repository` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `chart-from-git-repository`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `chart-from-git-repository`, `release` auf `release-chart.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `chart-from-git-repository/dist/`.

Wenn sich die Referenz bewegt

Ein Tag kann im Repository umgesetzt werden. Wenn das geschieht, stellt der nächste gewöhnliche aggrega pull fest, dass die Referenz auf etwas anderes als den festgehaltenen Commit aufgelöst wird, und bricht ab, statt ihn zu übernehmen:

# aggrega pull --release release-chart.yaml
#
# [E0130]
# lockfile: out of date; it no longer matches what its Release resolves to
# ---
# source-artifact kind=git-repository url=https://github.com/helm/examples.git
# module_subdir=charts/hello-world: reference "hello-world-0.1.0" moved — the
# lockfile pins 03f4a18d3c2b77b7ecd91d0324a95910d4f04152, and it now resolves to
# f3dc419e558e6ccebce2ed447384e5d2e11de2f9; adopt where it now points with
# `aggrega pull --upgrade --release <release>`

Er nennt beide Commits, sodass Sie genau sehen können, was sich bewegt hat, bevor Sie entscheiden. Das Lockfile bleibt, wie es war — der Abbruch erfolgt, bevor irgendetwas geschrieben wird —, und den neuen Commit zu übernehmen, ist ein bewusster Schritt:

Terminal window
aggrega pull --upgrade --pin-sources --release release-chart.yaml

Eine bewegte Referenz ist der Fall, für den --upgrade da ist: Ein gewöhnlicher Pull hält den Commit, den das Lockfile festhält, und nur ein Upgrade übernimmt, wohin die Referenz jetzt zeigt. Ein bloßes --upgrade verwirft jede festgehaltene Fixierung, daher fragt es zuerst nach einer Bestätigung. --pin-sources ist ebenfalls nötig, weil dieses Recipe auch den Commit seiner Quelle in der entity.lock daneben festhält: Das Upgrade schreibt diese Fixierung auf den neuen Commit um, während der Pull ohne das Flag an der Lock-Datei abbricht und aggrega pin nennt. Committen Sie die umgeschriebene entity.lock zusammen mit dem Recipe.

Eine Änderung in diesem Workspace, etwa am Aggregate oder am Release, ist eine Abweichung anderer Art: Der nächste Build meldet sie, und ein gewöhnliches aggrega pull --release release-chart.yaml beseitigt sie.

Einen Commit statt eines Tags in ref: zu fixieren, ist der andere Weg zur selben Garantie, um den Preis einer Koordinate, die kein Mensch lesen kann.

Das Guardrail-Release

release-negative.yaml soll fehlschlagen, und es ist hier, weil ein Abrufpfad, der nur auf seinem Erfolgspfad ausgeübt wird, nichts über seine Schutzmechanismen aussagt. Es stellt dasselbe Aggregate über manifest-negative.yaml bereit, das ein Recipe bindet, das bis auf seine Referenz mit dem funktionierenden identisch ist — sie nennt einen Tag, den das Repository nicht enthält:

Terminal window
aggrega build --release release-negative.yaml --auto-pull
# exits non-zero
# [E0137]
# auto-pull: resolving the source of each Recipe and FeatureRecipe the Release
# uses: resolve: resolve source for recipe
# "helm/hello-world-git-missing-ref:1.0.0": sourceresolver: kind=git-repository
# url=https://github.com/helm/examples.git version=: oci: artifact not found at
# remote source (cause: reference not found)
[… omitted: the rest of that line, a remediation naming the URL and version to check]

Das Repository ist erreichbar, und das Klonen gelingt; es gibt darin einfach keine solche Referenz, daher gibt es keinen Commit zu fixieren und nichts zu archivieren.

Was dieses Beispiel vom Netzwerk braucht

Anders als die meisten Workspaces hier klont dieser beim ersten Build ein echtes Repository, daher braucht dieser Build ausgehenden Zugriff auf den in url genannten Host. Sobald das Lockfile und der Auflösungs-Cache existieren, lesen spätere Builds aus dem Cache und laufen ganz ohne Netzwerk — aggrega build --release release-chart.yaml --offline baut dieselben Bytes neu.