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
jqinstalled locally - A Git repository with TaskBoard's
api/andweb/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:
-
Push token without pull
- Problem:
docker pushfails with an access denied error, although the token has thepushaction. - 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.
- Problem:
-
Lost token password
- Problem: After a fresh checkout,
terraform applysucceeds, but nobody has the password for the CI token. - Why it happens: The password is returned only once, on create, and
save_password_to_fileworks 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.
- Problem: After a fresh checkout,
-
CI push fails during garbage collection or from a blocked address
- Problem: A nightly pipeline fails on
docker pushevery Sunday, or every push from hosted runners fails. - Why it happens: The registry is read-only while garbage collection runs, and
api_subnet_allow_listblocks addresses outside the list. - Fix: Move
garbage_collection_scheduleout of your build hours, and keep the runner's egress address in the allow list or leave the list empty.
- Problem: A nightly pipeline fails on
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:
nameandlocationof a registry are immutable; the name is globally unique- Vulnerability scanning is enabled by default in the provider; set
vulnerability_scanning = falseat 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
sha256content 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: