Personalizar una imagen o chart de Docker Hardened Images

Cuando tienes una suscripción de DHI Select o DHI Enterprise, puedes personalizar Docker Hardened Images (DHI) y charts para adaptarlos a tus necesidades específicas mediante la interfaz web de Docker Hub. Para las imágenes, esto te deja seleccionar una imagen base, añadir paquetes, añadir artefactos OCI (como certificados personalizados o herramientas adicionales) y configurar los ajustes. Para los charts, esto te deja personalizar las referencias de las imágenes.

Tus personalizaciones se mantienen seguras de forma automática. Cuando la imagen o el chart base de Docker Hardened Image recibe un parche de seguridad o se actualizan tus artefactos OCI, Docker reconstruye automáticamente tus personalizaciones en segundo plano. Esto garantiza protección y cumplimiento continuos de forma predeterminada, sin necesidad de realizar trabajo manual. Los artefactos reconstruidos están firmados y atestiguados con el mismo estándar SLSA Build Level 3 que las imágenes y charts base, lo que garantiza una cadena de suministro segura y verificable.

Personalizar una Docker Hardened Image

Para añadir una Docker Hardened Image personalizada a tu organización, un propietario de la organización primero debe replicar el repositorio de DHI en tu organización en Docker Hub. Una vez replicado el repositorio, cualquier usuario con acceso al repositorio replicado de DHI puede crear una imagen personalizada.

Puedes crear personalizaciones utilizando la CLI de DHI o la interfaz web de Docker Hub.

# Preparar un andamio de personalización
$ docker dhi customization prepare golang 1.25 \
  --org my-org \
  --destination my-org/dhi-golang \
  --name "golang con git" \
  --output my-customization.yaml

# Crear una personalización
$ docker dhi customization create my-customization.yaml --org my-org

# Listar personalizaciones
$ docker dhi customization list --org my-org

# Filtrar personalizaciones por nombre, repositorio o origen
$ docker dhi customization list --org my-org --filter git
$ docker dhi customization list --org my-org --repo dhi-golang
$ docker dhi customization list --org my-org --source golang

# Obtener una personalización
$ docker dhi customization get my-org/dhi-golang "golang con git" --org my-org --output my-customization.yaml

# Actualizar una personalización
$ docker dhi customization edit my-customization.yaml --org my-org

# Eliminar una personalización
$ docker dhi customization delete my-org/dhi-golang "golang con git" --org my-org

# Eliminar sin solicitud de confirmación
$ docker dhi customization delete my-org/dhi-golang "golang con git" --org my-org --yes

resource "dhi_customization" "golang_with_git" {
  repository = "dhi-golang"
  name       = "golang con git"

  contents {
    packages = ["git", "curl"]
  }

  platform {
    os           = "linux"
    architecture = "amd64"
  }
}

Monitorizar las compilaciones de personalización

$ docker dhi customization build list my-org/dhi-golang "golang con git" --org my-org

$ docker dhi customization build get my-org/dhi-golang "golang con git" <build-id> --org my-org

$ docker dhi customization build logs my-org/dhi-golang "golang con git" <build-id> --org my-org

Crear una imagen de artefacto OCI para la personalización de imágenes

Un artefacto OCI es una imagen de Docker que contiene archivos o directorios que quieres incluir en tu Docker Hardened Image (DHI) personalizada. Esto puede incluir herramientas adicionales, bibliotecas o archivos de configuración.

Al crear una imagen para usarla como artefacto OCI, lo ideal es que sea lo más mínima posible y que contenga solo los archivos necesarios.

Por ejemplo, para distribuir un certificado CA raíz personalizado como parte de un paquete de CA de confianza, puedes usar una compilación de múltiples etapas. Este enfoque registra tu certificado en el sistema y genera un paquete de CA actualizado, que se puede extraer en una imagen final mínima:

# syntax=docker/dockerfile:1

FROM dhi.io/bash:5-dev AS certs

ENV DEBIAN_FRONTEND=noninteractive

RUN mkdir -p /usr/local/share/ca-certificates/my-rootca
COPY certs/rootCA.crt /usr/local/share/ca-certificates/my-rootca

RUN update-ca-certificates

FROM scratch
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt

Puedes seguir este patrón para crear otros artefactos OCI, como imágenes que contengan herramientas o bibliotecas que quieras incluir en tu DHI personalizada. Instala las herramientas o bibliotecas necesarias en la primera etapa y luego copia los archivos correspondientes a la etapa final que usa FROM scratch. Esto garantiza que tu artefacto OCI sea mínimo y contenga solo los archivos necesarios.

Para que el artefacto OCI esté disponible en una personalización de DHI, debe compilarse y subirse a un repositorio en el mismo espacio de nombres que el repositorio de DHI replicado.

Si estás personalizando una DHI para múltiples plataformas (como linux/amd64 y linux/arm64), compila tu artefacto OCI para todas las plataformas usando la opción --platform:

$ docker buildx build --platform linux/amd64,linux/arm64 \
  -t <your-namespace>/my-oci-artifact:latest \
  --push .

Esto crea un único manifiesto de imagen que puedes usar para cada plataforma. El sistema de compilación de personalización selecciona automáticamente la variante de plataforma correcta al compilar cada imagen personalizada.

Important

La interfaz de usuario de personalización solo te dejará seleccionar plataformas que estén disponibles en todos los artefactos OCI que hayas añadido. Si falta una plataforma en algún artefacto OCI, no podrás seleccionar esa plataforma para tu personalización.

Una vez subido a un repositorio en el espacio de nombres de tu organización, el artefacto OCI aparece automáticamente en el flujo de trabajo de personalización cuando seleccionas qué artefactos OCI añadir a tu Docker Hardened Image personalizada.

Mejores prácticas para artefactos OCI

Sigue estas mejores prácticas al crear artefactos OCI para personalizaciones de DHI:

• Usa compilaciones de múltiples etapas: Compila o instala las dependencias en una etapa de compilación y luego copia solo los archivos necesarios a una etapa final FROM scratch. Esto mantiene el artefacto OCI mínimo y libre de herramientas de compilación innecesarias.

• Incluye únicamente archivos esenciales: Los artefactos OCI deben contener solo los archivos que necesites añadir a la imagen personalizada. Evita incluir gestores de paquetes, shells u otras utilidades que no se vayan a utilizar en la imagen final.

• Coincidencia de plataformas de destino: Compila tu artefacto OCI para todas las plataformas que planees utilizar en tus personalizaciones. Usa docker buildx build --platform para crear imágenes multiplataforma cuando sea necesario.

• Usa etiquetas específicas: Etiqueta tus artefactos OCI con versiones o fechas específicas (como v1.0 o 20250101) en lugar de confiar únicamente en latest. Esto garantiza compilaciones reproducibles y facilita el seguimiento de qué artefactos se utilizan en cada personalización.

• Habilita las etiquetas inmutables: Considera habilitar las etiquetas inmutables para tus repositorios de artefactos OCI. Esto evita sobrescrituras accidentales y garantiza que cada versión de tu artefacto OCI permanezca inalterada, mejorando la reproducibilidad y confiabilidad de tus personalizaciones.

Personalizar un Helm chart de DHI

Puedes personalizar los Helm charts de DHI para adaptarlos a las necesidades específicas de tu organización. A través de la interfaz web de Docker Hub, puedes modificar las referencias de las imágenes para que apunten a imágenes replicadas o imágenes personalizadas que hayas creado. Esto te deja crear un chart personalizado y compilado de forma segura con referencias a imágenes almacenadas en Docker Hub u otros registros privados. DHI empaqueta de forma segura los Helm charts personalizados que hacen referencia a tus repositorios, dondequiera que estén almacenados, de forma predeterminada.

Para personalizar las referencias de imágenes, el propietario de una organización debe replicar el repositorio de charts de DHI en su organización en Docker Hub.

Puedes crear una personalización de chart por cada repositorio de Helm charts. Esto es diferente de las personalizaciones de imágenes, donde puedes crear múltiples personalizaciones por repositorio. Si necesitas hacer cambios, puedes editar tu personalización existente. Alternativamente, puedes replicar el mismo repositorio de Helm charts de nuevo y añadir una nueva personalización a la nueva réplica.

Note

Puedes personalizar los charts de Docker Hardened Image como cualquier otro Helm chart utilizando herramientas y prácticas estándar de Helm, como un archivo values.yaml, fuera de Docker Hub. Las siguientes instrucciones describen cómo personalizar las referencias de imágenes del chart utilizando la interfaz web de Docker Hub.

Para personalizar un Helm chart de Docker Hardened Image después de haberlo replicado:

1. Inicia sesión en Docker Hub.

2. Selecciona My Hub.

3. En el menú desplegable de espacios de nombres, selecciona tu organización que tenga un repositorio de DHI replicado.

4. Selecciona Hardened Images > Manage > Mirrored Helm charts.

5. En el repositorio de DHI replicado que quieras personalizar, selecciona el Name.

6. Selecciona la pestaña Customizations.

7. Selecciona Create customization.

   En este punto, las instrucciones en pantalla te guiarán a través del proceso de personalización.

Editar o eliminar una personalización

Para editar o eliminar una personalización de DHI o de un chart, sigue estos pasos:

1. Inicia sesión en Docker Hub.

2. Selecciona My Hub.

3. En el menú desplegable de espacios de nombres, selecciona tu organización que tenga un repositorio replicado.

4. Selecciona Hardened Images > Manage.

5. Selecciona Customizations.

6. En el repositorio de DHI personalizado que quieras gestionar, selecciona el icono de menú en la columna de la extrema derecha. Desde aquí, puedes:

   • Edit: Editar la personalización.
   • Create new: Crear una nueva personalización basada en el repositorio de origen.
   • Delete: Eliminar la personalización.

7. Sigue las instrucciones en pantalla para completar la edición o eliminación.