15 min de lectura

Objetivos de aprendizaje

Al final de este módulo, podrás:

  • Aprovisionar un Private Container Registry y sus tokens de acceso con `ionoscloud_container_registry` y `ionoscloud_container_registry_token`
  • Autenticar la CLI de Docker contra el registro con un token de ámbito limitado, e impulsar y extraer imágenes
  • Construir imágenes de producción para la API y el frontend web de TaskBoard con Dockerfiles de múltiples etapas
  • Implementar un pipeline de imágenes que etiquete cada imagen con el SHA del commit de Git y la impulse al registro
  • Configurar credenciales de CI para GitHub Actions y GitLab CI que inicien sesión en el registro sin exponer el token

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 jq instalados localmente
  • Un repositorio de Git con las carpetas api/ y web/ 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:

  1. Token de push sin pull

    • Problema: docker push falla con un error de acceso denegado, aunque el token tenga la acción push.
    • 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.
  2. Contraseña del token perdida

    • Problema: Después de un clonado nuevo, terraform apply tiene é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_file solo 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.
  3. El push de CI falla durante la recolección de basura o desde una dirección bloqueada

    • Problema: Un pipeline nocturno falla en docker push todos 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_list bloquea direcciones fuera de la lista.
    • Solución: Mueva garbage_collection_schedule fuera 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.

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:

  • name y location de 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 = false en 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 sha256 que 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: