Unidad 3.1: Container Registry y pipelines de imágenes
Introducción
El Módulo 2 proporcionó a TaskBoard su red, equilibrador de carga, almacenamiento y bases de datos. La propia aplicación sigue ejecutándose como archivos copiados en un servidor. Antes de poder desplegarla en Managed Kubernetes en la Unidad 3.2, necesita imágenes de contenedor con control de versiones en un registro al que su clúster y su pipeline de CI puedan acceder.
El Private Container Registry le proporciona esto. Admite la API HTTP v2 de Docker Registry, por lo que la CLI de Docker y cualquier sistema de CI que utilice dicha API funcionan con él. El acceso siempre requiere autenticación: crea tokens con alcances, y cada cliente inicia sesión con un token.
En esta unidad, aprovisiona el registro y sus tokens con Terraform, inicia sesión con Docker, construye imágenes de múltiples etapas para la API y el frontend de TaskBoard, y las publica con etiquetas de SHA de Git. En el Code Lab, ejecuta el ciclo completo desde terraform apply hasta una extracción verificada.
1. Aprovisionamiento del registro con 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
}
}
El recurso requiere un name y un location. Ambos son inmutables: cambiar cualquiera de ellos obliga a Terraform a destruir y recrear el registro, incluyendo todas las imágenes que contenga. El registro está disponible en la región FRA, ubicación de/fra.
1.1 Reglas de nomenclatura
El nombre del registro debe cumplir las siguientes condiciones:
- Ser único a nivel global entre todos los clientes
- Tener una longitud de entre 3 y 63 caracteres
- Estar compuesto únicamente por caracteres alfanuméricos y guiones
- Comenzar con un carácter entre a y z, y terminar con un carácter alfanumérico
Dado que el nombre es global, agregue un sufijo aleatorio por entorno, tal como hizo con los cubos de Object Storage en la Unidad 2.4.
1.2 Escaneo de vulnerabilidades y recolección de basura
El escaneo de vulnerabilidades es un complemento de pago. En el proveedor, está habilitado de forma predeterminada y no puede desactivarse después de la activación. Si no desea utilizarlo, establezca vulnerability_scanning = false al crear el registro.
La recolección de basura está desactivada de forma predeterminada. Eliminar una imagen o una etiqueta no libera almacenamiento: el registro oculta los elementos eliminados, pero los datos permanecen en el disco hasta que se ejecute la recolección de basura. El bloque garbage_collection_schedule configura una ejecución semanal con days y un time.
Durante la recolección de basura, el registro es de solo lectura y no puede cargar imágenes. Programe la ejecución fuera de sus horas de publicación, o una carga de CI fallará mientras se esté ejecutando.
1.3 Restricción del acceso a la red y lectura del nombre de host
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
}
El registro está disponible desde Internet público. api_subnet_allow_list limita qué subredes CIDR pueden conectarse; una lista vacía o no configurada significa que no hay restricción. La respuesta de creación no contiene un nombre de host porque el host aún no ha sido asignado, por lo que lea hostname desde la fuente de datos una vez que el registro esté en ejecución.
2. Tokens e inicio de sesión en Docker
Los clientes de Docker se autentican mediante tokens de registro. No existen repositorios públicos ni acceso sin autenticación. Un token tiene un nombre, una fecha de expiración opcional, un estado y una o más asignaciones de ámbito.
2.1 Tokens como código
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"]
}
}
Un ámbito combina un type, un name y actions. Con el tipo repository, el nombre es la ruta del repositorio al que el token puede acceder, y * funciona como comodín. Las acciones son pull, push y delete. El tipo registry crea un token que puede listar los repositorios del registro.
Cree un token por consumidor. El token de CI realiza operaciones de push; el token del clúster en la Unidad 3.2 solo realiza operaciones de pull. Si un token de clúster se filtra, nadie puede sobrescribir sus imágenes con él.
2.2 Reglas de tokens que afectan su código
| Regla | Valor |
|---|---|
| Longitud del nombre | De 3 a 63 caracteres, alfanuméricos y guiones, comienza con a-z |
| Cambio de nombre | No es posible; name es inmutable |
| Fecha de expiración | Al menos 1 hora en el futuro, marca de tiempo ISO 8601 |
| Al expirar | El token se elimina, no se desactiva |
| Acción de push | También requiere la acción de pull |
| Contraseña | Se devuelve solo una vez, al crearlo |
| Nombre duplicado | 409 Conflict |
La contraseña es la parte crítica. El proveedor documenta save_password_to_file como la única forma de obtener el token, y solo funciona al crearlo. Mueva el archivo a su almacén de secretos inmediatamente después de apply y elimínelo localmente. Si pierde la contraseña, cree un token nuevo.
2.3 Inicio de sesión con 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 requiere tres valores: el nombre de host del registro, el nombre de usuario y la contraseña. Obtenga el nombre de usuario de credentials de la respuesta del token; en los ejemplos de la API, coincide con el nombre del token. Pase la contraseña a través de --password-stdin para que nunca aparezca en el historial de su shell ni en la lista de procesos.
También puede crear un token a través de la API. La respuesta contiene credentials.username y 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
Observe las dos credenciales diferentes: el token de portador de la Cloud API (IONOS_TOKEN) administra los registros y los tokens; el token del registro inicia sesión con Docker.
3. Dockerfiles de varias etapas para TaskBoard
Una compilación de varias etapas compila en una imagen y copia solo el resultado en una imagen de ejecución pequeña. Las herramientas de compilación, las cachés y los archivos de código fuente quedan fuera de lo que se publica.
3.1 El servicio API
# 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"]
La primera etapa instala las dependencias en /install; la segunda etapa copia únicamente ese árbol y el código fuente. El contenedor se ejecuta como un usuario no root, algo en lo que se apoya la Unidad 3.2.
3.2 El frontend web
# 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
La imagen del frontend contiene archivos estáticos y un servidor web, pero nada de Node.js. Las imágenes más pequeñas se transfieren más rápido y contienen menos paquetes que parchear. Si habilitó el escaneo de vulnerabilidades, cada paquete que deje fuera de la etapa de tiempo de ejecución representa una fuente menos de hallazgos.
4. El patrón de la canalización de imágenes
Cada compilación de TaskBoard sigue los mismos cuatro pasos: compilar, etiquetar con el SHA de Git, enviar y pasar la referencia a la implementación.
4.1 Etiquetar con el SHA del commit
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"
Una etiqueta SHA es inmutable por convención: un commit, una imagen. Una etiqueta móvil como latest convierte la reversión en la Unidad 3.3 en una conjetura, porque el clúster no puede determinar qué compilación está ejecutando. Los nombres de repositorio como taskboard/api coinciden con el ámbito taskboard/* de la Sección 2.1.
4.2 Pasar un resumen a la implementación
DIGEST="$(docker inspect --format '{{index .RepoDigests 0}}' "$CR_HOST/taskboard/api:$SHA")"
echo "$DIGEST" # <registry-hostname>/taskboard/api@sha256:...
El resumen fija el contenido exacto de la imagen. El manifiesto de despliegue en la Unidad 3.2 puede utilizar la etiqueta SHA o el resumen; la canalización en la Unidad 3.3 lo escribe en el manifiesto.
4.3 Límites de velocidad para servidores de compilación
El registro limita a cada cliente:
| Métrica | Límite | Descripción |
|---|---|---|
| Conexiones simultáneas máximas por cliente | 100 | La cantidad máxima de conexiones TCP simultáneas que un solo cliente (por ejemplo, un servidor de compilación o un nodo del clúster) puede mantener para operaciones de Private Container Registry, como la descarga de capas. Superar este límite resultará en la rechazo de la conexión. |
| Solicitudes máximas por segundo (RPS) por cliente | 60 | La cantidad máxima de solicitudes de API (por ejemplo, recuperaciones, solicitudes de autenticación de token, comprobaciones de existencia de capas) que un solo cliente puede enviar al Private Container Registry por segundo. Las solicitudes excesivas resultan en un error 429 (Demasiadas solicitudes). |
Un servidor de compilación compartido que envía muchas imágenes en paralelo puede alcanzar estos límites. Limite los envíos paralelos por ejecutor y reintente un 429 con retroceso, como aprendió para la Cloud API en la Unidad 1.1.
5. Integración de CI
La pipeline requiere tres valores como secretos: el nombre del host, el nombre de usuario y la contraseña del token de push. Nunca debe commitarse ninguno de ellos.
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
En GitLab, defina CR_PASSWORD como una variable de CI/CD enmascarada y protegida para que solo esté disponible en ramas protegidas. Los flujos de trabajo completos para ambos sistemas se detallan en la Unidad 3.3.
Si configura api_subnet_allow_list, la dirección de salida del runner debe estar en la lista. Los runners alojados pueden utilizar direcciones cambiantes, por lo que debe ejecutar runners autoalojados con una dirección conocida o dejar la lista vacía y confiar en el token.
Tarjeta rápida de referencia de la API
Endpoints clave de la API para el tema de esta unidad:
| Método | Endpoint | Descripción |
|---|---|---|
GET |
/locations |
Enumerar las ubicaciones donde puede crear un registro |
POST |
/registries |
Crear un registro |
GET |
/registries/{registryId} |
Obtener un registro, incluyendo hostname y estado |
POST |
/registries/{registryId}/tokens |
Crear un token; la respuesta contiene la contraseña una sola vez |
DELETE |
/registries/{registryId}/repositories/{repositoryName} |
Eliminar un repositorio (codifique el nombre en la URL, por ejemplo taskboard%2Fapi) |
URL base: https://api.ionos.com/containerregistries
Autenticación: Authorization: Bearer <token>
Laboratorio de código
Objetivo: Crear una Private Container Registry con un token de push y un token de pull, construir las imágenes de la API y de la interfaz web de TaskBoard con Dockerfiles de múltiples etapas, enviarlas con etiquetas de SHA de Git y verificar un pull con el token de solo lectura.
Requisitos previos:
- Cuenta de IONOS CLOUD con un token de API en
IONOS_TOKEN - Terraform, Docker y
jqinstalados localmente - Un repositorio de Git con las carpetas
api/yweb/de TaskBoard y los Dockerfiles de la Sección 3
Paso 1: Escribir registry.tf
Copie el recurso de registro de la Sección 1, la fuente de datos y la salida de la Sección 1.3 (sin api_subnet_allow_list) y ambos tokens de la Sección 2.1. Utilice su propio sufijo de nombre. Añada el bloque de proveedor de la Unidad 1.2 y una salida adicional:
output "registry_id" {
value = ionoscloud_container_registry.taskboard.id
}
terraform init
Salida esperada:
Terraform has been successfully initialized!
Paso 2: Aplicar
terraform apply
Salida esperada:
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>"
Paso 3: Iniciar sesión con el token de push
export CR_HOST="$(terraform output -raw registry_hostname)"
docker login "$CR_HOST" --username taskboard-ci-push --password-stdin < ci-push.pass
Salida esperada:
Login Succeeded
Paso 4: Compilar y enviar ambas imágenes
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
Salida esperada:
...
<sha>: digest: sha256:... size: ...
Paso 5: Listar los repositorios a través de la 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'
Salida esperada:
taskboard/api
taskboard/web
Paso 6: Verificar el token solo de extracción
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"
Salida esperada:
Login Succeeded
...
Status: Image is up to date for <registry-hostname>/taskboard/api:<sha>
...
(the push fails with an access denied error)
Lista de verificación:
- [ ] El registro y ambos tokens fueron creados por
terraform apply - [ ] Ambas imágenes están en el registro bajo
taskboard/con la etiqueta de SHA de Git - [ ] El token de extracción puede extraer, pero no puede publicar
- [ ] Ninguna contraseña de token se ha confirmado (commit) en Git
Limpieza:
Mantenga el registro y el archivo k8s-pull.pass si continúa con la Unidad 3.2. De lo contrario:
terraform destroy -auto-approve
rm -f ci-push.pass k8s-pull.pass
Errores comunes
Errores de desarrollo que debe evitar con el tema de esta unidad:
-
Token de push sin pull
- Problema:
docker pushfalla con un error de acceso denegado, aunque el token tenga la acciónpush. - Por qué ocurre: La acción de push requiere la acción de pull. Docker verifica las capas existentes antes de cargarlas.
- Solución: Establezca
actions = ["pull", "push"]en el ámbito del token.
- Problema:
-
Contraseña del token perdida
- Problema: Después de un clonado nuevo,
terraform applytiene éxito, pero nadie tiene la contraseña del token de CI. - Por qué ocurre: La contraseña se devuelve solo una vez, al crear, y
save_password_to_filesolo funciona al crear. - Solución: Guarde el archivo en su almacén de secretos de inmediato. Para rotar, reemplace el token:
terraform apply -replace=ionoscloud_container_registry_token.ci_push, y luego actualice el secreto de CI.
- Problema: Después de un clonado nuevo,
-
El push de CI falla durante la recolección de basura o desde una dirección bloqueada
- Problema: Un pipeline nocturno falla en
docker pushtodos los domingos, o todos los pushes desde ejecutores alojados fallan. - Por qué ocurre: El registro es de solo lectura mientras se ejecuta la recolección de basura, y
api_subnet_allow_listbloquea direcciones fuera de la lista. - Solución: Mueva
garbage_collection_schedulefuera de sus horas de compilación, y mantenga la dirección de salida del ejecutor en la lista de permitidos o deje la lista vacía.
- Problema: Un pipeline nocturno falla en
Resumen
Ahora puede proporcionar a TaskBoard una cadena de suministro de imágenes privada. Terraform crea el Private Container Registry en de/fra y un token con ámbito por cada consumidor. Los Dockerfiles de varias etapas mantienen pequeñas las imágenes de la API y del frontend, cada imagen lleva el SHA de Git de su commit, y los sistemas de CI inician sesión con un token de su almacén de secretos.
Puntos clave:
nameylocationde un registro son inmutables; el nombre es único a nivel global- El escaneo de vulnerabilidades está habilitado de forma predeterminada en el proveedor; establezca
vulnerability_scanning = falseen la creación si no lo desea - Los clientes de Docker inician sesión con tokens de registro; la contraseña del token se devuelve solo una vez
- Use tokens separados para push (CI, con pull y push) y pull (clúster)
- Etiquete las imágenes con el SHA de Git; respete los límites por cliente de 100 conexiones y 60 solicitudes por segundo
Terminología importante:
- Token de registro: Una credencial con ámbitos que la CLI de Docker utiliza para iniciar sesión en el registro
- Ámbito: Una combinación de tipo, nombre de repositorio (con el comodín
*) y acciones (pull,push,delete) - Construcción de varias etapas: Un Dockerfile con una etapa de construcción y una etapa de ejecución mínima que recibe solo la salida de la construcción
- Suma de verificación de imagen: La suma de verificación de contenido
sha256que fija una imagen exacta, independientemente de las etiquetas - Recopilación de basura: La ejecución programada que libera almacenamiento de imágenes eliminadas; el registro es de solo lectura mientras se ejecuta
Próximos pasos
Siga aprendiendo: Unidad 3.2: Despliegue y operaciones de Kubernetes
Temas relacionados: