Annotations

Les annotations fournissent des métadonnées descriptives pour les images. Utilisez les annotations pour enregistrer des informations arbitraires et les attacher à votre image, ce qui aide les consommateurs et les outils à comprendre l'origine, le contenu et comment utiliser l'image.

Les annotations sont similaires aux labels, et dans une certaine mesure se chevauchent avec eux. Les deux servent le même objectif : attacher des métadonnées à une ressource. Comme principe général, vous pouvez penser à la différence entre les annotations et les labels comme suit :

• Les annotations décrivent les composants d'image OCI, tels que les manifests, indexes et descriptors.
• Les labels décrivent les ressources Docker, telles que les images, conteneurs, réseaux et volumes.

La specification d'image OCI définit le format des annotations, ainsi qu'un ensemble de clés d'annotation prédéfinies. Respecter les standards spécifiés assure que les métadonnées sur les images peuvent être affichées automatiquement et de manière cohérente, par des outils comme Docker Scout.

Les annotations ne doivent pas être confondues avec les attestations :

• Les attestations contiennent des informations sur comment une image a été construite et ce qu'elle contient. Une attestation est attachée comme un manifeste séparé sur l'index d'image. Les attestations ne sont pas standardisées par l'Open Container Initiative.
• Les annotations contiennent des métadonnées arbitraires sur une image. Les annotations s'attachent à la config d'image comme des labels, ou sur l'index d'image ou le manifeste comme des propriétés.

Ajouter des annotations

Vous pouvez ajouter des annotations à une image au moment du build, ou lors de la création du manifeste ou index d'image.

Note

Le magasin d'images Docker Engine ne prend pas en charge le chargement d'images avec des annotations. Pour construire avec des annotations, assurez-vous de pousser l'image directement vers un registre, en utilisant le flag CLI --push ou l' exportateur registry.

Pour spécifier des annotations en ligne de commande, utilisez le flag --annotation pour la commande docker build :

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

Si vous utilisez Bake, vous pouvez utiliser l'attribut annotations pour spécifier des annotations pour une cible donnée :

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

Pour des exemples sur comment ajouter des annotations aux images construites avec GitHub Actions, voir Ajouter des annotations d'image avec GitHub Actions

Vous pouvez aussi ajouter des annotations à une image créée en utilisant docker buildx imagetools create. Cette commande ne prend en charge que l'ajout d'annotations aux descripteurs d'index ou de manifeste, voir référence CLI.

Inspecter les annotations

Pour voir les annotations sur un index d'image, utilisez la commande docker buildx imagetools inspect. Cela vous montre toutes les annotations pour l'index et les descripteurs (références aux manifestes) que l'index contient. L'exemple suivant montre une annotation org.opencontainers.image.documentation sur un descripteur, et une annotation org.opencontainers.image.authors sur l'index.

$ 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"
  }
}

Pour inspecter les annotations sur un manifeste, utilisez la commande docker buildx imagetools inspect et spécifiez <IMAGE>@<DIGEST>, où <DIGEST> est le digest du manifeste :

$ 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",
  }
}

Spécifier le niveau d'annotation

Par défaut, les annotations sont ajoutées au manifeste d'image. Vous pouvez spécifier à quel niveau (composant d'image OCI) attacher l'annotation en préfixant la chaîne d'annotation avec une déclaration de type spéciale :

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

Les types suivants sont pris en charge :

• manifest: annote les manifestes.
• index: annote l'index racine.
• manifest-descriptor: annote les descripteurs de manifeste dans l'index.
• index-descriptor: annote le descripteur d'index dans la disposition d'image.

Par exemple, pour construire une image avec l'annotation foo=bar attachée à l'index d'image :

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

Notez que le build doit produire le composant que vous spécifiez, sinon le build échouera. Par exemple, ce qui suit ne fonctionne pas, parce que l'exportateur docker ne produit pas d'index :

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

De même, l'exemple suivant ne fonctionne pas non plus, parce que buildx crée une sortie docker par défaut dans certaines circonstances, comme lorsque les attestations de provenance sont explicitement désactivées :

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

Il est possible de spécifier des types, séparés par une virgule, pour ajouter l'annotation à plus d'un niveau. L'exemple suivant crée une image avec l'annotation foo=bar à la fois sur l'index d'image et le manifeste d'image :

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

Vous pouvez aussi spécifier un qualificateur de plateforme entre crochets dans le préfixe de type, pour annoter seulement les composants correspondant à des OS et architectures spécifiques. L'exemple suivant ajoute l'annotation foo=bar seulement au manifeste linux/amd64 :

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

Informations connexes

Articles connexes :

• Ajouter des annotations d'image avec GitHub Actions
• Spécification OCI des annotations

Informations de référence :

• docker buildx build --annotation
• Référence du fichier Bake : annotations
• docker buildx imagetools create --annotation