Einheit 3.1: Container Registry und Image-Pipelines
Einführung
Modul 2 hat TaskBoard sein Netzwerk, den Load Balancer, den Speicher und die Datenbanken bereitgestellt. Die Anwendung selbst läuft weiterhin als Dateien, die auf einen Server kopiert wurden. Bevor Sie sie in Einheit 3.2 auf Managed Kubernetes bereitstellen können, benötigen Sie versionierte Container-Images in einer Registry, auf die Ihr Cluster und Ihre CI-Pipeline zugreifen können.
Die Private Container Registry bietet Ihnen genau das. Sie unterstützt die Docker Registry HTTP API v2, sodass die Docker CLI und jedes CI-System, das diese API spricht, damit zusammenarbeiten. Der Zugriff erfordert immer eine Authentifizierung: Sie erstellen Tokens mit Scopes, und jeder Client meldet sich mit einem Token an.
In dieser Einheit provisionieren Sie die Registry und ihre Tokens mit Terraform, melden sich mit Docker an, erstellen Multi-Stage-Images für die TaskBoard API und das Frontend und schieben sie mit Git-SHA-Tags hoch. Im Code Lab führen Sie den vollständigen Ablauf von terraform apply bis zu einem verifizierten Pull durch.
1. Bereitstellung der Registry mit Terraform
resource "ionoscloud_container_registry" "taskboard" {
name = "taskboard-registry-7f3a"
location = "de/fra"
garbage_collection_schedule {
days = ["Sunday"]
time = "03:00:00+00:00"
}
features {
vulnerability_scanning = false
}
}
Die Ressource benötigt ein name und ein location. Beide sind unveränderlich: Eine Änderung an einem der beiden führt dazu, dass Terraform die Registry zerstört und neu erstellt, einschließlich aller darin enthaltenen Images. Die Registry ist in der Region FRA, Standort de/fra, verfügbar.
1.1 Namensregeln
Der Registry-Name muss folgende Bedingungen erfüllen:
- Global eindeutig über alle Kunden hinweg sein
- Zwischen 3 und 63 Zeichen lang sein
- Nur aus alphanumerischen Zeichen und Gedankenstrichen bestehen
- Mit einem Buchstaben von a bis z beginnen und mit einem alphanumerischen Zeichen enden
Da der Name global ist, fügen Sie für jede Umgebung einen zufälligen Suffix hinzu, wie Sie es für Object Storage-Buckets in Einheit 2.4 getan haben.
1.2 Schwachstellen-Scanning und Garbage Collection
Schwachstellen-Scanning ist ein kostenpflichtiges Add-on. Im Provider ist es standardmäßig aktiviert und kann nach der Aktivierung nicht mehr deaktiviert werden. Wenn Sie es nicht wünschen, setzen Sie vulnerability_scanning = false beim Erstellen der Registry.
Garbage Collection ist standardmäßig deaktiviert. Das Löschen eines Images oder Tags gibt keinen Speicherplatz frei: Die Registry versteckt die gelöschten Einträge, aber die Daten verbleiben auf der Festplatte, bis Garbage Collection ausgeführt wird. Der garbage_collection_schedule-Block setzt einen wöchentlichen Lauf mit days und einem time fest.
Während der Garbage Collection ist die Registry schreibgeschützt, und Sie können keine Images hochladen. Planen Sie den Lauf außerhalb Ihrer Release-Zeiten ein, da andernfalls ein CI-Push während der Ausführung fehlschlägt.
1.3 Einschränkung des Netzwerkzugriffs und Lesen des Hostnamens
resource "ionoscloud_container_registry" "taskboard" {
# ... arguments from Section 1
api_subnet_allow_list = ["203.0.113.10/32"]
}
data "ionoscloud_container_registry" "taskboard" {
id = ionoscloud_container_registry.taskboard.id
}
output "registry_hostname" {
value = data.ionoscloud_container_registry.taskboard.hostname
}
Die Registry ist über das öffentliche Internet erreichbar. api_subnet_allow_list bestimmt, welche Subnetz-CIDRs sich verbinden dürfen; eine leere oder nicht gesetzte Liste bedeutet, dass keine Einschränkung besteht. Die Antwort bei der Erstellung enthält keinen Hostnamen, da der Host noch nicht zugewiesen wurde. Lesen Sie daher hostname aus der Datenquelle, sobald die Registry läuft.
2. Tokens und Docker Login
Docker-Clients authentifizieren sich mit Registry-Tokens. Es gibt keine öffentlichen Repositories und keinen nicht authentifizierten Zugriff. Ein Token hat einen Namen, ein optionales Ablaufdatum, einen Status und einen oder mehrere Scopes.
2.1 Tokens als Code
resource "ionoscloud_container_registry_token" "ci_push" {
registry_id = ionoscloud_container_registry.taskboard.id
name = "taskboard-ci-push"
status = "enabled"
save_password_to_file = "ci-push.pass"
scopes {
name = "taskboard/*"
type = "repository"
actions = ["pull", "push"]
}
}
resource "ionoscloud_container_registry_token" "k8s_pull" {
registry_id = ionoscloud_container_registry.taskboard.id
name = "taskboard-k8s-pull"
status = "enabled"
save_password_to_file = "k8s-pull.pass"
scopes {
name = "taskboard/*"
type = "repository"
actions = ["pull"]
}
}
Ein Scope kombiniert ein type, ein name und actions. Bei der Art repository ist der Name der Repository-Pfad, auf den der Token zugreifen darf, und * funktioniert als Platzhalter. Die Aktionen sind pull, push und delete. Die Art registry erstellt einen Token, der die Repositories der Registry auflisten kann.
Erstellen Sie einen Token pro Verbraucher. Der CI-Token schiebt; der Cluster-Token in Einheit 3.2 zieht nur. Wenn ein Cluster-Token geleakt, kann niemand damit Ihre Images überschreiben.
2.2 Token-Regeln, die Ihren Code beeinflussen
| Regel | Wert |
|---|---|
| Namenslänge | 3 bis 63 Zeichen, alphanumerisch und Bindestriche, beginnt mit a-z |
| Namensänderung | Nicht möglich; name ist unveränderlich |
| Ablaufdatum | Mindestens 1 Stunde in der Zukunft, ISO 8601-Zeitstempel |
| Beim Ablauf | Der Token wird gelöscht, nicht deaktiviert |
| Push-Aktion | Erfordert auch die Pull-Aktion |
| Passwort | Wird nur einmal zurückgegeben, bei der Erstellung |
| Doppelte Name | 409 Conflict |
Das Passwort ist der kritische Teil. Der Anbieter dokumentiert save_password_to_file als den einzigen Weg, den Token zu erhalten, und es funktioniert nur bei der Erstellung. Verschieben Sie die Datei direkt nach apply in Ihren Secret Store und löschen Sie sie lokal. Wenn Sie das Passwort verlieren, erstellen Sie einen neuen Token.
2.3 Anmeldung mit Docker
export CR_HOST="$(terraform output -raw registry_hostname)"
export CR_USERNAME="taskboard-ci-push"
docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin < ci-push.pass
docker login benötigt drei Werte: den Hostnamen der Registry, den Benutzernamen und das Passwort. Nehmen Sie den Benutzernamen aus dem credentials der Token-Antwort; in den API-Beispielen entspricht er dem Token-Namen. Übergeben Sie das Passwort über --password-stdin, damit es niemals in Ihrer Shell-Historie oder Prozessliste erscheint.
Sie können auch ein Token über die API erstellen. Die Antwort enthält credentials.username und credentials.password:
curl --silent --request POST \
"https://api.ionos.com/containerregistries/registries/$REGISTRY_ID/tokens" \
--header "Authorization: Bearer $IONOS_TOKEN" \
--header "Content-Type: application/json" \
--data '{"properties": {"name": "taskboard-hotfix", "expiryDate": null,
"scopes": [{"name": "taskboard/*", "actions": ["pull", "push"], "type": "repository"}]}}' \
| jq -r '.properties.credentials.password' > hotfix.pass
Beachten Sie die beiden unterschiedlichen Zugangsdaten: Das Bearer-Token der Cloud API (IONOS_TOKEN) verwaltet Register und Token; das Registry-Token meldet sich bei Docker an.
3. Mehrstufige Dockerfiles für TaskBoard
Ein mehrstufiger Build kompiliert in einem Image und kopiert nur das Ergebnis in ein kleines Laufzeit-Image. Build-Tools, Caches und Quelldateien bleiben aus dem ausgelieferten Inhalt heraus.
3.1 Der API-Dienst
# api/Dockerfile
FROM python:3.12-slim AS build
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
FROM python:3.12-slim
WORKDIR /app
COPY --from=build /install /usr/local
COPY src/ ./src/
RUN useradd --uid 10001 taskboard
USER 10001
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
Die erste Stufe installiert die Abhängigkeiten in /install; die zweite Stufe kopiert nur diesen Baum und den Quellcode. Der Container wird als Benutzer ohne Root-Rechte ausgeführt, worauf Sie in Einheit 3.2 zurückgreifen.
3.2 Das Web-Frontend
# web/Dockerfile
FROM node:22-alpine AS build
WORKDIR /web
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM nginxinc/nginx-unprivileged:alpine
COPY --from=build /web/dist /usr/share/nginx/html
EXPOSE 8080
Das Frontend-Image enthält statische Dateien und einen Webserver, aber nichts von Node.js. Kleinere Images werden schneller übertragen und enthalten weniger Pakete, die gepatcht werden müssen. Wenn Sie die Schwachstellenanalyse aktiviert haben, ist jedes Paket, das Sie aus der Laufzeitstufe weglassen, eine Quelle für Befunde weniger.
4. Das Image-Pipeline-Muster
Jeder Build von TaskBoard folgt denselben vier Schritten: Build, Taggen mit dem Git-SHA, Pushen und Übergabe der Referenz an die Deployment.
4.1 Taggen mit dem Commit-SHA
SHA="$(git rev-parse --short=12 HEAD)"
docker build -t "$CR_HOST/taskboard/api:$SHA" api/
docker build -t "$CR_HOST/taskboard/web:$SHA" web/
docker push "$CR_HOST/taskboard/api:$SHA"
docker push "$CR_HOST/taskboard/web:$SHA"
Ein SHA-Tag ist nach Konvention unveränderlich: ein Commit, ein Image. Ein sich änderndes Tag wie latest macht einen Rollback in Einheit 3.3 zu einer Vermutung, da der Cluster nicht erkennen kann, welchen Build er ausführt. Repository-Namen wie taskboard/api entsprechen dem taskboard/*-Umfang aus Abschnitt 2.1.
4.2 Ein Digest an die Bereitstellung übergeben
DIGEST="$(docker inspect --format '{{index .RepoDigests 0}}' "$CR_HOST/taskboard/api:$SHA")"
echo "$DIGEST" # <registry-hostname>/taskboard/api@sha256:...
Der Digest fixiert den genauen Bildinhalt. Ihr Deployment-Manifest in Einheit 3.2 kann entweder den SHA-Tag oder den Digest verwenden; die Pipeline in Einheit 3.3 schreibt ihn in das Manifest.
4.3 Ratenbeschränkungen für Build-Server
Die Registry begrenzt jeden Client:
| Metrik | Limit | Beschreibung |
|---|---|---|
| Maximale gleichzeitige Verbindungen pro Client | 100 | Die höchste Anzahl an gleichzeitigen TCP-Verbindungen, die ein einzelner Client (Beispiel: ein Build-Server oder Clusterknoten) für Private Container Registry-Operationen, wie das Herunterladen von Ebenen, aufrechterhalten kann. Wird dieses Limit überschritten, wird die Verbindung abgelehnt. |
| Maximale Anfragen pro Sekunde (RPS) pro Client | 60 | Die maximale Anzahl an API-Anfragen (Beispiel: Abrufe, Token-Authentifizierungsanfragen, Prüfungen auf das Vorhandensein von Ebenen), die ein einzelner Client pro Sekunde an die Private Container Registry senden kann. Übermäßige Anfragen führen zu einem 429 (Too Many Requests)-Fehler. |
Ein geteilter Build-Server, der viele Bilder parallel hochlädt, kann diese Limits erreichen. Beschränken Sie parallele Uploads pro Runner und wiederholen Sie einen 429 mit Backoff, wie Sie es für die Cloud API in Einheit 1.1 gelernt haben.
5. CI-Integration
Die Pipeline benötigt drei Werte als Secrets: den Hostnamen, den Benutzernamen und das Passwort des Push-Tokens. Keines dieser Werte darf jemals in das Repository eingecheckt werden.
5.1 GitHub Actions
- name: Log in to the registry
env:
CR_HOST: ${{ secrets.CR_HOST }}
CR_USERNAME: ${{ secrets.CR_USERNAME }}
CR_PASSWORD: ${{ secrets.CR_PASSWORD }}
run: echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin
5.2 GitLab CI
before_script:
- echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin
In GitLab definieren Sie CR_PASSWORD als maskierte, geschützte CI/CD-Variable, damit sie nur auf geschützten Branches verfügbar ist. Die vollständigen Workflows für beide Systeme folgen in Einheit 3.3.
Wenn Sie api_subnet_allow_list festlegen, muss die Egress-Adresse des Runners in der Liste enthalten sein. Hosted Runners können sich ändernde Adressen verwenden. Führen Sie entweder selbst gehostete Runner mit einer bekannten Adresse aus oder lassen Sie die Liste leer und verlassen Sie sich auf den Token.
API-Referenz-Schnellkarte
Wichtige API-Endpunkte für das Thema dieser Einheit:
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/locations |
Die Standorte auflisten, an denen Sie eine Registry erstellen können |
POST |
/registries |
Eine Registry erstellen |
GET |
/registries/{registryId} |
Eine Registry abrufen, einschließlich hostname und Status |
POST |
/registries/{registryId}/tokens |
Ein Token erstellen; die Antwort enthält das Passwort einmalig |
DELETE |
/registries/{registryId}/repositories/{repositoryName} |
Ein Repository löschen (Name URL-kodieren, zum Beispiel taskboard%2Fapi) |
Basis-URL: https://api.ionos.com/containerregistries
Authentifizierung: Authorization: Bearer <token>
Code-Labor
Ziel: Erstellen Sie eine Private Container Registry mit einem Push-Token und einem Pull-Token, bauen Sie die API- und Web-Images von TaskBoard mit mehrstufigen Dockerfiles, schieben Sie diese mit Git-SHA-Tags hoch und überprüfen Sie einen Pull mit dem Token mit nur Lesezugriff.
Voraussetzungen:
- IONOS CLOUD-Konto mit einem API-Token in
IONOS_TOKEN - Lokal installierte Tools: Terraform, Docker und
jq - Ein Git-Repository mit den Ordnern
api/undweb/von TaskBoard sowie den Dockerfiles aus Abschnitt 3
Schritt 1: registry.tf schreiben
Kopieren Sie das Registry-Resource aus Abschnitt 1, die Datenquelle und die Ausgabe aus Abschnitt 1.3 (ohne api_subnet_allow_list) sowie beide Tokens aus Abschnitt 2.1. Verwenden Sie Ihren eigenen Namenszusatz. Fügen Sie den Provider-Block aus Einheit 1.2 und eine weitere Ausgabe hinzu:
output "registry_id" {
value = ionoscloud_container_registry.taskboard.id
}
terraform init
Erwartete Ausgabe:
Terraform has been successfully initialized!
Schritt 2: Anwenden
terraform apply
Erwartete Ausgabe:
ionoscloud_container_registry.taskboard: Creation complete after ...
ionoscloud_container_registry_token.ci_push: Creation complete after ...
ionoscloud_container_registry_token.k8s_pull: Creation complete after ...
Outputs:
registry_hostname = "<registry-hostname>"
Schritt 3: Anmelden mit dem Push-Token
export CR_HOST="$(terraform output -raw registry_hostname)"
docker login "$CR_HOST" --username taskboard-ci-push --password-stdin < ci-push.pass
Erwartete Ausgabe:
Login Succeeded
Schritt 4: Beide Images erstellen und hochladen
SHA="$(git rev-parse --short=12 HEAD)"
for svc in api web; do
docker build -t "$CR_HOST/taskboard/$svc:$SHA" "$svc/"
docker push "$CR_HOST/taskboard/$svc:$SHA"
done
Erwartete Ausgabe:
...
<sha>: digest: sha256:... size: ...
Schritt 5: Die Repositories über die API auflisten
REGISTRY_ID="$(terraform output -raw registry_id)"
curl --silent "https://api.ionos.com/containerregistries/registries/$REGISTRY_ID/repositories" \
--header "Authorization: Bearer $IONOS_TOKEN" | jq -r '.items[].properties.name'
Erwartete Ausgabe:
taskboard/api
taskboard/web
Schritt 6: Das nur-Abholungs-Token überprüfen
docker logout "$CR_HOST"
docker login "$CR_HOST" --username taskboard-k8s-pull --password-stdin < k8s-pull.pass
docker pull "$CR_HOST/taskboard/api:$SHA"
docker push "$CR_HOST/taskboard/api:$SHA"
Erwartete Ausgabe:
Login Succeeded
...
Status: Image is up to date for <registry-hostname>/taskboard/api:<sha>
...
(the push fails with an access denied error)
Prüfliste:
- [ ] Das Registry und beide Tokens wurden von
terraform applyerstellt - [ ] Beide Images befinden sich im Registry unter
taskboard/mit dem Git-SHA-Tag - [ ] Das Pull-Token kann ziehen, aber nicht schieben
- [ ] Kein Token-Passwort wurde in Git committet
Aufräumarbeiten:
Bewahren Sie das Registry und die Datei k8s-pull.pass auf, wenn Sie mit Einheit 3.2 fortfahren. Andernfalls:
terraform destroy -auto-approve
rm -f ci-push.pass k8s-pull.pass
Häufige Fehler
Fehler von Entwicklerinnen und Entwicklern, die bei dem Thema dieser Einheit zu vermeiden sind:
-
Push-Token ohne Pull
- Problem:
docker pushschlägt mit einem Fehler „Zugriff verweigert“ fehl, obwohl das Token diepush-Aktion besitzt. - Ursache: Die Push-Aktion erfordert die Pull-Aktion. Docker prüft vor dem Hochladen auf vorhandene Ebenen.
- Lösung:
actions = ["pull", "push"]im Token-Bereich festlegen.
- Problem:
-
Verlorenes Token-Passwort
- Problem: Nach einem frischen Checkout ist
terraform applyerfolgreich, aber niemand hat das Passwort für das CI-Token. - Ursache: Das Passwort wird nur einmal, bei der Erstellung, zurückgegeben, und
save_password_to_filefunktioniert nur bei der Erstellung. - Lösung: Die Datei sofort im Secret Store ablegen. Zur Rotation das Token ersetzen:
terraform apply -replace=ionoscloud_container_registry_token.ci_push, dann das CI-Secret aktualisieren.
- Problem: Nach einem frischen Checkout ist
-
CI-Push schlägt während der Müllsammlung oder von einer blockierten Adresse fehl
- Problem: Eine nächtliche Pipeline schlägt jeden Sonntag bei
docker pushfehl, oder jeder Push von gehosteten Runnern schlägt fehl. - Ursache: Die Registry ist während der Müllsammlung nur lesbar, und
api_subnet_allow_listblockiert Adressen außerhalb der Liste. - Lösung:
garbage_collection_scheduleaußerhalb der Build-Zeiten verschieben und die Ausgangsadresse des Runners in der Freigabeliste belassen oder die Liste leer lassen.
- Problem: Eine nächtliche Pipeline schlägt jeden Sonntag bei
Zusammenfassung
Sie können TaskBoard jetzt eine private Bildlieferkette einrichten. Terraform erstellt die Private Container Registry in de/fra und ein Token mit begrenztem Geltungsbereich pro Verbraucher. Mehrstufige Dockerfiles halten die Bilder für die API und das Frontend klein, jedes Bild trägt den Git SHA seines Commits, und CI-Systemen melden sich mit einem Token aus ihrem Secret Store an.
Wichtige Punkte:
nameundlocationeines Registry sind unveränderlich; der Name ist global eindeutig- Die Schwachstellenanalyse ist im Anbieter standardmäßig aktiviert; setzen Sie
vulnerability_scanning = falsebei der Erstellung, wenn Sie diese nicht wünschen - Docker-Clients melden sich mit Registry-Tokens an; ein Token-Passwort wird nur einmal zurückgegeben
- Verwenden Sie separate Tokens für Push (CI, mit Pull und Push) und Pull (Cluster)
- Vergeben Sie den Git SHA als Tag für Bilder; beachten Sie die pro Client geltenden Grenzen von 100 Verbindungen und 60 Anfragen pro Sekunde
Wichtige Begriffe:
- Registry-Token: Eine Anmeldeinformation mit Berechtigungen, die die Docker CLI verwendet, um sich bei der Registry anzumelden
- Berechtigung (Scope): Eine Kombination aus Typ, Repository-Name (mit
*Platzhalter) und Aktionen (pull,push,delete) - Mehrstufiger Build: Ein Dockerfile mit einer Build-Stufe und einer minimalen Laufzeitstufe, die nur das Build-Ergebnis erhält
- Bild-Digest: Der
sha256Inhalts-Hash, der ein exaktes Bild festlegt, unabhängig von Tags - Müllsammlung (Garbage Collection): Der geplante Lauf, der Speicherplatz von gelöschten Bildern freigibt; die Registry ist währenddessen nur lesbar
Nächste Schritte
Weiter lernen: Einheit 3.2: Kubernetes-Bereitstellung und Betrieb
Verwandte Themen: