diff --git a/docs/bake-reference.md b/docs/bake-reference.md
index 2c113f8a..50cf90f9 100644
--- a/docs/bake-reference.md
+++ b/docs/bake-reference.md
@@ -274,13 +274,13 @@ target "db" {
### `target.annotations`
-The `annotations` attribute is a shortcut to allow you to easily set a list of
-annotations on the target.
+The `annotations` attribute lets you add annotations to images built with bake.
+The key takes a list of annotations, in the format of `KEY=VALUE`.
```hcl
target "default" {
output = ["type=image,name=foo"]
- annotations = ["key=value"]
+ annotations = ["org.opencontainers.image.authors=dvdksn"]
}
```
@@ -288,10 +288,25 @@ is the same as
```hcl
target "default" {
- output = ["type=image,name=foo,annotation.key=value"]
+ output = ["type=image,name=foo,annotation.org.opencontainers.image.authors=dvdksn"]
}
```
+By default, the annotation is added to image manifests. You can configure the
+level of the annotations by adding a prefix to the annotation, containing a
+comma-separated list of all the levels that you want to annotate. The following
+example adds annotations to both the image index and manifests.
+
+```hcl
+target "default" {
+ output = ["type=image,name=foo"]
+ annotations = ["index,manifest:org.opencontainers.image.authors=dvdksn"]
+}
+```
+
+Read about the supported levels in
+[Specifying annotation levels](https://docs.docker.com/build/building/annotations/#specifying-annotation-levels).
+
### `target.attest`
The `attest` attribute lets you apply [build attestations][attestations] to the target.
diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md
index 78489e92..758a608f 100644
--- a/docs/reference/buildx_build.md
+++ b/docs/reference/buildx_build.md
@@ -17,7 +17,7 @@ Start a build
|:-------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------------|
| [`--add-host`](https://docs.docker.com/engine/reference/commandline/build/#add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) |
| [`--allow`](#allow) | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) |
-| `--annotation` | `stringArray` | | Add annotation to the image |
+| [`--annotation`](#annotation) | `stringArray` | | Add annotation to the image |
| [`--attest`](#attest) | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) |
| [`--build-arg`](#build-arg) | `stringArray` | | Set build-time variables |
| [`--build-context`](#build-context) | `stringArray` | | Additional build contexts (e.g., name=path) |
@@ -69,6 +69,52 @@ This page describes a subset of the new flags.
## Examples
+### Create annotations (--annotation)
+
+```text
+--annotation="key=value"
+--annotation="[type:]key=value"
+```
+
+Add OCI annotations to the image index, manifest, or descriptor.
+The following example adds the `foo=bar` annotation to the image manifests:
+
+```console
+$ docker buildx build -t TAG --annotation "foo=bar" --push .
+```
+
+You can optionally add a type prefix to specify the level of the annotation. By
+default, the image manifest is annotated. The following example adds the
+`foo=bar` annotation the image index instead of the manifests:
+
+```console
+$ docker buildx build -t TAG --annotation "index:foo=bar" --push .
+```
+
+You can specify multiple types, separated by a comma (,) to add the annotation
+to multiple image components. The following example adds the `foo=bar`
+annotation to image index, descriptors, manifests:
+
+```console
+$ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .
+```
+
+You can also specify a platform qualifier in square brackets (`[os/arch]`) in
+the type prefix, to apply the annotation to a subset of manifests with the
+matching platform. The following example adds the `foo=bar` annotation only to
+the manifest with the `linux/amd64` platform:
+
+```console
+$ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .
+```
+
+Wildcards are not supported in the platform qualifier; you can't specify a type
+prefix like `manifest[linux/*]` to add annotations only to manifests which has
+`linux` as the OS platform.
+
+For more information about annotations, see
+[Annotations](https://docs.docker.com/build/building/annotations/).
+
### Create attestations (--attest)
```text
diff --git a/docs/reference/buildx_imagetools_create.md b/docs/reference/buildx_imagetools_create.md
index e714cd9c..cfce7478 100644
--- a/docs/reference/buildx_imagetools_create.md
+++ b/docs/reference/buildx_imagetools_create.md
@@ -11,7 +11,7 @@ Create a new image based on source images
| Name | Type | Default | Description |
|:---------------------------------|:--------------|:--------|:-----------------------------------------------------------------------------------------|
-| `--annotation` | `stringArray` | | Add annotation to the image |
+| [`--annotation`](#annotation) | `stringArray` | | Add annotation to the image |
| [`--append`](#append) | | | Append to existing manifest |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| [`--dry-run`](#dry-run) | | | Show final image instead of pushing |
@@ -31,6 +31,34 @@ specified, create performs a carbon copy.
## Examples
+### Add annotations to an image (--annotation)
+
+The `--annotation` flag lets you add annotations the image index, manifest,
+and descriptors when creating a new image.
+
+The following command creates a `foo/bar:latest` image with the
+`org.opencontainers.image.authors` annotation on the image index.
+
+```console
+$ docker buildx imagetools create \
+ --annotation "index:org.opencontainers.image.authors=dvdksn" \
+ --tag foo/bar:latest \
+ foo/bar:alpha foo/bar:beta foo/bar:gamma
+```
+
+> **Note**
+>
+> The `imagetools create` command supports adding annotations to the image
+> index and descriptor, using the following type prefixes:
+>
+> - `index:`
+> - `manifest-descriptor:`
+>
+> It doesn't support annotating manifests or OCI layouts.
+
+For more information about annotations, see
+[Annotations](https://docs.docker.com/build/building/annotations/).
+
### Append new sources to an existing manifest list (--append)
Use the `--append` flag to append the new sources to an existing manifest list
@@ -46,7 +74,7 @@ Use the `--dry-run` flag to not push the image, just show it.
### Read source descriptor from a file (-f, --file)
-```
+```text
-f FILE or --file FILE
```
@@ -67,7 +95,7 @@ The supported fields for the descriptor are defined in [OCI spec](https://github
### Set reference for new image (-t, --tag)
-```
+```text
-t IMAGE or --tag IMAGE
```