centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-04-05 02:38:52 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #18891 from dvdksn/build-annotations

Browse Source 
build: annotations
This commit is contained in:
CrazyMax
2023-12-14 11:15:56 +01:00
committed by GitHub
parent cc62fb5887 37b84b1a71
commit 80b0ef6a86
11 changed files with 938 additions and 400 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
_vendor/github.com/docker/buildx/docs/bake-reference.md generated
View File

@@ -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.

1
_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md generated
View File

@@ -109,6 +109,7 @@ insecure-entitlements = [ "network.host", "security.insecure" ]
# configure the containerd runtime
[worker.containerd.runtime]
name = "io.containerd.runc.v2"
path = "/path/to/containerd/runc/shim"
options = { BinaryName = "runc" }
[[worker.containerd.gcpolicy]]

854
_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md generated
View File

File diff suppressed because it is too large Load Diff

6
_vendor/modules.txt
View File

@@ -1,7 +1,7 @@
# github.com/moby/moby v24.0.5+incompatible
# github.com/moby/buildkit v0.13.0-beta1.0.20231113205014-1efcd30d9dd6
# github.com/docker/buildx v0.12.0
# github.com/moby/buildkit v0.13.0-beta1.0.20231214000015-a960fe501f00
# github.com/docker/buildx v0.12.1-0.20231214091505-b68ee824c673
# github.com/docker/scout-cli v1.2.0
# github.com/docker/cli v24.0.8-0.20231213094340-0f82fd88610a+incompatible
# github.com/docker/cli v25.0.0-beta.1+incompatible
# github.com/compose-spec/compose-spec v0.0.0-20231121152139-478928e7c9f8
# github.com/docker/compose/v2 v2.23.3

192
content/build/building/annotations.md Normal file
View File

@@ -0,0 +1,192 @@
---
title: Annotations
description: Annotations specify additional metadata about OCI images
keywords: build, buildkit, annotations, metadata
---
Annotations provide descriptive metadata for images. Use annotations to record
arbitrary information and attach it to your image, which helps consumers and
tools understand the origin, contents, and how to use the image.
Annotations are similar to, and in some sense overlap with, [labels]. Both
serve the same purpose: attach metadata to a resource. As a general principle,
you can think of the difference between annotations and labels as follows:
- Annotations describe OCI image components, such as [manifests], [indexes],
and [descriptors].
- Labels describe Docker resources, such as images, containers, networks, and
volumes.
The OCI image [specification] defines the format of annotations, as well as a set
of pre-defined annotation keys. Adhering to the specified standards ensures
that metadata about images can be surfaced automatically and consistently, by
tools like Docker Scout.
Annotations are not to be confused with [attestations]:
- Attestations contain information about how an image was built and what it contains.
An attestation is attached as a separate manifest on the image index.
Attestations are not standardized by the Open Container Initiative.
- Annotations contain arbitrary metadata about an image.
Annotations attach to the image [config] as labels,
or on the image index or manifest as properties.
## Add annotations
You can add annotations to an image at build-time, or when creating the image
manifest or index.
> **Note**
>
> The Docker Engine image store doesn't support loading images with
> annotations. To build with annotations, make sure to push the image directly
> to a registry, using the `--push` CLI flag or the
> [registry exporter](../exporters/image-registry.md).
To specify annotations on the command line, use the `--annotation` flag for the
`docker build` command:
```console
$ docker build --push --annotation "foo=bar" .
```
If you're using [Bake](../bake/_index.md), you can use the `annotations`
attribute to specify annotations for a given target:
```hcl
target "default" {
output = ["type=registry"]
annotations = ["foo=bar"]
}
```
For examples on how to add annotations to images built with GitHub Actions, see
[Add image annotations with GitHub Actions](../ci/github-actions/annotations.md)
You can also add annotations to an image created using `docker buildx
imagetools create`. This command only supports adding annotations to an index
or manifest descriptors, see
[CLI reference](../../engine/reference/commandline/buildx_imagetools_create.md#annotations).
## Inspect annotations
To view annotations on an **image index**, use the `docker buildx imagetools
inspect` command. This shows you any annotations for the index and descriptors
(references to manifests) that the index contains. The following example shows
an `org.opencontainers.image.documentation` annotation on a descriptor, and an
`org.opencontainers.image.authors` annotation on the index.
```console {hl_lines=["10-12","19-21"]}
$ 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"
}
}
```
To inspect annotations on a manifest, use the `docker buildx imagetools
inspect` command and specify `<IMAGE>@<DIGEST>`, where `<DIGEST>` is the digest
of the manifest:
```console {hl_lines="22-25"}
$ 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",
}
}
```
## Specify annotation level
By default, annotations are added to the image manifest. You can specify which
level(s) to attach the manifest to, by prefixing the annotation string with a
special type declaration:
- `manifest`: annotates manifests.
- `index`: annotates the root index.
- `manifest-descriptor`: annotates manifest descriptors in the index.
- `index-descriptor`: annotates the index descriptor in the image layout.
For example, to build an image with the annotation `foo=bar` attached to the
image index:
```console
$ docker build --tag <IMAGE> --push --annotation "index:foo=bar" .
```
It's possible to specify types, separated by a comma, to add the annotation to
more than one level. The following example creates an image with the annotation
`foo=bar` on both the image index and the image manifest:
```console
$ docker build --tag <IMAGE> --push --annotation "index,manifest:foo=bar" .
```
You can also specify a platform qualifier in the type prefix, to annotate only
components matching specific OS and architectures. The following example adds
the `foo=bar` annotation only to the `linux/amd64` manifest:
```console
$ docker build --tag <IMAGE> --push --annotation "manifest[linux/amd64]:foo=bar" .
```
## Related information
Related articles:
- [Add image annotations with GitHub Actions](../ci/github-actions/annotations.md)
- [Annotations OCI specification][specification]
Reference information:
- [`docker buildx build --annotation`](../../engine/reference/commandline/buildx_build.md#annotation)
- [Bake file reference: `annotations`](../bake/reference.md#targetannotations)
- [`docker buildx imagetools create --annotation`](../../engine/reference/commandline/buildx_imagetools_create.md#annotation)
<!-- links -->
[specification]: https://github.com/opencontainers/image-spec/blob/main/annotations.md
[attestations]: ../attestations/_index.md
[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-index.md
[labels]: ../../config/labels-custom-metadata.md
[manifests]: https://github.com/opencontainers/image-spec/blob/main/manifest.md

165
content/build/ci/github-actions/annotations.md Normal file
View File

@@ -0,0 +1,165 @@
---
title: Add image annotations with GitHub Actions
description: Add OCI annotations to image components using GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, annotations, oci
---
Annotations let you specify arbitrary metadata for OCI image components, such
as manifests, indexes, and descriptors.
To add annotations when building images with GitHub Actions, use the
[metadata-action] to automatically create OCI-compliant annotations. The
metadata action creates an `annotations` output that you can reference, both
with [build-push-action] and [bake-action].
[metadata-action]: https://github.com/docker/metadata-action#overwrite-labels-and-annotations
[build-push-action]: https://github.com/docker/build-push-action/
[bake-action]: https://github.com/docker/bake-action/
{{< tabs >}}
{{< tab name="build-push-action" >}}
```yaml {hl_lines=37}
name: ci
on:
push:
branches:
- "main"
env:
IMAGE_NAME: user/app
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v4
with:
images: ${{ env.IMAGE_NAME }}
- name: Build and push
uses: docker/build-push-action@v5
with:
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
push: true
```
{{< /tab >}}
{{< tab name="bake-action" >}}
```yaml {hl_lines=39}
name: ci
on:
push:
branches:
- "main"
env:
IMAGE_NAME: user/app
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v4
with:
images: ${{ env.IMAGE_NAME }}
- name: Build
uses: docker/bake-action@v3
with:
files: |
./docker-bake.hcl
${{ steps.meta.outputs.bake-file-tags }}
${{ steps.meta.outputs.bake-file-annotations }}
push: true
```
{{< /tab >}}
{{< /tabs >}}
## Configure annotation level
By default, annotations are placed on image manifests. To configure the
[annotation level](../../building/annotations.md#specify-annotation-level), set
the `DOCKER_METADATA_ANNOTATIONS_LEVELS` environment variable on the
`metadata-action` step to a comma-separated list of all the levels that you
want to annotate. For example, setting `DOCKER_METADATA_ANNOTATIONS_LEVELS` to
`index` results in annotations on the image index instead of the manifests.
The following example creates annotations on both the image index and
manifests.
```yaml {hl_lines=33}
name: ci
on:
push:
branches:
- "main"
env:
IMAGE_NAME: user/app
jobs:
docker:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v4
with:
images: ${{ env.IMAGE_NAME }}
env:
DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
- name: Build and push
uses: docker/build-push-action@v5
with:
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
push: true
```

47
data/buildx/docker_buildx_build.yaml
View File

@@ -39,6 +39,7 @@ options:
value_type: stringArray
default_value: '[]'
description: Add annotation to the image
details_url: '#annotation'
deprecated: false
hidden: false
experimental: false
@@ -526,6 +527,52 @@ inherited_options:
kubernetes: false
swarm: false
examples: |-
### Create annotations (--annotation) {#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](/build/building/annotations/).
### Create attestations (--attest) {#attest}
```text

33
data/buildx/docker_buildx_imagetools_create.yaml
View File

@@ -13,6 +13,7 @@ options:
value_type: stringArray
default_value: '[]'
description: Add annotation to the image
details_url: '#annotation'
deprecated: false
hidden: false
experimental: false
@@ -88,6 +89,34 @@ inherited_options:
kubernetes: false
swarm: false
examples: |-
### Add annotations to an image (--annotation) {#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](/build/building/annotations/).
### Append new sources to an existing manifest list (--append) {#append}
Use the `--append` flag to append the new sources to an existing manifest list
@@ -103,7 +132,7 @@ examples: |-
### Read source descriptor from a file (-f, --file) {#file}
```
```text
-f FILE or --file FILE
```
@@ -124,7 +153,7 @@ examples: |-
### Set reference for new image (-t, --tag) {#tag}
```
```text
-t IMAGE or --tag IMAGE
```

4
data/toc.yaml
View File

@@ -1790,6 +1790,8 @@ Manuals:
title: Environment variables
- path: /build/building/secrets/
title: Build secrets
- path: /build/building/annotations/
title: Annotations
- path: /build/building/opentelemetry/
title: OpenTelemetry support
- path: /build/building/base-images/
@@ -1922,6 +1924,8 @@ Manuals:
title: Update Docker Hub repo description
- path: /build/ci/github-actions/attestations/
title: SBOM and provenance attestations
- path: /build/ci/github-actions/annotations/
title: Annotations
- path: /build/release-notes/
title: Release notes
- sectiontitle: Docker Compose

9
go.mod
View File

@@ -6,10 +6,13 @@ toolchain go1.21.1
require (
github.com/compose-spec/compose-spec v0.0.0-20231121152139-478928e7c9f8 // indirect
github.com/docker/buildx v0.12.0 // indirect
github.com/docker/cli v24.0.8-0.20231213094340-0f82fd88610a+incompatible // indirect
github.com/docker/buildx v0.12.1-0.20231214091505-b68ee824c673 // indirect
github.com/docker/cli v25.0.0-beta.1+incompatible // indirect
github.com/docker/compose/v2 v2.23.3 // indirect
github.com/docker/scout-cli v1.2.0 // indirect
github.com/moby/buildkit v0.13.0-beta1.0.20231113205014-1efcd30d9dd6 // indirect
github.com/moby/buildkit v0.13.0-beta1.0.20231214000015-a960fe501f00 // indirect
github.com/moby/moby v24.0.5+incompatible // indirect
)
// buildkit depends on cli v25 beta1, pin to v24
replace github.com/docker/cli => github.com/docker/cli v24.0.8-0.20231213094340-0f82fd88610a+incompatible

4
go.sum
View File

@@ -52,6 +52,8 @@ github.com/docker/buildx v0.11.2 h1:R3p9F0gnI4FwvQ0p40UwdX1T4ugap4UWxY3TFHoP4Ws=
github.com/docker/buildx v0.11.2/go.mod h1:CWAABt10iIuGpleypA3103mplDfcGu0A2AvT03xfpTc=
github.com/docker/buildx v0.12.0 h1:pI4jr4SeH9oHa0SmMvH/lz+Rdqkg+dRa9H/1VXbYgws=
github.com/docker/buildx v0.12.0/go.mod h1:SBLnQH9q+77aVvpvS5LLIly9+nHVlwscl5GEegGMD5g=
github.com/docker/buildx v0.12.1-0.20231214091505-b68ee824c673 h1:mZ2+TyEERNA4GY2xO3kIa7ZhfmUNwveIMxGYWV126dA=
github.com/docker/buildx v0.12.1-0.20231214091505-b68ee824c673/go.mod h1:SBLnQH9q+77aVvpvS5LLIly9+nHVlwscl5GEegGMD5g=
github.com/docker/cli v24.0.2+incompatible h1:QdqR7znue1mtkXIJ+ruQMGQhpw2JzMJLRXp6zpzF6tM=
github.com/docker/cli v24.0.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
github.com/docker/cli v24.0.4+incompatible h1:Y3bYF9ekNTm2VFz5U/0BlMdJy73D+Y1iAAZ8l63Ydzw=
@@ -151,6 +153,8 @@ github.com/moby/buildkit v0.13.0-beta1.0.20231011101155-c444964c2e8f h1:CEiXZq08
github.com/moby/buildkit v0.13.0-beta1.0.20231011101155-c444964c2e8f/go.mod h1:oSHnUZH7sNtAFLyeN1syf46SuzMThKsCQaioNEqJVUk=
github.com/moby/buildkit v0.13.0-beta1.0.20231113205014-1efcd30d9dd6 h1:gfbjHMadWpzz9Jbbo4l73lrkNrP2YvNsKIIg8e5Ra4s=
github.com/moby/buildkit v0.13.0-beta1.0.20231113205014-1efcd30d9dd6/go.mod h1:VE6gCOYRW2hbxnxtt7udKkYMF73YdvkgIrGhkB0EiDA=
github.com/moby/buildkit v0.13.0-beta1.0.20231214000015-a960fe501f00 h1:Ymp+x/hsr6M6R+6j4XVyGaRrhAt1MnGXoN+ZkQ+TuuA=
github.com/moby/buildkit v0.13.0-beta1.0.20231214000015-a960fe501f00/go.mod h1:6MddWPSL5jxy+W8eMMHWDOfZzzRRKWXPZqajw72YHBc=
github.com/moby/locker v1.0.1/go.mod h1:S7SDdo5zpBK84bzzVlKr2V0hz+7x9hWbYC/kq7oQppc=
github.com/moby/moby v24.0.2+incompatible h1:yH+5dRHH1x3XRKzl1THA2aGTy6CHYnkt5N924ADMax8=
github.com/moby/moby v24.0.2+incompatible/go.mod h1:fDXVQ6+S340veQPv35CzDahGBmHsiclFwfEygB/TWMc=