Merge pull request #2161 from crazy-max/0.12_backport_docs-annotations

[0.12 backport] docs: annotations

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
+The `annotations` attribute lets you add annotations to images built with bake.
-annotations on the target.
+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.

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
 
+### <a name="annotation"></a> 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/).
+
 ### <a name="attest"></a> Create attestations (--attest)
 
 ```text

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
 
+### <a name="annotation"></a> 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/).
+
 ### <a name="append"></a> 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.
 
 ### <a name="file"></a> 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
 
 ### <a name="tag"></a> Set reference for new image  (-t, --tag)
 
-```
+```text
 -t IMAGE or --tag IMAGE
 ```