13 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • Eine Private Container Registry und deren Zugriffstokens mit `ionoscloud_container_registry` und `ionoscloud_container_registry_token` provisionieren
  • Die Docker-CLI mit einem Token mit eingeschränktem Geltungsbereich gegenüber der Registry authentifizieren und Images pushen und pullen
  • Produktionsimages für die API und das Web-Frontend von TaskBoard mit mehrstufigen Dockerfiles erstellen
  • Eine Image-Pipeline implementieren, die jedes Image mit dem Git-Commit-SHA taggt und in die Registry pushen
  • CI-Zugangsdaten für GitHub Actions und GitLab CI konfigurieren, die sich bei der Registry anmelden, ohne das Token offenzulegen

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/ und web/ 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 apply erstellt
  • [ ] 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:

  1. Push-Token ohne Pull

    • Problem: docker push schlägt mit einem Fehler „Zugriff verweigert“ fehl, obwohl das Token die push-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.
  2. Verlorenes Token-Passwort

    • Problem: Nach einem frischen Checkout ist terraform apply erfolgreich, 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_file funktioniert 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.
  3. 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 push fehl, oder jeder Push von gehosteten Runnern schlägt fehl.
    • Ursache: Die Registry ist während der Müllsammlung nur lesbar, und api_subnet_allow_list blockiert Adressen außerhalb der Liste.
    • Lösung: garbage_collection_schedule außerhalb der Build-Zeiten verschieben und die Ausgangsadresse des Runners in der Freigabeliste belassen oder die Liste leer lassen.

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:

  • name und location eines Registry sind unveränderlich; der Name ist global eindeutig
  • Die Schwachstellenanalyse ist im Anbieter standardmäßig aktiviert; setzen Sie vulnerability_scanning = false bei 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 sha256 Inhalts-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: