Compartir comentarios
Las respuestas se generan en base a la documentación.

Anotaciones

Tabla de contenidos

Las anotaciones proporcionan metadatos descriptivos para las imágenes. Utiliza anotaciones para registrar información arbitraria y adjuntarla a tu imagen, lo que ayuda a los consumidores y herramientas a comprender el origen, el contenido y cómo utilizar la imagen.

Las anotaciones son similares a las etiquetas (labels) y, en cierto sentido, se superponen. Ambas sirven para el mismo propósito: adjuntar metadatos a un recurso. Como principio general, puedes pensar en la diferencia entre anotaciones y etiquetas de la siguiente manera:

  • Las anotaciones describen componentes de imagen OCI, como manifiestos, índices y descriptores.
  • Las etiquetas describen recursos de Docker, como imágenes, contenedores, redes y volúmenes.

La especificación de la imagen OCI define el formato de las anotaciones, así como un conjunto de claves de anotación predefinidas. Adherirse a los estándares especificados garantiza que los metadatos sobre las imágenes se puedan mostrar de forma automática y consistente por herramientas como Docker Scout.

Las anotaciones no deben confundirse con las atestaciones (attestations):

  • Las atestaciones contienen información sobre cómo se compiló una imagen y qué contiene. Una atestación se adjunta como un manifiesto independiente en el índice de la imagen. Las atestaciones no están estandarizadas por la Open Container Initiative.
  • Las anotaciones contienen metadatos arbitrarios sobre una imagen. Las anotaciones se adjuntan a la configuración (config) de la imagen como etiquetas, o en el índice o manifiesto de la imagen como propiedades.

Añadir anotaciones

Puedes añadir anotaciones a una imagen en el momento de la compilación, o al crear el manifiesto o índice de la imagen.

Note

El almacenamiento de imágenes de Docker Engine no admite la carga de imágenes con anotaciones. Para compilar con anotaciones, asegúrate de subir la imagen directamente a un registro, utilizando la bandera de CLI --push o el exportador de registro.

Para especificar anotaciones en la línea de comandos, utiliza la bandera --annotation para el comando docker build:

$ docker build --push --annotation "foo=bar" .

Si estás utilizando Bake, puedes usar el atributo annotations para especificar anotaciones para un objetivo (target) determinado:

target "default" {
  output = ["type=registry"]
  annotations = ["foo=bar"]
}

Para ver ejemplos sobre cómo añadir anotaciones a imágenes compiladas con GitHub Actions, consulta Añadir anotaciones de imagen con GitHub Actions

También puedes añadir anotaciones a una imagen creada mediante docker buildx imagetools create. Este comando solo admite añadir anotaciones a descriptores de índice o de manifiesto, consulta la referencia de CLI.

Inspeccionar anotaciones

Para ver las anotaciones en un índice de imagen, utiliza el comando docker buildx imagetools inspect. Esto te muestra cualquier anotación para el índice y los descriptores (referencias a manifiestos) que contiene el índice. El siguiente ejemplo muestra una anotación org.opencontainers.image.documentation en un descriptor y una anotación org.opencontainers.image.authors en el índice.

$ docker buildx imagetools inspect <IMAGE> --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb",
      "size": 911,
      "annotations": {
        "org.opencontainers.image.documentation": "https://foo.example/docs",
      },
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
  ],
  "annotations": {
    "org.opencontainers.image.authors": "dvdksn"
  }
}

Para inspeccionar las anotaciones en un manifiesto, utiliza el comando docker buildx imagetools inspect y especifica <IMAGE>@<DIGEST>, donde <DIGEST> es el hash (digest) del manifiesto:

$ docker buildx imagetools inspect <IMAGE>@sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:4368b6959a78b412efa083c5506c4887e251f1484ccc9f0af5c406d8f76ece1d",
    "size": 850
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:2c03dbb20264f09924f9eab176da44e5421e74a78b09531d3c63448a7baa7c59",
      "size": 3333033
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:4923ad480d60a548e9b334ca492fa547a3ce8879676685b6718b085de5aaf142",
      "size": 61887305
    }
  ],
  "annotations": {
    "index,manifest:org.opencontainers.image.vendor": "foocorp",
    "org.opencontainers.image.source": "https://git.example/foo.git",
  }
}

Especificar el nivel de la anotación

Por defecto, las anotaciones se añaden al manifiesto de la imagen. Puedes especificar a qué nivel (componente de la imagen OCI) adjuntar la anotación prefijando la cadena de anotación con una declaración de tipo especial:

$ docker build --annotation "<TYPE>:<KEY>=<VALUE>" .

Se admiten los siguientes tipos:

  • manifest: anota manifiestos.
  • index: anota el índice raíz.
  • manifest-descriptor: anota los descriptores de manifiesto en el índice.
  • index-descriptor: anota el descriptor de índice en la distribución de la imagen (image layout).

Por ejemplo, para compilar una imagen con la anotación foo=bar adjunta al índice de la imagen:

$ docker build --tag <IMAGE> --push --annotation "index:foo=bar" .

Ten en cuenta que la compilación debe producir el componente que especifiques; de lo contrario, la compilación fallará. Por ejemplo, lo siguiente no funciona porque el exportador docker no produce un índice:

$ docker build --output type=docker --annotation "index:foo=bar" .

Del mismo modo, el siguiente ejemplo tampoco funciona, porque buildx crea una salida docker por defecto en algunas circunstancias, como cuando las atestaciones de procedencia (provenance attestations) están explitamente desactivadas:

$ docker build --provenance=false --annotation "index:foo=bar" .

Es posible especificar tipos, separados por una coma, para añadir la anotación en más de un nivel. El siguiente ejemplo crea una imagen con la anotación foo=bar tanto en el índice de la imagen como en el manifiesto de la imagen:

$ docker build --tag <IMAGE> --push --annotation "index,manifest:foo=bar" .

También puedes especificar un calificador de plataforma entre corchetes en el prefijo del tipo, para anotar únicamente componentes que coincidan con sistemas operativos y arquitecturas específicas. El siguiente ejemplo añade la anotación foo=bar solo al manifiesto linux/amd64:

$ docker build --tag <IMAGE> --push --annotation "manifest[linux/amd64]:foo=bar" .

Información relacionada

Artículos relacionados:

Información de referencia: