docker/buildx
1
0
Fork 0
mirror of https://gitea.com/Lydanne/buildx.git synced 2025-05-18 00:47:48 +08:00
Code Issues Packages Projects Releases 1 Wiki Activity

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

Browse Source 
[0.12 backport] docs: annotations
This commit is contained in:
CrazyMax 2023-12-14 10:15:05 +01:00 committed by GitHub
commit b68ee824c6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 97 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/bake-reference.md
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.

48
docs/reference/buildx_build.md
View File

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

34
docs/reference/buildx_imagetools_create.md
View File

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