13 min read

Learning Objectives

By the end of this module, you will be able to:

  • Provision a Private Container Registry and its access tokens with `ionoscloud_container_registry` and `ionoscloud_container_registry_token`
  • Authenticate the Docker CLI against the registry with a scoped token and push and pull images
  • Build production images for TaskBoard's API and web frontend with multi-stage Dockerfiles
  • Implement an image pipeline that tags every image with the Git commit SHA and pushes it to the registry
  • Configure CI credentials for GitHub Actions and GitLab CI that log in to the registry without exposing the token

Unit 3.1: Container Registry and Image Pipelines

Introduction

Module 2 gave TaskBoard its network, load balancer, storage and databases. The application itself still runs as files copied onto a server. Before you can deploy it to Managed Kubernetes in Unit 3.2, you need versioned container images in a registry that your cluster and your CI pipeline can reach.

The Private Container Registry gives you that. It supports the Docker Registry HTTP API v2, so the Docker CLI and any CI system that speaks that API work with it. Access always requires authentication: you create tokens with scopes, and every client logs in with a token.

In this unit you provision the registry and its tokens with Terraform, log in with Docker, build multi-stage images for the TaskBoard API and frontend, and push them with Git SHA tags. In the Code Lab you run the full loop from terraform apply to a verified pull.

1. Provisioning the Registry with 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
  }
}

The resource needs a name and a location. Both are immutable: changing either forces Terraform to destroy and recreate the registry, including every image in it. The registry is available in the FRA region, location de/fra.

1.1 Name Rules

The registry name must be:

  • Globally unique across all customers
  • Between 3 and 63 characters long
  • Made of alphanumeric characters and dashes only
  • Started with a character between a-z and ended with an alphanumeric character

Because the name is global, add a random suffix per environment, as you did for Object Storage buckets in Unit 2.4.

1.2 Vulnerability Scanning and Garbage Collection

Vulnerability scanning is a paid add-on. In the provider it is enabled by default, and it cannot be turned off after activation. If you do not want it, set vulnerability_scanning = false when you create the registry.

Garbage collection is turned off by default. Deleting an image or tag does not free storage: the registry hides the deleted items, but the data stays on disk until garbage collection runs. The garbage_collection_schedule block sets a weekly run with days and a time.

During garbage collection the registry is read-only, and you cannot push images. Schedule the run outside your release hours, or a CI push fails while it runs.

1.3 Restricting Network Access and Reading the Hostname

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
}

The registry is available from the public internet. api_subnet_allow_list limits which subnet CIDRs may connect; an empty or unset list means no restriction. The create response does not contain a hostname because the host has not been allocated yet, so read hostname from the data source once the registry is running.

2. Tokens and Docker Login

Docker clients authenticate with registry tokens. There are no public repositories and no unauthenticated access. A token has a name, an optional expiry date, a status and one or more scopes.

2.1 Tokens as 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"]
  }
}

A scope combines a type, a name and actions. With type repository, the name is the repository path the token may access, and * works as a wildcard. The actions are pull, push and delete. Type registry creates a token that can list the repositories of the registry.

Create one token per consumer. The CI token pushes; the cluster token in Unit 3.2 only pulls. When a cluster token leaks, nobody can overwrite your images with it.

2.2 Token Rules That Affect Your Code

Rule Value
Name length 3 to 63 characters, alphanumeric and dashes, starts with a-z
Name change Not possible; name is immutable
Expiry date At least 1 hour in the future, ISO 8601 timestamp
At expiry The token is deleted, not disabled
Push action Requires the pull action as well
Password Returned only once, on create
Duplicate name 409 Conflict

The password is the critical part. The provider documents save_password_to_file as the only way to get the token, and it works only on create. Move the file into your secret store right after apply and delete it locally. If you lose the password, create a new token.

2.3 Logging In with 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 needs three values: the registry hostname, the username and the password. Take the username from the credentials of the token response; in the API examples it matches the token name. Pass the password through --password-stdin so that it never appears in your shell history or process list.

You can also create a token through the API. The response contains credentials.username and 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

Note the two different credentials: the Cloud API bearer token (IONOS_TOKEN) manages registries and tokens; the registry token logs in with Docker.

3. Multi-Stage Dockerfiles for TaskBoard

A multi-stage build compiles in one image and copies only the result into a small runtime image. Build tools, caches and source files stay out of what you push.

3.1 The API Service

# 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"]

The first stage installs the dependencies into /install; the second stage copies only that tree and the source. The container runs as a non-root user, which you rely on in Unit 3.2.

3.2 The 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

The frontend image contains static files and a web server, nothing from Node.js. Smaller images push faster and contain fewer packages to patch. If you enabled vulnerability scanning, each package that you leave out of the runtime stage is one less source of findings.

4. The Image Pipeline Pattern

Every TaskBoard build follows the same four steps: build, tag with the Git SHA, push, and hand the reference to the deployment.

4.1 Tag with the 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"

A SHA tag is immutable by convention: one commit, one image. A moving tag such as latest makes a rollback in Unit 3.3 guesswork, because the cluster cannot tell which build it runs. Repository names such as taskboard/api match the taskboard/* scope from Section 2.1.

4.2 Pass a Digest to the Deployment

DIGEST="$(docker inspect --format '{{index .RepoDigests 0}}' "$CR_HOST/taskboard/api:$SHA")"
echo "$DIGEST"   # <registry-hostname>/taskboard/api@sha256:...

The digest pins the exact image content. Your deployment manifest in Unit 3.2 can use either the SHA tag or the digest; the pipeline in Unit 3.3 writes it into the manifest.

4.3 Rate Limits for Build Servers

The registry limits each client:

Metric Limit Description
Maximum Concurrent Connections per Client 100 The highest number of simultaneous TCP connections that a single client (Example: a build server or cluster node) can maintain for Private Container Registry operations, such as downloading layers. Exceeding this limit will result in the connection rejection.
Maximum Requests per Second (RPS) per Client 60 The maximum number of API requests (Example: fetches, token authentication requests, layer existence checks) that a single client can send to the Private Container Registry per second. Excessive requests result in a 429 (Too Many Requests) error.

A shared build server that pushes many images in parallel can hit these limits. Limit parallel pushes per runner, and retry a 429 with backoff, as you learned for the Cloud API in Unit 1.1.

5. CI Integration

The pipeline needs three values as secrets: the hostname, the username and the password of the push token. Never commit any of them.

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, define CR_PASSWORD as a masked, protected CI/CD variable so that it is only available on protected branches. The full workflows for both systems follow in Unit 3.3.

If you set api_subnet_allow_list, the runner's egress address must be in the list. Hosted runners can use changing addresses, so either run self-hosted runners with a known address or leave the list empty and rely on the token.

API Reference Quick Card

Key API endpoints for this unit's topic:

Method Endpoint Description
GET /locations List the locations where you can create a registry
POST /registries Create a registry
GET /registries/{registryId} Get a registry, including hostname and state
POST /registries/{registryId}/tokens Create a token; the response holds the password once
DELETE /registries/{registryId}/repositories/{repositoryName} Delete a repository (URL-encode the name, for example taskboard%2Fapi)

Base URL: https://api.ionos.com/containerregistries Authentication: Authorization: Bearer <token>

Code Lab

Objective: Create a Private Container Registry with a push token and a pull token, build TaskBoard's API and web images with multi-stage Dockerfiles, push them with Git SHA tags, and verify a pull with the read-only token.

Prerequisites:

  • IONOS CLOUD account with an API token in IONOS_TOKEN
  • Terraform, Docker and jq installed locally
  • A Git repository with TaskBoard's api/ and web/ folders and the Dockerfiles from Section 3

Step 1: Write registry.tf

Copy the registry resource from Section 1, the data source and output from Section 1.3 (without api_subnet_allow_list), and both tokens from Section 2.1. Use your own name suffix. Add the provider block from Unit 1.2 and one more output:

output "registry_id" {
  value = ionoscloud_container_registry.taskboard.id
}
terraform init

Expected output:

Terraform has been successfully initialized!

Step 2: Apply

terraform apply

Expected output:

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>"

Step 3: Log in with the push token

export CR_HOST="$(terraform output -raw registry_hostname)"
docker login "$CR_HOST" --username taskboard-ci-push --password-stdin < ci-push.pass

Expected output:

Login Succeeded

Step 4: Build and push both images

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

Expected output:

...
<sha>: digest: sha256:... size: ...

Step 5: List the repositories through the API

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'

Expected output:

taskboard/api
taskboard/web

Step 6: Verify the pull-only token

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"

Expected output:

Login Succeeded
...
Status: Image is up to date for <registry-hostname>/taskboard/api:<sha>
...
(the push fails with an access denied error)

Validation Checklist:

  • [ ] The registry and both tokens were created by terraform apply
  • [ ] Both images are in the registry under taskboard/ with the Git SHA tag
  • [ ] The pull token can pull but not push
  • [ ] No token password is committed to Git

Cleanup:

Keep the registry and the k8s-pull.pass file if you continue with Unit 3.2. Otherwise:

terraform destroy -auto-approve
rm -f ci-push.pass k8s-pull.pass

Common Pitfalls

Developer mistakes to avoid with this unit's topic:

  1. Push token without pull

    • Problem: docker push fails with an access denied error, although the token has the push action.
    • Why it happens: The push action requires the pull action. Docker checks for existing layers before it uploads.
    • Fix: Set actions = ["pull", "push"] in the token scope.
  2. Lost token password

    • Problem: After a fresh checkout, terraform apply succeeds, but nobody has the password for the CI token.
    • Why it happens: The password is returned only once, on create, and save_password_to_file works only on create.
    • Fix: Store the file in your secret store immediately. To rotate, replace the token: terraform apply -replace=ionoscloud_container_registry_token.ci_push, then update the CI secret.
  3. CI push fails during garbage collection or from a blocked address

    • Problem: A nightly pipeline fails on docker push every Sunday, or every push from hosted runners fails.
    • Why it happens: The registry is read-only while garbage collection runs, and api_subnet_allow_list blocks addresses outside the list.
    • Fix: Move garbage_collection_schedule out of your build hours, and keep the runner's egress address in the allow list or leave the list empty.

Summary

You can now give TaskBoard a private image supply chain. Terraform creates the Private Container Registry in de/fra and one scoped token per consumer. Multi-stage Dockerfiles keep the API and frontend images small, every image carries the Git SHA of its commit, and CI systems log in with a token from their secret store.

Key Points:

  • name and location of a registry are immutable; the name is globally unique
  • Vulnerability scanning is enabled by default in the provider; set vulnerability_scanning = false at creation if you do not want it
  • Docker clients log in with registry tokens; a token password is returned only once
  • Use separate tokens for push (CI, with pull and push) and pull (cluster)
  • Tag images with the Git SHA; respect the per-client limits of 100 connections and 60 requests per second

Important Terminology:

  • Registry token: A credential with scopes that the Docker CLI uses to log in to the registry
  • Scope: A combination of type, repository name (with * wildcard) and actions (pull, push, delete)
  • Multi-stage build: A Dockerfile with a build stage and a minimal runtime stage that receives only the build output
  • Image digest: The sha256 content hash that pins an exact image, independent of tags
  • Garbage collection: The scheduled run that frees storage from deleted images; the registry is read-only while it runs

Next Steps

Continue Learning: Unit 3.2: Kubernetes Deployment and Operations

Related Topics: