Einheit 3.1: Container-Registrierung und Bildpipelines

Einführung

Sie stehen kurz davor, TaskBoards API-Dienst und Web-Frontend zu containerisieren, und benötigen ein Register, um die Images darauf zu übertragen, bevor Managed Kubernetes sie abrufen kann. Das IONOS Container-Register bietet Ihnen ein oder mehrere dedizierte, authentifizierte Register, die das Docker-Register-HTTP-API-V2 sprechen und jedes OCI-konforme Artefakt akzeptieren. Alles, was Sie damit tun, wie Bereitstellung, Token-Erstellung, Anmeldung, Übertragung und Müllsammlung, wird durch Terraform, das REST-API und die Docker-CLI gesteuert.

Diese Einheit beginnt auf der Code-Ebene. Sie werden ein Register als Infrastructure as Code bereitstellen, einen gültigen Token prägen, Docker authentifizieren und die Build-Tag-Push-Pipeline aufbauen, auf die das REST von Modul 3 angewiesen ist. Zwei IONOS-spezifische Einschränkungen prägen jedes Beispiel hier: Die Authentifizierung erfolgt nur über Token und nicht über rollenbasierte Zugriffskontrolle und es gibt keine pro-Repository-ACLs, und der Registrierungs-Hostname existiert nicht, bis das Register den Running-Zustand erreicht. Beides wird Sie in der CI beißen, wenn Sie sie ignorieren, daher sind sie in die Code-Muster unten integriert.

1. Bereitstellung des Registries mit Terraform

Das Registry ist eine erstklassige Terraform-Ressource. Sie erklären einen Namen und einen Standort, wenden sie an und warten auf die asynchrone Bereitstellung, bis der Hostname zugewiesen wird. Die name und location sind nach der Erstellung unveränderlich, daher ist die Auswahl ein einwegiger Entscheidungsprozess pro Registry.

Der Registrierungsname muss höchstens 63 Zeichen lang sein. Wenn Sie versuchen, ein Registry mit einem Namen zu erstellen, der bereits über die Plattform vergeben ist, gibt das API HTTP 409 Conflict mit der Meldung already exists: name is not available zurück. Behandeln Sie den Namen als globalen Handle und nicht als pro-Konto-Handle und fügen Sie ihn mit Ihrem Projekt vor, um Kollisionen zu vermeiden.

1.1 Die ionoscloud_container_registry-Ressource

Der Standort muss ein unterstützter Container-Registrierungsstandort sein. Das Container-Registry ist in de/fra (DE/FRA) verfügbar, daher ist Ihr location-Wert de/fra.

terraform {
  required_providers {
    ionoscloud = {
      source  = "ionos-cloud/ionoscloud"
      version = ">= 6.0.0"
    }
  }
}

provider "ionoscloud" {
  # token read from IONOS_TOKEN env var
}

resource "ionoscloud_container_registry" "taskboard" {
  name     = "taskboard-prod"
  location = "de/fra"

  garbage_collection_schedule {
    days = ["Saturday", "Sunday"]
    time = "19:30:00+00:00"
  }
}

output "registry_hostname" {
  value = ionoscloud_container_registry.taskboard.hostname
}

Die hostname-Ausgabe folgt dem Muster {registry-name}.cr.{location-with-dash}.ionos.com. Sie ist leer, bis das Registry den Zustand Running erreicht, daher muss jeder nachgelagerte Schritt, der sie liest, nach dem vollständigen Abschluss von apply ausgeführt werden. Das Registry hat nur zwei Lebenszykluszustände, New und Running, und nur Running ist verwendbar.

1.2 Bereitstellung über das REST API

Wenn Sie außerhalb von Terraform bereitstellen, wird das Registry mit einem POST zum Registrierungsendpunkt erstellt. Die gleichen garbageCollectionSchedule-, location- und name-Eigenschaften gelten.

curl --location \
  --request POST 'https://api.ionos.com/containerregistries/registries' \
  --header "Authorization: Bearer ${IONOS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "properties": {
      "garbageCollectionSchedule": {
        "days": ["Saturday", "Sunday"],
        "time": "19:30:00+00:00"
      },
      "location": "de/fra",
      "name": "taskboard-prod"
    }
  }'

Die 201-Antwort enthält keinen Hostnamen, da der Host noch nicht zugewiesen ist. Pollen Sie GET /containerregistries/registries/{registryId}, bis der Zustand Running ist, bevor Sie den Hostnamen lesen. Listenaufrufe sind tokenbasiert paginiert: Übergeben Sie limit als Abfrageparameter und folgen Sie nextPageToken, um große Sammlungen zu durchlaufen.

2. Token und Authentifizierung

Die Authentifizierung ist ausschließlich tokenbasiert docker login . Es gibt kein RBAC , keine Team-Repositorys und keinen anonymen oder öffentlichen Repository-Zugriff. Ein Token ist die Zugriffseinheit, und Sie können es pro Registry oder pro Repository-Pfad mit einem Satz von zulässigen Aktionen umschreiben.

2.1 Erstellen eines Tokens mit Terraform

Ein Token hat einen Namen, einen Status, ein optionales Ablaufdatum und einen oder mehrere Bereiche. Jeder Bereich hat einen Typ von Registry oder Repository , einen Pfad und eine Aktionenliste, die aus pull , push und delete gezogen wird. Der Tokenname muss 3 bis 63 Zeichen lang sein, mit einem Kleinbuchstaben beginnen, mit einem alphanumerischen Zeichen enden und nur alphanumerische Zeichen und Bindestriche enthalten, und er ist nach der Erstellung unveränderlich.

resource "ionoscloud_container_registry_token" "ci_push" {
  container_registry_id = ionoscloud_container_registry.taskboard.id
  name                  = "ci-push"
  status                = "enabled"

  # minimum expiry is 1 hour in the future; on expiry the token is DELETED
  expiry_date = "2027-01-01T00:00:00Z"

  scopes {
    type    = "Repository"
    name    = "taskboard/*"
    actions = ["push", "pull"]
  }
}

output "ci_push_password" {
  value     = ionoscloud_container_registry_token.ci_push.password
  sensitive = true
}

Zwei Verhaltensweisen sind für die Automatisierung wichtig. Das Token-Passwort wird nur einmal angezeigt, daher sollten Sie es sofort aus dem Terraform -Zustand oder der API -Antwort erfassen und in Ihrem Geheimnis-Manager speichern. Wenn das Ablaufdatum erreicht ist, wird das Token gelöscht, nicht deaktiviert, daher muss ein Rotationsjob das Ersatztoken erstellen, bevor das alte abläuft, oder Ihre Pipeline verliert den Zugriff während der Bereitstellung.

2.2 Erstellen eines Tokens über die API und Anmelden

Der Token-Endpunkt ist POST /containerregistries/registries/{registryId}/tokens . Token gibt es in zwei Typen, ein permanentes Registry-Zugriffstoken und ein temporäres, das durch expiryDate begrenzt ist. Die Mindestablauffrist beträgt eine Stunde in der Zukunft.

curl --location \
  --request POST "https://api.ionos.com/containerregistries/registries/${REGISTRY_ID}/tokens" \
  --header "Authorization: Bearer ${IONOS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "properties": {
      "name": "ci-push",
      "status": "enabled",
      "scopes": [
        { "type": "Repository", "name": "taskboard/*", "actions": ["push", "pull"] }
      ]
    }
  }'

Die Antwort enthält die Anmeldeinformationen einmal. Verwenden Sie den Tokennamen als Benutzernamen und das Token-Passwort als Passwort für docker login gegen den Registry-Hostnamen.

echo "${CR_TOKEN_PASSWORD}" | docker login taskboard-prod.cr.de-fra.ionos.com \
  --username ci-push \
  --password-stdin

Ein Token kann einen von drei Zuständen haben: enabled , disabled oder deleted . Deaktivieren Sie ein Token, um den Zugriff sofort zu widerrufen, ohne es zu löschen; löschen Sie es, wenn es nicht mehr benötigt wird.

2.3 Auswahl der Methode zum Erstellen und Verwenden von Anmeldeinformationen

Die folgende Tabelle vergleicht die Zugriffspfade für Registry-Anmeldeinformationen, damit Sie den richtigen auswählen können, je nach Workflow.

Da Bereiche pro Registry oder pro Repository-Pfad sind und es kein RBAC gibt, sollten Sie ein Token pro CI-Pipeline und eines pro Entwickler erstellen, anstatt ein einzelnes breites Token zu teilen. CI-Tokens sollten auf push plus pull auf den Repository-Pfaden beschränkt werden, die sie besitzen, und lesbare Bereitstellungstoken sollten auf pull beschränkt werden.

3. Erstellung und Übertragung von Images

Mit einem laufenden Registry und einem Token in der Hand ist der Image-Workflow standardmäßig gegen den Registry-Hostname gerichtet. Die Disziplin, die es produktionssicher macht, sind Multi-Stage-Builds für kleine Images und unveränderliche Git-SHA-Tags für nachverfolgbare Deployments.

3.1 Multi-Stage-Dockerfile für das TaskBoard API

Ein Multi-Stage-Build kompiliert oder installiert Abhängigkeiten in einer fetten Builder-Stage und kopiert nur die Laufzeit-Artifakte in ein schlankes Endimage. Kleinere Images werden auf Kubernetes schneller geladen und enthalten weniger Pakete, die der Vulnerabilitäts-Scanner markieren muss.

FROM python:3.12 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --prefix=/install --no-cache-dir -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /install /usr/local
COPY . .
EXPOSE 8080
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "taskboard.api:app"]

3.2 Tag mit dem Git SHA und Übertragung

Jeden Build mit dem unveränderlichen Git SHA taggen, damit ein deploytes Image auf einen exakten Commit zurückverweisen kann. Ein latest-Tag ist als Convenience-Zeiger in Ordnung, aber nie davon deployen; deployen Sie von dem SHA.

REGISTRY=taskboard-prod.cr.de-fra.ionos.com
GIT_SHA=$(git rev-parse --short HEAD)

docker build -t "${REGISTRY}/taskboard/api:${GIT_SHA}" \
             -t "${REGISTRY}/taskboard/api:latest" .

docker push "${REGISTRY}/taskboard/api:${GIT_SHA}"
docker push "${REGISTRY}/taskboard/api:latest"

Das Pipeline-Muster ist Build, Tag mit dem Git SHA, Übertragung auf die Registry, dann Referenzierung des SHA-Tags im Kubernetes-Manifest (in Einheit 3.2 behandelt). Beachten Sie, dass ein Token, das push gewährt, auch pull benötigt: Das Übertragen eines Images erfordert das Lesen vorhandener Schichten, sodass ein push-only-Umfang unzureichend ist und ein push-Token auch pull tragen muss.

4. Müllsammlung und Schwachstellenscanning

Zwei Registrierfunktionen laufen serverseitig und sind es wert, frühzeitig konfiguriert zu werden. Die Müllsammlung gewinnt Speicherplatz von nicht referenzierten Schichten zurück, und der Schwachstellenscanning bringt CVEs in Ihren gepushten Artefakten ans Licht.

4.1 Müllsammlung

Die Müllsammlung befreit den Speicherplatz, der von Schichtendaten belegt ist, die nicht mehr von einem Tag referenziert werden. Sie ist standardmäßig deaktiviert, da der richtige Zeitplan von Ihrem Push- und Löschrythmus abhängt, sodass Sie ihn explizit festlegen. Sie haben ihn bereits im Terraform-Ressourcen in Abschnitt 1.1 über den garbage_collection_schedule-Block mit days und einem time konfiguriert.

garbage_collection_schedule {
  days = ["Saturday", "Sunday"]
  time = "19:30:00+00:00"
}

Während der Müllabfuhr befindet sich das Register im schreibgeschützten Zustand: Pulls funktionieren weiterhin, aber Pushs werden bis zum Abschluss des Laufs blockiert, daher sollten Sie es für ein Zeitfenster mit geringem Datenverkehr planen, um die Unterbrechung von CI/CD-Pushs und -Deployments zu vermeiden. Beachten Sie, dass das Docker-Registrierungs-Modul V2 von API nicht ein ganzes Repository löschen kann. Um ein Repository zu entfernen, müssen Sie das IONOS-Container-Registrierungs-Modul von API direkt mit DELETE /containerregistries/registries/{id}/repositories/{url-encoded-name} aufrufen, und der Repository-Name in der URL muss URL-kodiert sein, beispielsweise wird taskboard/api zu taskboard%2Fapi, oder der Aufruf gibt 404 zurück.

4.2 Schwachstellen-Scanning

Schwachstellen-Scanning analysiert die hochgeladenen Artefakte auf bekannte CVEs. Es handelt sich um eine Add-on-Funktion, und sobald sie in einem Register aktiviert ist, kann sie nicht mehr deaktiviert werden, daher sollten Sie sie bewusst aktivieren. Die Scan-Ergebnisse werden pro Artefakt und pro Repository gemeldet, einschließlich der Erkenntnisse, die bekannte Korrekturen haben, sodass Sie die Förderung eines Bildes aufgrund der Scan-Ergebnisse in der CI behindern können.

Behandeln Sie den Scan als Qualitäts-Tor: Nach dem Push-Schritt sollten Sie die Scan-Ergebnisse für das SHA-getaggte Artefakt abfragen und die Pipeline fehlschlagen lassen, wenn die Erkenntnisse Ihren Schwellenwert überschreiten, bevor der Deploy-Schritt fortgesetzt wird.

5. CI-Integration

In CI führen Sie kein interaktives docker login aus. Sie speichern die Token-Anmeldedaten als Pipeline-Geheimnisse und übergeben sie an docker login --password-stdin. Der Registrierungs-Hostname, der Token-Name und das Token-Passwort sind die drei Werte, die Ihre Pipeline benötigt.

5.1 GitHub Actions

Speichern Sie CR_HOSTNAME, CR_USERNAME und CR_PASSWORD als Repository- oder Umgebungsgeheimnisse, dann melden Sie sich an und pushen Sie im Workflow.

name: build-and-push
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Log in to IONOS Container Registry
        run: |
          echo "${{ secrets.CR_PASSWORD }}" | docker login "${{ secrets.CR_HOSTNAME }}" \
            --username "${{ secrets.CR_USERNAME }}" --password-stdin

      - name: Build and push
        run: |
          SHA=$(git rev-parse --short HEAD)
          IMG="${{ secrets.CR_HOSTNAME }}/taskboard/api:${SHA}"
          docker build -t "$IMG" .
          docker push "$IMG"

5.2 GitLab CI

Die äquivalente GitLab-Pipeline verwendet CI/CD-Variablen für die gleichen drei Werte und den Docker-in-Docker-Dienst für den Build.

build-and-push:
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_HOST: tcp://docker:2376
  script:
    - echo "$CR_PASSWORD" | docker login "$CR_HOSTNAME" --username "$CR_USERNAME" --password-stdin
    - SHA=$(echo "$CI_COMMIT_SHA" | cut -c1-7)
    - docker build -t "$CR_HOSTNAME/taskboard/api:$SHA" .
    - docker push "$CR_HOSTNAME/taskboard/api:$SHA"
  only:
    - main

Da Token das einzige Anmeldemodell sind, drehen Sie das CI-Token nach einem Zeitplan und aktualisieren Sie das Geheimnis schrittweise. Jeder Client ist auf 60 Anfragen pro Sekunde und 100 gleichzeitige Verbindungen begrenzt, was für eine einzelne Pipeline großzügig ist, aber bei der Ausführung paralleler Matrix-Builds, die alle gleichzeitig pushen, beachtet werden sollte.

API Referenz-Quick-Card

Wichtige API-Endpunkte für das Container-Registrierungssystem:

Basis-URL: https://api.ionos.com Authentifizierung: Authorization: Bearer <token>

Code-Labor

Ziel: Ein Container-Registrierung bereitstellen, ein scopiertes Token prägen, das TaskBoard-API-Bild erstellen und es mit einem Git-SHA-Tag pushen.

Voraussetzungen:

• IONOS Cloud-Konto mit API-Token als IONOS_TOKEN exportiert
• Terraform und Docker lokal installiert
• Ein Dockerfile für das TaskBoard-API (siehe Abschnitt 3.1)

Schritt 1: Registrierung und Token bereitstellen

export IONOS_TOKEN="your-api-token"
terraform init
terraform apply -auto-approve

Erwartete Ausgabe:

ionoscloud_container_registry.taskboard: Creation complete
Outputs:
registry_hostname = "taskboard-prod.cr.de-fra.ionos.com"

Schritt 2: Registrierungs-Hostname und Token-Passwort lesen

REGISTRY=$(terraform output -raw registry_hostname)
CR_PASSWORD=$(terraform output -raw ci_push_password)
echo "$REGISTRY"

Erwartete Ausgabe:

taskboard-prod.cr.de-fra.ionos.com

Schritt 3: Anmelden bei der Registrierung

echo "$CR_PASSWORD" | docker login "$REGISTRY" --username ci-push --password-stdin

Erwartete Ausgabe:

Login Succeeded

Schritt 4: Bild erstellen

docker build -t "${REGISTRY}/taskboard/api:$(git rev-parse --short HEAD)" .

Erwartete Ausgabe:

=> exporting to image
=> => naming to taskboard-prod.cr.de-fra.ionos.com/taskboard/api:a1b2c3d

Schritt 5: Bild pushen

docker push "${REGISTRY}/taskboard/api:$(git rev-parse --short HEAD)"

Erwartete Ausgabe:

a1b2c3d: digest: sha256:... size: 1786

Schritt 6: Überprüfen via dem API

REGISTRY_ID=$(terraform output -raw registry_id)
curl -s --request GET \
  "https://api.ionos.com/containerregistries/registries/${REGISTRY_ID}/repositories" \
  --header "Authorization: Bearer ${IONOS_TOKEN}" | jq '.items[].id'

Erwartete Ausgabe:

"taskboard/api"

Validierungs-Checkliste:

• [ ] Registrierung erreicht Running und einen Hostnamen exponiert
• [ ] docker login gab Login Succeeded zurück
• [ ] Bild mit einem Git-SHA-Tag gepusht und über die Repositories des API sichtbar

Aufräumen:

terraform destroy -auto-approve

Häufige Fehlerquellen

Entwicklerfehler, die bei der Arbeit mit dem Container-Registrierungssystem vermieden werden sollten:

1. Lesen des Hostnamens, bevor das Registrierungssystem gestartet ist

   • Problem: Die Pipeline für den docker login-Code schlägt mit einem DNS-Auflösungsfehler fehl, direkt nachdem der terraform apply-Code ausgeführt wurde.
   • Warum es passiert: Der Hostname ist leer, bis das Registrierungssystem den New-Zustand verlässt und den Running-Zustand erreicht. Wenn der Hostname zu früh gelesen wird, ergibt sich ein leerer oder nicht auflösbarer Wert.
   • Lösung: Die Anmeldung sollte an den Running-Zustand gekoppelt werden. Das Registrierungssystem sollte bis zum Bereitschaftsstatus abgefragt werden, bevor die Anmeldung durchgeführt wird:

   until [ "$(curl -s -H "Authorization: Bearer $IONOS_TOKEN" \
     https://api.ionos.com/containerregistries/registries/$REGISTRY_ID \
     | jq -r '.metadata.state')" = "Running" ]; do sleep 5; done
   

2. Push-Token ohne Pull-Berechtigung

   • Problem: Der docker push-Code schlägt mit einem Autorisierungsfehler fehl, obwohl das Token die push-Aktion besitzt.
   • Warum es passiert: Beim Pushen werden bestehende Schichten zur Deduplizierung gelesen, sodass Pushen auch Pullen erfordert. Ein push-only-Bereich wird abgelehnt.
   • Lösung: Immer pull neben push im Bereich aufnehmen:

   actions = ["push", "pull"]
   

3. Ein Token ablaufen lassen, während es noch im Einsatz ist

   • Problem: Ein CI-Deploy, das gestern noch funktioniert hat, schlägt jetzt bei der Authentifizierung fehl, und das Token ist einfach verschwunden.
   • Warum es passiert: Wenn das Ablaufdatum eines Tokens erreicht ist, wird es gelöscht und nicht deaktiviert, sodass es keine Übergangsfrist und keinen Wiederaktivierungsmechanismus gibt.
   • Lösung: Das Token vor dem Ablauf ersetzen. Erstellen Sie das Ersatztoken, aktualisieren Sie das CI-Geheimnis und lassen Sie das alte Token ablaufen. Setzen Sie nie ein Ablaufdatum, das kürzer ist als Ihre Release-Häufigkeit, und beachten Sie, dass das Mindestablaufdatum eine Stunde in der Zukunft liegt.

Zusammenfassung

Sie können jetzt einen IONOS Container-Registrierung als Infrastructure as Code bereitstellen, gültige Zugriffstoken ausstellen, die Docker-CLI und CI-Pipelines authentifizieren und produktionssichere, mehrstufige Bilder mit Git-SHA-Tag ausliefern. Sie wissen auch, wie Sie die Müllsammlung konfigurieren, um Speicherplatz zurückzugewinnen, und die Schwachstellenanalyse als Promotionsgate aktivieren. Dieses Registrierungssystem ist die Quelle der Wahrheit für die Bilder, die in Einheit 3.2 auf Managed Kubernetes bereitgestellt werden.

Das Token-basierte Zugriffsmodell des Registrierungssystems mit keinem RBAC und ohne pro-Repositorium-ACLs bestimmt, wie Sie Anmeldeinformationen organisieren: ein gültiger Token pro Pipeline und pro Entwickler, der vor dem Ablauf rotiert wird, da abgelaufene Token sofort gelöscht werden. Beachten Sie die Hostname-Nach-Laufen-Einschränkung für jeden automatisierten Arbeitsablauf, und die Build-Tag-Push-Pipeline, die Sie hier erstellt haben, wird zur ersten Stufe des vollständigen CI/CD-Flusses in Einheit 3.3.

Wichtige Punkte:

• Registrierungen mit ionoscloud_container_registry; name und location sind unveränderlich und der Name ist global eindeutig (ein Duplikat gibt HTTP 409 zurück)
• Der Hostname folgt {name}.cr.{location-with-dash}.ionos.com und ist leer, bis das Registrierungssystem Running ist
• Die Authentifizierung ist token-basiert docker login nur, mit Berechtigungen von Registry oder Repository und Aktionen pull, push, delete; push erfordert pull
• Token-Passwörter werden einmal angezeigt und abgelaufene Token werden gelöscht, nicht deaktiviert, also erfassen und rotieren Sie proaktiv
• Die Müllsammlung ist standardmäßig deaktiviert und kann nach einem Zeitplan konfiguriert werden; die Schwachstellenanalyse ist ein Add-on, das nicht deaktiviert werden kann, sobald es aktiviert ist

Wichtige Begriffe:

• Registrierungszugriffstoken: Die Anmeldeinformationen für docker login, pro Registrierung oder pro Repository-Pfad gültig; gibt es in permanenten und temporären (ablaufbehafteten) Typen
• Berechtigung: Ein Token-Zugriff, ein Typ (Registry oder Repository), ein Pfad und eine Aktionssammlung von pull, push, delete
• Müllsammlung: Serverseitige Rückgewinnung von nicht referenzierten Bildschichten, standardmäßig deaktiviert und nach einem konfigurierten Tag/Uhrzeitplan ausgeführt
• Schwachstellenanalyse: Ein Add-on, das ausgelieferte Artefakte auf CVEs pro Artefakt und pro Repository analysiert; unwiderruflich, sobald aktiviert
• Git-SHA-Tag: Ein unveränderlicher Bildtag, der auf den Commit-SHA gesetzt wird, damit ein bereitgestelltes Bild einem exakten Commit zugeordnet werden kann

Nächste Schritte

Weiterlernen: Einheit 3.2: Kubernetes-Bereitstellung und -Betrieb

Verwandte Themen:

• Einheit 1.1: IONOS API, Authentifizierung und Async-Modell
• Einheit 3.3: CI/CD-Pipelines für IONOS