Justin Chadwell
3 years ago
parent
cc7e11da99
commit
93e9b9874a
@ -0,0 +1,49 @@
|
||||
# Image exporter
|
||||
|
||||
The `image` exporter outputs the build result into a container image format.
|
||||
The `registry` exporter is identical, but it automatically pushes the result by
|
||||
setting `push=true`.
|
||||
|
||||
## Synopsis
|
||||
|
||||
Build a container image using the `image` exporter:
|
||||
|
||||
```console
|
||||
$ docker buildx build --output type=image[,parameters] .
|
||||
```
|
||||
|
||||
The following table describes the available parameters that you can pass to
|
||||
`--output` for `type=image`:
|
||||
|
||||
| Parameter | Value | Default | Description |
|
||||
| ----------------- | ---------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `name` | String | | Specify image name(s) |
|
||||
| `push` | `true`,`false` | `false` | Push after creating the image. |
|
||||
| `push-by-digest` | `true`,`false` | `false` | Push image without name. |
|
||||
| `registry.insecure` | `true`,`false` | `false` | Allow pushing to insecure registry. |
|
||||
| `dangling-name-prefix` | `<value>` | | Name image with `prefix@<digest>`, used for anonymous images |
|
||||
| `name-canonical` | `true`,`false` | | Add additional canonical name `name@<digest>` |
|
||||
| `compression` | `uncompressed`,`gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [compression][1] |
|
||||
| `compression-level` | `0..22` | | Compression level, see [compression][1] |
|
||||
| `force-compression` | `true`,`false` | `false` | Forcefully apply compression, see [compression][1] |
|
||||
| `oci-mediatypes` | `true`,`false` | `false` | Use OCI mediatypes in exporter manifests, see [OCI Media types][2] |
|
||||
| `buildinfo` | `true`,`false` | `true` | Attach inline [build info][3] |
|
||||
| `buildinfo-attrs` | `true`,`false` | `false` | Attach inline [build info attributes][3] |
|
||||
| `unpack` | `true`,`false` | `false` | Unpack image after creation (for use with containerd) |
|
||||
| `store` | `true`,`false` | `true` | Store the result images to the worker's (e.g. containerd) image store as well as ensures that the image has all blobs in the content store. Ignored if the worker doesn't have image store (e.g. OCI worker). |
|
||||
| `annotation.<key>` | String | | Attach an annotation with the respective `key` and `value` to the built image,see [annotations][4] |
|
||||
|
||||
[1]: index.md#cache-compression
|
||||
[2]: index.md#oci-media-types
|
||||
[3]: index.md#build-info
|
||||
[4]: #annotations
|
||||
|
||||
## Annotations
|
||||
|
||||
<!-- FIXME: how to present this info from buildkit -->
|
||||
|
||||
https://github.com/opencontainers/image-spec/blob/main/annotations.md
|
||||
|
||||
https://github.com/moby/buildkit/blob/master/docs/annotations.md
|
||||
|
||||
## Further reading
|
||||
@ -0,0 +1,170 @@
|
||||
# Exporters overview
|
||||
|
||||
BuildKit exporters allow outputting the results of a build to different
|
||||
locations.
|
||||
|
||||
...
|
||||
|
||||
Buildx supports the following exporters:
|
||||
|
||||
- `image` / `registry`: exports the build result into a container image.
|
||||
- `local`: exports the build root filesystem into a local directory.
|
||||
- `tar`: packs the build root filesystem into a local tarball.
|
||||
- `oci`: exports the build result as a local
|
||||
[OCI image layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md).
|
||||
- `docker`: exports the build result as a local
|
||||
[Docker image specification](https://github.com/docker/docker/blob/v20.10.2/image/spec/v1.2.md).
|
||||
|
||||
Each exporter creates outputs designed for different use cases. To build
|
||||
container images ready to load or push to a registry, you can use the `image`
|
||||
exporter. Alternatively, you can use the `oci` or `docker` exporters to export
|
||||
the container image to disk directly, to import or post-process as you want.
|
||||
Finally, if you just want the output of the final root filesystem, you can use
|
||||
the `local` or `tar` exporters.
|
||||
|
||||
## Command syntax
|
||||
|
||||
To use any of the exporters, you need to specify it by either using the
|
||||
available shorthands, or passing the exporter name and its parameters to the
|
||||
[`--output`](../../reference/buildx_build.md#output) flag.
|
||||
|
||||
To get the full flexibility out of the various exporters buildkit has to offer,
|
||||
you'll need to use the full form of the `--output` flag. However, for
|
||||
ease-of-use, buildx also offers various familiar short-hands.
|
||||
|
||||
### Pushing images
|
||||
|
||||
You may already be familiar with the following `buildx` command syntax using
|
||||
the `-t`/`--tag` and `--push` shorthands to push the resulting image to a
|
||||
registry:
|
||||
|
||||
```console
|
||||
$ docker buildx build . --tag <registry>/<image> --push
|
||||
```
|
||||
|
||||
You can replicate this command without the shorthands, using the full
|
||||
`--output` flag:
|
||||
|
||||
```console
|
||||
$ docker buildx build . --output type=image,name=<registry>/<image>,push=true
|
||||
```
|
||||
|
||||
### Loading images
|
||||
|
||||
Images built using the [Docker "default" Buildx driver](../../guides/drivers/docker.md)
|
||||
will be automatically loaded into the engine. This means you can run them
|
||||
immediately, and they'll be visible in the `docker images` view.
|
||||
|
||||
Images built using any of theh other drivers will not be automatically
|
||||
loaded, and instead require manually adding the `--load` flag:
|
||||
|
||||
```console
|
||||
$ docker buildx build . --tag <registry>/<image> --load
|
||||
```
|
||||
|
||||
## Multiple exporters
|
||||
|
||||
While [currently](https://github.com/moby/buildkit/pull/2760) only a single
|
||||
exporter is supported, you can perform multiple builds one after another to
|
||||
export the same content twice - because of caching, as long as nothing changes
|
||||
inbetween, then all builds after the first should be instantaneous.
|
||||
|
||||
For example, using both the [`image` exporter](./image.md) and the
|
||||
[`local` exporter](./local.md)
|
||||
|
||||
```console
|
||||
$ docker buildx build --output type=image,tag=<user>/<image> .
|
||||
$ docker buildx build --output type=local,dest=<path/to/output> .
|
||||
```
|
||||
|
||||
## Configuration options
|
||||
|
||||
This section describes some of the configuration options available for
|
||||
exporters. The options described here are common for at least two or more
|
||||
exporter types. Additionally, the different exporters types support specific
|
||||
parameters as well. See the detailed page about each exporter for more
|
||||
information about which configuration parameters apply.
|
||||
|
||||
The common parameters described here are:
|
||||
|
||||
- [Compression](#compression)
|
||||
- [OCI media type](#oci-media-type)
|
||||
|
||||
### Compression
|
||||
|
||||
For all exporters that compress their output, you can configure the exact
|
||||
compression algorithm and level to use. While the default values provide a good
|
||||
out-of-the-box experience, you may wish to tweak the parameters to optimize for
|
||||
storage vs compute costs. Changing the compression parameters can reduce
|
||||
storage space required, and improve image download times, but will increase
|
||||
build times.
|
||||
|
||||
To select the compression algorithm, you can use the `compression` option. For
|
||||
example, to build an `image` with `compression=zstd`:
|
||||
|
||||
```console
|
||||
$ docker buildx build \
|
||||
--output type=image,name=<registry>/<image>,push=true,compression=zstd .
|
||||
```
|
||||
|
||||
Use the `compression-level=<value>` option alongside the `compression`
|
||||
parameter to choose a compression level for the algorithms which support it:
|
||||
|
||||
- 0-9 for `gzip` and `estargz`
|
||||
- 0-22 for `zstd`
|
||||
|
||||
As a general rule, the higher the number, the smaller the resulting file will
|
||||
be, and the longer the compression will take to run.
|
||||
|
||||
Use the `force-compression=true` option to force re-compressing layers imported
|
||||
from a previous image, if the requested compression algorithm is different from
|
||||
the previous compression algorithm.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The `gzip` and `estargz` compression methods use the
|
||||
> [`compress/gzip` package](https://pkg.go.dev/compress/gzip), while `zstd` uses
|
||||
> the
|
||||
> [`github.com/klauspost/compress/zstd` package](https://github.com/klauspost/compress/tree/master/zstd).
|
||||
|
||||
### OCI media types
|
||||
|
||||
Exporters that output container images, support creating images with either
|
||||
Docker media types or with OCI media types. By default, BuildKit exports
|
||||
images using Docker image types.
|
||||
|
||||
To export images with OCI mediatypes set, use the `oci-mediatypes` property. For
|
||||
example, with the `image` exporter:
|
||||
|
||||
```console
|
||||
$ docker buildx build \
|
||||
--output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .
|
||||
```
|
||||
|
||||
### Build info
|
||||
|
||||
Exporters that output container images, allow embedding information about the
|
||||
build, including information on the original build request and sources used
|
||||
during the build.
|
||||
|
||||
This build info is attached to the image configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"moby.buildkit.buildinfo.v0": "<base64>"
|
||||
}
|
||||
```
|
||||
|
||||
By default, the build dependencies are inlined in the image configuration. You
|
||||
can disable this behavior using the `buildinfo` attribute.
|
||||
|
||||
## What's next
|
||||
|
||||
Read about each of the exporters to learn about how they work and how to
|
||||
use them:
|
||||
|
||||
- [`image`](./image.md) / [`registry`](./image.md)
|
||||
- [`local`](./local.md)
|
||||
- [`tar`](./tar.md)
|
||||
- [`oci`](./oci.md)
|
||||
- [`docker`](./docker.md)
|
||||
@ -0,0 +1,25 @@
|
||||
# Local exporter
|
||||
|
||||
The `local` exporter outputs the root filesystem of the build result into a
|
||||
local directory. This exporter can be used when using buildkit to build
|
||||
something other than container images.
|
||||
|
||||
This exporter is often paired with [multi-stage]() builds, to export only a
|
||||
minimal number of build artifacts, such as self-contained binaries.
|
||||
|
||||
## Synopsis
|
||||
|
||||
Build a container image using the `local` exporter:
|
||||
|
||||
```console
|
||||
$ docker buildx build --output type=local[,parameters] .
|
||||
```
|
||||
|
||||
The following table describes the available parameters that you can pass to
|
||||
`--output` for `type=local`:
|
||||
|
||||
| Parameter | Value | Default | Description |
|
||||
| --------- | ------ | ------- | --------------------- |
|
||||
| `dest` | String | | Path to copy files to |
|
||||
|
||||
## Further reading
|
||||
@ -0,0 +1,41 @@
|
||||
# OCI exporter
|
||||
|
||||
The `oci` exporter outputs the build result into an
|
||||
[OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)
|
||||
tarball.
|
||||
|
||||
The `docker` exporter behaves the same, however, it exports a docker image
|
||||
layout instead.
|
||||
|
||||
## Synopsis
|
||||
|
||||
Build a container image using the `image` exporter:
|
||||
|
||||
```console
|
||||
$ docker buildx build --output type=image[,parameters] .
|
||||
```
|
||||
|
||||
The following table describes the available parameters that you can pass to
|
||||
`--output` for `type=image`:
|
||||
|
||||
| Parameter | Value | Default | Description |
|
||||
| ----------------- | ---------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `name` | String | | Specify image name(s) |
|
||||
| `compression` | `uncompressed`,`gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [compression][1] |
|
||||
| `compression-level` | `0..22` | | Compression level, see [compression][1] |
|
||||
| `force-compression` | `true`,`false` | `false` | Forcefully apply compression, see [compression][1] |
|
||||
| `oci-mediatypes` | `true`,`false` | `false` | Use OCI mediatypes in exporter manifests, see [OCI Media types][2] |
|
||||
| `buildinfo` | `true`,`false` | `true` | Attach inline [build info][3] |
|
||||
| `buildinfo-attrs` | `true`,`false` | `false` | Attach inline [build info attributes][3] |
|
||||
| `annotation.<key>` | String | | Attach an annotation with the respective `key` and `value` to the built image,see [annotations][4] |
|
||||
|
||||
[1]: index.md#cache-compression
|
||||
[2]: index.md#oci-media-types
|
||||
[3]: index.md#build-info
|
||||
[4]: #annotations
|
||||
|
||||
## Annotations
|
||||
|
||||
The annotation options are the same as for the [`image` exporter](image.md#annotations).
|
||||
|
||||
## Further reading
|
||||
@ -0,0 +1,23 @@
|
||||
# Tarball exporter
|
||||
|
||||
The `tar` exporter outputs the root filesystem from the build result into a
|
||||
local tarball file. This exporter operates similarly to the [`local` exporter](local.md),
|
||||
however, instead of exporting multiple files together, it bundles all of them
|
||||
up together into a POSIX tar.
|
||||
|
||||
## Synopsis
|
||||
|
||||
Build a container image using the `tar` exporter:
|
||||
|
||||
```console
|
||||
$ docker buildx build --output type=tar[,parameters] .
|
||||
```
|
||||
|
||||
The following table describes the available parameters that you can pass to
|
||||
`--output` for `type=tar`:
|
||||
|
||||
| Parameter | Value | Default | Description |
|
||||
| --------- | ------ | ------- | ------------------------------- |
|
||||
| `dest` | String | | Path to generate the tarball at |
|
||||
|
||||
## Further reading
|
||||
Loading…
Reference in New Issue