Replicar un repositorio de Docker Hardened Image

La réplica requiere una suscripción a DHI Select o Enterprise. Sin una suscripción, puedes descargar Docker Hardened Images directamente desde dhi.io sin necesidad de realizar la réplica. Con una suscripción a DHI Select o Enterprise, debes realizar la réplica en tu organización para obtener:

• Variantes de cumplimiento (imágenes habilitadas para FIPS o listas para STIG)
• Variantes de soporte de ciclo de vida extendido (ELS) (requiere un complemento)
• Personalización de imágenes o Helm charts
• Entornos de red aislados (air-gapped) o restringidos
• Actualizaciones de seguridad respaldadas por SLA

Cómo replicar

Este tema cubre dos tipos de réplica para repositorios de Docker Hardened Image (DHI):

• Replicar en tu organización: Replicar un repositorio de DHI en el espacio de nombres de tu organización en Docker Hub.

• Replicar en un registro de terceros: Replicar un repositorio en otro registro de contenedores, como Amazon ECR, Google Artifact Registry o una instancia privada de Harbor.

Replicar un DHI en tu organización

Para replicar repositorios, debes ser propietario o editor de la organización, o utilizar un token de acceso personal (PAT) o un token de acceso de organización (OAT). Consulta las pestañas de la CLI y Terraform en las siguientes secciones para conocer los alcances de permisos requeridos.

• Repositorios de imágenes: La réplica te deja personalizar las imágenes al añadir paquetes, artefactos OCI (como certificados personalizados o herramientas adicionales), variables de entorno, etiquetas (labels) y otros ajustes de configuración. Para obtener más detalles, consulta Personalizar una Docker Hardened Image.

• Repositorios de charts: La réplica te deja personalizar las referencias de imágenes dentro del chart. Esto es especialmente útil cuando se utilizan imágenes personalizadas o cuando has replicado imágenes en un registro de terceros y necesitas que el chart haga referencia a esas ubicaciones personalizadas. Para obtener más detalles, consulta Personalizar un Helm chart de DHI.

$ docker dhi mirror start --org my-org \
  -r dhi/golang,my-org/dhi-golang \
  -r dhi/nginx,my-org/dhi-nginx \
  -r dhi/prometheus-chart,my-org/dhi-prometheus-chart

$ docker dhi mirror start --org my-org -r dhi/golang,my-org/dhi-golang --dependencies

$ docker dhi mirror list --org my-org

$ docker dhi mirror list --org my-org --filter python
$ docker dhi mirror list --org my-org --type image
$ docker dhi mirror list --org my-org --type helm-chart

terraform {
  required_providers {
    dhi = {
      source = "docker-hardened-images/dhi"
    }
  }
}

provider "dhi" {
  docker_hub_username = var.docker_username
  docker_hub_password = var.docker_password
  organization        = var.org_name
}

resource "dhi_mirror" "golang" {
  source_namespace = "dhi"
  source_name      = "golang"
  destination_name = "dhi-golang"
}

resource "dhi_mirror" "nginx" {
  source_namespace = "dhi"
  source_name      = "nginx"
  destination_name = "dhi-nginx"
}

resource "dhi_mirror" "golang" {
  source_namespace = "dhi"
  source_name      = "golang"
  destination_name = "dhi-golang"
  els              = true
}

Después de la réplica, el repositorio aparece en la lista de repositorios de tu organización con el prefijo dhi- y continúa recibiendo imágenes actualizadas. Se comporta como cualquier otro repositorio de Docker Hub, por lo que puedes gestionar el acceso y los permisos, configurar webhooks y usar otras funciones estándar de Hub. Consulta Repositorios de Docker Hub para más detalles.

Detener la réplica de un repositorio

Después de detener la réplica, el repositorio permanece, pero ya no recibe actualizaciones. Aún puedes usar las últimas imágenes o charts que fueron replicados.

Note

Si solo quieres dejar de replicar las versiones ELS, puedes desmarcar la opción ELS en la pestaña Settings del repositorio replicado.

$ docker dhi mirror stop --org my-org dhi-golang

Replicar un repositorio de DHI en un registro de terceros

Después de replicar un repositorio de DHI en tu organización en Docker Hub, opcionalmente puedes replicarlo en otro registro de contenedores, como Amazon ECR, Google Artifact Registry, GitHub Container Registry o una instancia privada de Harbor.

Puedes usar cualquier flujo de trabajo estándar para replicar la imagen, como la CLI de Docker, la API del registro de Docker Hub, herramientas de registro de terceros o automatización de CI/CD.

Sin embargo, para preservar todo el contexto de seguridad, incluidas las atestaciones, también debes replicar sus artefactos OCI asociados. Los repositorios de DHI almacenan las capas de la imagen en dhi.io (o docker.io para imágenes personalizadas) y las atestaciones firmadas en un registro separado (registry.scout.docker.com).

Para copiar ambos, puedes usar regctl, una CLI compatible con OCI que admite la réplica de imágenes junto con sus artefactos adjuntos, como SBOM, informes de vulnerabilidades y procedencia de SLSA. Para la sincronización continua, puedes usar regsync.

Automatizar la sincronización con webhooks

Para mantener registros o sistemas externos sincronizados con tus Docker Hardened Images replicadas, y recibir notificaciones cuando ocurran actualizaciones, puedes configurar un webhook en el repositorio replicado en Docker Hub. Un webhook envía una solicitud POST a una URL que definas cada vez que se sube o actualiza una nueva etiqueta de imagen.

Por ejemplo, podrías configurar un webhook para llamar a un sistema CI/CD en https://ci.example.com/hooks/dhi-sync cada vez que se replique una nueva etiqueta. La automatización activada por este webhook puede descargar la imagen actualizada de Docker Hub y subirla a un registro interno como Amazon ECR, Google Artifact Registry o GitHub Container Registry.

Otros casos de uso comunes de webhooks incluyen:

• Activar flujos de trabajo de validación o escaneo de vulnerabilidades
• Firmar o promocionar imágenes
• Enviar notificaciones a sistemas descendentes (downstream)

Ejemplo de carga útil de webhook

Cuando se activa un webhook, Docker Hub envía una carga útil JSON como la siguiente:

{
  "callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/",
  "push_data": {
    "pushed_at": 1712345678,
    "pusher": "trustedbuilder",
    "tag": "3.13-alpine3.21"
  },
  "repository": {
    "name": "dhi-python",
    "namespace": "exampleorg",
    "repo_name": "exampleorg/dhi-python",
    "repo_url": "https://hub.docker.com/r/exampleorg/dhi-python",
    "is_private": true,
    "status": "Active",
    ...
  }
}

Ejemplo de réplica con regctl

El siguiente ejemplo muestra cómo usar regctl para replicar una etiqueta específica de una Docker Hardened Image desde Docker Hub a otro registro, junto con sus atestaciones asociadas. Primero debes instalar regctl.

El ejemplo asume que has replicado el repositorio de DHI en el espacio de nombres de tu organización en Docker Hub como se describió en la sección anterior. Puedes aplicar los mismos pasos a una imagen no replicada actualizando las variables SRC_ATT_REPO y SRC_REPO según corresponda.

1. Establece las variables de entorno para tu entorno específico. Reemplaza los marcadores de posición con tus valores reales.

   En este ejemplo, utilizas un nombre de usuario de Docker para representar a un miembro de la organización de Docker Hub en la que se replican los repositorios de DHI. Prepara un token de acceso personal (PAT) para el usuario con acceso read only. Alternativamente, puedes usar el nombre de tu organización y un token de acceso de organización (OAT) para autenticarte en docker.io. Ten en cuenta que los OAT no son compatibles con registry.scout.docker.com. Si tu flujo de trabajo requiere autenticarse en el registro de Scout, usa un token de acceso personal (PAT) para ese paso.

   Warning

   Los siguientes ejemplos exportan las credenciales directamente en la línea de comandos con fines de demostración. Esto expone tokens sensibles en el historial de la shell y en la lista de procesos. En entornos de producción, utiliza métodos seguros como leer desde archivos con permisos restringidos, archivos de entorno cargados en tiempo de ejecución o herramientas de gestión de secretos.

   $ export DOCKER_USERNAME="YOUR_DOCKER_USERNAME"
   $ export DOCKER_PAT="YOUR_DOCKER_PAT"
   $ export DOCKER_ORG="YOUR_DOCKER_ORG"
   $ export DEST_REG="registry.example.com"
   $ export DEST_REPO="mirror/dhi-python"
   $ export DEST_REG_USERNAME="YOUR_DESTINATION_REGISTRY_USERNAME"
   $ export DEST_REG_TOKEN="YOUR_DESTINATION_REGISTRY_TOKEN"
   $ export SRC_REPO="docker.io/${DOCKER_ORG}/dhi-python"
   $ export SRC_ATT_REPO="registry.scout.docker.com/${DOCKER_ORG}/dhi-python"
   $ export TAG="3.13-alpine3.21"
   

2. Inicia sesión a través de regctl en Docker Hub, el registro de Scout que contiene las atestaciones y tu registro de destino.

   $ echo $DOCKER_PAT | regctl registry login -u "$DOCKER_USERNAME" --pass-stdin docker.io
   $ echo $DOCKER_PAT | regctl registry login -u "$DOCKER_USERNAME" --pass-stdin registry.scout.docker.com
   $ echo $DEST_REG_TOKEN | regctl registry login -u "$DEST_REG_USERNAME" --pass-stdin "$DEST_REG"
   

3. Replica la imagen y las atestaciones utilizando --referrers y los puntos de conexión de referenciadores (referrers):

   $ regctl image copy \
        "${SRC_REPO}:${TAG}" \
        "${DEST_REG}/${DEST_REPO}:${TAG}" \
        --referrers \
        --referrers-src "${SRC_ATT_REPO}" \
        --referrers-tgt "${DEST_REG}/${DEST_REPO}" \
        --force-recursive
   

4. Verifica que los artefactos se hayan preservado.

   Primero, obtén el resumen (digest) de una etiqueta y plataforma específicas. Por ejemplo, linux/amd64.

   DIGEST="$(regctl manifest head "${DEST_REG}/${DEST_REPO}:${TAG}" --platform linux/amd64)"
   

   Lista los artefactos adjuntos (SBOM, procedencia, VEX, informes de vulnerabilidades).

   $ regctl artifact list "${DEST_REG}/${DEST_REPO}@${DIGEST}"
   

   O bien, lista los artefactos adjuntos con docker scout.

   $ docker scout attest list "registry://${DEST_REG}/${DEST_REPO}@${DIGEST}"
   

Ejemplo de réplica continua con regsync

regsync automatiza la descarga de imágenes desde los repositorios replicados de DHI de tu organización en Docker Hub y su subida a tu registro externo, incluyendo las atestaciones. Lee un archivo de configuración YAML y puede filtrar etiquetas.

El siguiente ejemplo utiliza un archivo regsync.yaml que sincroniza las variantes Debian 13 de Node 24 y Python 3.12, excluyendo Alpine y Debian 12.

version: 1
# Opcional: credenciales integradas si no confías en inicios de sesión previos de la CLI
# creds:
#   - registry: docker.io
#     user: <your-docker-username>
#     pass: "{{file \"/run/secrets/docker_token\"}}"
#   - registry: registry.scout.docker.com
#     user: <your-docker-username>
#     pass: "{{file \"/run/secrets/docker_token\"}}"
#   - registry: registry.example.com
#     user: <service-user>
#     pass: "{{file \"/run/secrets/dest_token\"}}"

sync:
  - source: docker.io/<your-org>/dhi-node
    target: registry.example.com/mirror/dhi-node
    type: repository
    fastCopy: true
    referrers: true
    referrerSource: registry.scout.docker.com/<your-org>/dhi-node
    referrerTarget: registry.example.com/mirror/dhi-node
    tags:
      allow: [ "24.*" ]
      deny: [ ".*alpine.*", ".*debian12.*" ]

  - source: docker.io/<your-org>/dhi-python
    target: registry.example.com/mirror/dhi-python
    type: repository
    fastCopy: true
    referrers: true
    referrerSource: registry.scout.docker.com/<your-org>/dhi-python
    referrerTarget: registry.example.com/mirror/dhi-python
    tags:
      allow: [ "3.12.*" ]
      deny: [ ".*alpine.*", ".*debian12.*" ]

Para realizar una prueba (dry run) con el archivo de configuración, puedes ejecutar el siguiente comando. Primero debes instalar regsync.

$ regsync check -c regsync.yaml

Para ejecutar la sincronización con el archivo de configuración:

$ regsync once -c regsync.yaml

Siguientes pasos

Después de replicar, consulta Descargar una DHI para aprender a descargar y usar las imágenes replicadas.