# Anotaciones 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)][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][manifests], [índices][indexes] y [descriptores][descriptors]. - Las etiquetas describen recursos de Docker, como imágenes, contenedores, redes y volúmenes. La [especificación][specification] 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)][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)][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](/build/exporters/image-registry/). Para especificar anotaciones en la línea de comandos, utiliza la bandera `--annotation` para el comando `docker build`: ```console $ docker build --push --annotation "foo=bar" . ``` Si estás utilizando [Bake](/build/bake/), puedes usar el atributo `annotations` para especificar anotaciones para un objetivo (target) determinado: ```hcl 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](/build/ci/github-actions/annotations/) 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](/reference/cli/docker/buildx/imagetools/create/#annotation). ## 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. ```console {hl_lines=["10-12","19-21"]} $ docker buildx imagetools inspect --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 `@`, donde `` es el hash (digest) del manifiesto: ```console {hl_lines="22-25"} $ docker buildx imagetools inspect @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: ```console $ docker build --annotation ":=" . ``` 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: ```console $ docker build --tag --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: ```console $ 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: ```console $ 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: ```console $ docker build --tag --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`: ```console $ docker build --tag --push --annotation "manifest[linux/amd64]:foo=bar" . ``` ## Información relacionada Artículos relacionados: - [Añadir anotaciones de imagen con GitHub Actions](/build/ci/github-actions/annotations/) - [Especificación de anotaciones OCI][specification] Información de referencia: - [`docker buildx build --annotation`](/reference/cli/docker/buildx/build/#annotation) - [Referencia de archivo Bake: `annotations`](/build/bake/reference/#targetannotations) - [`docker buildx imagetools create --annotation`](/reference/cli/docker/buildx/imagetools/create/#annotation) [specification]: https://github.com/opencontainers/image-spec/blob/main/annotations.md [attestations]: /build/metadata/attestations/ [config]: https://github.com/opencontainers/image-spec/blob/main/config.md [descriptors]: https://github.com/opencontainers/image-spec/blob/main/descriptor.md [indexes]: https://github.com/opencontainers/image-spec/blob/main/image-../metadata.md [labels]: /engine/manage-resources/labels/ [manifests]: https://github.com/opencontainers/image-spec/blob/main/manifest.md