Cómo usar el comando docker buildx history inspect attachment para inspeccionar adjuntos de compilación

Introducción

En este laboratorio, aprenderás a utilizar el comando docker buildx history inspect attachment para examinar los archivos adjuntos asociados con las compilaciones de imágenes de Docker. Comenzarás construyendo una imagen de Docker y adjuntando un archivo a ella utilizando la bandera --attest.

Después de la compilación, explorarás cómo listar el historial de compilaciones para identificar la referencia de la compilación que contiene el archivo adjunto. Finalmente, practicarás la inspección del archivo adjunto utilizando la referencia obtenida, y refinarás la inspección especificando el tipo de adjunto y la plataforma. Esta experiencia práctica demostrará cómo acceder y verificar los metadatos incrustados dentro de tus imágenes de Docker.

Skills Graph

Construir una imagen con un archivo adjunto

En este paso, aprenderemos cómo construir una imagen de Docker y adjuntarle metadatos. Los archivos adjuntos son una forma de incluir información adicional con tu imagen, como la procedencia de la compilación, la lista de materiales de software (SBOM, por sus siglas en inglés) u otros datos relevantes.

Primero, creemos un Dockerfile simple. Navega al directorio ~/project si no estás allí.

cd ~/project

Ahora, crea un archivo llamado Dockerfile usando el editor nano.

nano Dockerfile

Agrega el siguiente contenido al Dockerfile:

FROM alpine:latest
CMD ["echo", "Hello, Docker Attachments!"]

Este Dockerfile es muy simple. Utiliza la imagen alpine:latest como base y define un comando para imprimir un mensaje cuando el contenedor se inicia.

Guarda el archivo y sal de nano (presiona Ctrl + X, luego Y, luego Enter).

A continuación, necesitamos crear un archivo que adjuntaremos a la imagen. Creemos un archivo de texto simple llamado attachment.txt.

nano attachment.txt

Agrega algún contenido a attachment.txt, por ejemplo:

This is an example attachment for the Docker image.
It can contain any relevant metadata.

Guarda el archivo y sal de nano.

Ahora, construiremos la imagen de Docker y adjuntaremos el archivo attachment.txt. Usaremos el comando docker build con la bandera --attest. La bandera --attest te permite especificar un archivo adjunto para incluir en la compilación de la imagen. El formato es type=tipo,dest=destino,src=origen.

En nuestro caso, usaremos type=sbom (Software Bill of Materials) como tipo, dest=/sbom/attachment.txt como ruta de destino dentro del adjunto y src=attachment.txt como archivo de origen en nuestro sistema de archivos local. También etiquetaremos la imagen como my-attached-image:latest.

Antes de construir, asegúrate de tener el plugin buildx necesario instalado. Si no lo tienes, es posible que necesites instalarlo. Sin embargo, para adjuntos básicos, el constructor integrado debería ser suficiente.

Construyamos la imagen:

docker build -t my-attached-image:latest --attest type=sbom,dest=/sbom/attachment.txt,src=attachment.txt .

El . al final del comando especifica el contexto de compilación, que es el directorio actual (~/project).

Deberías ver una salida que indica que la imagen se está construyendo y el adjunto se está procesando.

Una vez completada la compilación, puedes verificar que la imagen fue creada listando tus imágenes locales.

docker images

Deberías ver my-attached-image en la lista.

Listar el historial de compilación para encontrar la referencia

En el paso anterior, construimos una imagen de Docker con un archivo adjunto. Ahora necesitamos encontrar la referencia a este adjunto para poder inspeccionarlo. Los archivos adjuntos están asociados con el historial de compilación, no directamente con la etiqueta final de la imagen.

Podemos usar el comando docker buildx imagetools inspect para ver información sobre la imagen y sus archivos adjuntos asociados. Este comando requiere la referencia de la imagen.

Inspeccionemos la imagen que construimos, my-attached-image:latest.

docker buildx imagetools inspect my-attached-image:latest

Este comando mostrará información detallada sobre el manifiesto de la imagen. Busca la sección attestations en la salida. Esta sección enumera los archivos adjuntos asociados con la imagen.

Dentro de la sección attestations, encontrarás entradas para cada adjunto. Cada entrada tendrá un campo ref. Esta ref es la referencia que necesitamos para inspeccionar el contenido del adjunto. Tendrá un formato similar a sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Copia el valor del campo ref para el adjunto que agregaste (el que tiene type=sbom). Esta es la referencia que usaremos en el siguiente paso.

Por ejemplo, si la salida muestra:

{
  "manifest": {
    ...
  },
  "attestations": [
    {
      "ref": "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "type": "sbom",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    }
  ]
}

La referencia que necesitas es sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890. Ten en cuenta que tu referencia real será diferente.

Mantén esta referencia a mano para el siguiente paso.

Inspeccionar el adjunto usando la referencia

En el paso anterior, encontramos la referencia del adjunto asociado a nuestra imagen Docker usando docker buildx imagetools inspect. Ahora usaremos esta referencia para inspeccionar el contenido del adjunto.

Podemos usar el comando docker buildx attestation inspect para ver los detalles de un adjunto específico usando su referencia.

Recuerda la referencia que obtuviste en el paso anterior. Debe tener el formato sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Reemplaza <attachment_reference> con la referencia real que copiaste.

docker buildx attestation inspect <attachment_reference>

Por ejemplo, si tu referencia era sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890, el comando sería:

docker buildx attestation inspect sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Este comando mostrará el contenido del adjunto. Deberías ver el texto que agregaste al archivo attachment.txt en el Paso 1.

La salida probablemente incluirá algunos metadatos sobre el adjunto, seguidos del contenido real. Busca la sección que contiene el texto "This is an example attachment...".

Esto demuestra cómo puedes recuperar el contenido de un adjunto usando su referencia única. Esto es útil para verificar la integridad y contenido de los datos adjuntos.

Inspeccionar el adjunto especificando tipo y plataforma

En el paso anterior, inspeccionamos un adjunto usando su referencia directa. Sin embargo, también puedes inspeccionar adjuntos asociados a una imagen especificando el tipo de adjunto y la plataforma para la que fue construido. Esto es particularmente útil cuando una imagen tiene múltiples adjuntos de diferentes tipos o para distintas arquitecturas.

Usaremos nuevamente el comando docker buildx attestation inspect, pero esta vez proporcionaremos la referencia de la imagen, el tipo de adjunto y la plataforma.

La referencia de la imagen es my-attached-image:latest.
El tipo de adjunto que usamos fue sbom.
La plataforma para nuestra compilación es típicamente linux/amd64 en el entorno LabEx.

El formato del comando es docker buildx attestation inspect <image_reference> --type <attachment_type> --platform <platform>.

Inspeccionemos el adjunto usando este método:

docker buildx attestation inspect my-attached-image:latest --type sbom --platform linux/amd64

Este comando también debería mostrar el contenido del adjunto, similar al paso anterior. Esto confirma que puedes recuperar la información del adjunto especificando la imagen, tipo y plataforma.

Este método es más conveniente cuando conoces el tipo de adjunto que buscas y la plataforma de la imagen, ya que no necesitas primero encontrar la referencia específica del adjunto usando imagetools inspect.

Ahora has aprendido cómo construir una imagen Docker con un adjunto y cómo inspeccionar ese adjunto usando tanto su referencia directa como especificando la imagen, tipo y plataforma.

Resumen

En este laboratorio, aprendimos cómo construir una imagen Docker con un archivo adjunto utilizando el comando docker build con el flag --attest, especificando el tipo de adjunto, el destino dentro del adjunto y el archivo fuente. Luego exploramos cómo listar el historial de compilación usando docker buildx history para identificar la referencia de la compilación que contiene el adjunto.

Finalmente, practicamos la inspección del archivo adjunto usando el comando docker buildx history inspect attachment, primero proporcionando la referencia de compilación y destino del adjunto, y posteriormente especificando también el tipo de adjunto y plataforma para una inspección más dirigida. Este proceso demostró cómo incluir y acceder a metadatos adicionales asociados con una compilación de imagen Docker.