1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
|
# Image annotations
Buildkit supports attaching [OCI annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md)
to its built image manifests and indexes. These annotations can be used to
attach additional metadata to a built image, which may not be appropriate to
store in the image content itself.
Annotations are similar to, but not a replacement for image labels. Annotations
can be attached at almost every level of the resulting image output, while
labels can be only included in the image configuration object. Additionally,
unless overridden, image labels are inherited by other images that use the
image as a base.
Annotations support multiple pre-defined annotation keys which you can use, or
you can also create your own.
To build an image with annotations, you can use the `image` or `oci` (and
related) exporter types, along with the `annotation.*` option.
For example, to attach a human-readable title to your image, you can use the
following buildctl invocation:
buildctl build ... \
--opt platform=amd64,arm64 \
--output "type=image,name=target,annotation.org.opencontainers.image.title=Target"
This annotation will be added to each built image manifest, so each platform
you built for (in the above, `amd64` and `arm64`) will get a copy of the annotation.
You want to allow different annotations for different platforms, e.g. maybe you
want to provide a different documentation URL per manifest. You can do this
with platform specific annotations, using the `annotation[<platform>].*` syntax
like so:
buildctl build ... \
--opt platform=amd64,arm64 \
--output "type=image,name=target,annotation[linux/amd64].org.opencontainers.image.url=https://example.com/amd64,annotation[linux/arm64].org.opencontainers.image.url=https://example.com/arm64"
Buildkit also allows you to finely control the exact destination where the
annotation will be written to using the syntax `annotation-<type>.*`. You can
write to the following `<type>`s:
- The `manifest` (the default, as above)
- The `manifest-descriptor`
- This adds the annotation into the image index's descriptor for the manifest
- The `index`
- This adds the annotation into the image index root
- If the exporter does not produce an image index, the build will fail.
- The `index-descriptor`
- This adds the annotation into the OCI layout's descriptor for the index
- If the exporter does not produce an image index, the build will fail.
For example, if you want to add the annotation at the image index level, so
that the annotation is shared between all architectures, you can instead:
buildctl build ... \
--opt platform=amd64,arm64 \
--output "type=image,name=target,annotation-index.org.opencontainers.image.title=Target Image"
|
