From e59aecf03464703b26a2c36c739b6c6683a5de78 Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Thu, 9 Sep 2021 10:29:08 +0200 Subject: [PATCH] Remove YAML docs from the repo Signed-off-by: CrazyMax --- .github/workflows/validate.yml | 15 + .yamllint.yml | 1 - docker-bake.hcl | 9 + docs/generate.go | 55 +- docs/reference/docker_buildx.yaml | 46 - docs/reference/docker_buildx_bake.yaml | 946 ------------------ docs/reference/docker_buildx_build.yaml | 649 ------------ docs/reference/docker_buildx_create.yaml | 297 ------ docs/reference/docker_buildx_du.yaml | 39 - docs/reference/docker_buildx_imagetools.yaml | 28 - .../docker_buildx_imagetools_create.yaml | 118 --- .../docker_buildx_imagetools_inspect.yaml | 58 -- docs/reference/docker_buildx_inspect.yaml | 66 -- docs/reference/docker_buildx_install.yaml | 21 - docs/reference/docker_buildx_ls.yaml | 38 - docs/reference/docker_buildx_prune.yaml | 68 -- docs/reference/docker_buildx_rm.yaml | 39 - docs/reference/docker_buildx_stop.yaml | 23 - docs/reference/docker_buildx_uninstall.yaml | 21 - docs/reference/docker_buildx_use.yaml | 43 - docs/reference/docker_buildx_version.yaml | 29 - hack/dockerfiles/docs.Dockerfile | 4 +- hack/update-docs | 3 +- 23 files changed, 77 insertions(+), 2539 deletions(-) delete mode 100644 docs/reference/docker_buildx.yaml delete mode 100644 docs/reference/docker_buildx_bake.yaml delete mode 100644 docs/reference/docker_buildx_build.yaml delete mode 100644 docs/reference/docker_buildx_create.yaml delete mode 100644 docs/reference/docker_buildx_du.yaml delete mode 100644 docs/reference/docker_buildx_imagetools.yaml delete mode 100644 docs/reference/docker_buildx_imagetools_create.yaml delete mode 100644 docs/reference/docker_buildx_imagetools_inspect.yaml delete mode 100644 docs/reference/docker_buildx_inspect.yaml delete mode 100644 docs/reference/docker_buildx_install.yaml delete mode 100644 docs/reference/docker_buildx_ls.yaml delete mode 100644 docs/reference/docker_buildx_prune.yaml delete mode 100644 docs/reference/docker_buildx_rm.yaml delete mode 100644 docs/reference/docker_buildx_stop.yaml delete mode 100644 docs/reference/docker_buildx_uninstall.yaml delete mode 100644 docs/reference/docker_buildx_use.yaml delete mode 100644 docs/reference/docker_buildx_version.yaml diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index ed506742..f28f8aaa 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -31,3 +31,18 @@ jobs: name: Run run: | make ${{ matrix.target }} + + validate-docs-yaml: + runs-on: ubuntu-latest + needs: + - validate + steps: + - + name: Checkout + uses: actions/checkout@v2 + - + name: Run + run: | + make docs + env: + FORMATS: yaml diff --git a/.yamllint.yml b/.yamllint.yml index a995d0bf..e190c161 100644 --- a/.yamllint.yml +++ b/.yamllint.yml @@ -1,6 +1,5 @@ ignore: | /vendor - /docs/reference extends: default diff --git a/docker-bake.hcl b/docker-bake.hcl index 997bda20..7522f775 100644 --- a/docker-bake.hcl +++ b/docker-bake.hcl @@ -7,6 +7,9 @@ variable "BIN_OUT" { variable "RELEASE_OUT" { default = "./release-out" } +variable "DOCS_FORMATS" { + default = "md" +} // Special target: https://github.com/docker/metadata-action#bake-definition target "meta-helper" { @@ -43,6 +46,9 @@ target "validate-vendor" { target "validate-docs" { inherits = ["_common"] + args = { + FORMATS = DOCS_FORMATS + } dockerfile = "./hack/dockerfiles/docs.Dockerfile" target = "validate" output = ["type=cacheonly"] @@ -64,6 +70,9 @@ target "update-vendor" { target "update-docs" { inherits = ["_common"] + args = { + FORMATS = DOCS_FORMATS + } dockerfile = "./hack/dockerfiles/docs.Dockerfile" target = "update" output = ["./docs/reference"] diff --git a/docs/generate.go b/docs/generate.go index a6bfcffa..27a9f483 100644 --- a/docs/generate.go +++ b/docs/generate.go @@ -8,19 +8,25 @@ import ( "github.com/docker/buildx/commands" clidocstool "github.com/docker/cli-docs-tool" "github.com/docker/cli/cli/command" + "github.com/pkg/errors" "github.com/spf13/cobra" + "github.com/spf13/pflag" ) -const sourcePath = "docs/reference/" +const defaultSourcePath = "docs/reference/" -func main() { +type options struct { + source string + formats []string +} + +func gen(opts *options) error { log.SetFlags(0) dockerCLI, err := command.NewDockerCli() if err != nil { - log.Printf("ERROR: %+v", err) + return err } - cmd := &cobra.Command{ Use: "docker [OPTIONS] COMMAND [ARG...]", Short: "The base command for the Docker CLI.", @@ -31,12 +37,47 @@ func main() { clidocstool.DisableFlagsInUseLine(cmd) cwd, _ := os.Getwd() - source := filepath.Join(cwd, sourcePath) + source := filepath.Join(cwd, opts.source) if err = os.MkdirAll(source, 0755); err != nil { - log.Printf("ERROR: %+v", err) + return err } - if err = clidocstool.GenTree(cmd, source); err != nil { + + for _, format := range opts.formats { + switch format { + case "md": + if err = clidocstool.GenMarkdownTree(cmd, source); err != nil { + return err + } + case "yaml": + if err = clidocstool.GenYamlTree(cmd, source); err != nil { + return err + } + default: + return errors.Errorf("unknwown doc format %q", format) + } + } + + return nil +} + +func run() error { + opts := &options{} + flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError) + flags.StringVar(&opts.source, "source", defaultSourcePath, "Docs source folder") + flags.StringSliceVar(&opts.formats, "formats", []string{}, "Format (md, yaml)") + if err := flags.Parse(os.Args[1:]); err != nil { + return err + } + if len(opts.formats) == 0 { + return errors.New("Docs format required") + } + return gen(opts) +} + +func main() { + if err := run(); err != nil { log.Printf("ERROR: %+v", err) + os.Exit(1) } } diff --git a/docs/reference/docker_buildx.yaml b/docs/reference/docker_buildx.yaml deleted file mode 100644 index 604575cb..00000000 --- a/docs/reference/docker_buildx.yaml +++ /dev/null @@ -1,46 +0,0 @@ -command: docker buildx -short: Build with BuildKit -long: Build with BuildKit -pname: docker -plink: docker.yaml -cname: -- docker buildx bake -- docker buildx build -- docker buildx create -- docker buildx du -- docker buildx imagetools -- docker buildx inspect -- docker buildx ls -- docker buildx prune -- docker buildx rm -- docker buildx stop -- docker buildx use -- docker buildx version -clink: -- docker_buildx_bake.yaml -- docker_buildx_build.yaml -- docker_buildx_create.yaml -- docker_buildx_du.yaml -- docker_buildx_imagetools.yaml -- docker_buildx_inspect.yaml -- docker_buildx_ls.yaml -- docker_buildx_prune.yaml -- docker_buildx_rm.yaml -- docker_buildx_stop.yaml -- docker_buildx_use.yaml -- docker_buildx_version.yaml -options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_bake.yaml b/docs/reference/docker_buildx_bake.yaml deleted file mode 100644 index d0a624e9..00000000 --- a/docs/reference/docker_buildx_bake.yaml +++ /dev/null @@ -1,946 +0,0 @@ -command: docker buildx bake -aliases: f -short: Build from a file -long: |- - Bake is a high-level build command. Each specified target will run in parallel - as part of the build. - - Read [High-level build options](https://github.com/docker/buildx#high-level-build-options) - for introduction. - - Please note that `buildx bake` command may receive backwards incompatible - features in the future if needed. We are looking for feedback on improving the - command and extending the functionality further. -usage: docker buildx bake [OPTIONS] [TARGET...] -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: file - shorthand: f - value_type: stringArray - default_value: '[]' - description: Build definition file - details_url: '#file' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: load - value_type: bool - default_value: "false" - description: Shorthand for --set=*.output=type=docker - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: metadata-file - value_type: string - description: Write build result metadata to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-cache - value_type: bool - default_value: "false" - description: Do not use cache when building the image - details_url: '#no-cache' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: print - value_type: bool - default_value: "false" - description: Print the options without building - details_url: '#print' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: progress - value_type: string - default_value: auto - description: | - Set type of progress output (auto, plain, tty). Use plain to show container output - details_url: '#progress' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Always attempt to pull a newer version of the image - details_url: '#pull' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: push - value_type: bool - default_value: "false" - description: Shorthand for --set=*.output=type=registry - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: set - value_type: stringArray - default_value: '[]' - description: 'Override target value (eg: targetpattern.key=value)' - details_url: '#set' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Specify a build definition file (-f, --file) {#file} - - By default, `buildx bake` looks for build definition files in the current - directory, the following are parsed: - - - `docker-compose.yml` - - `docker-compose.yaml` - - `docker-bake.json` - - `docker-bake.override.json` - - `docker-bake.hcl` - - `docker-bake.override.hcl` - - Use the `-f` / `--file` option to specify the build definition file to use. The - file can be a Docker Compose, JSON or HCL file. If multiple files are specified - they are all read and configurations are combined. - - The following example uses a Docker Compose file named `docker-compose.dev.yaml` - as build definition file, and builds all targets in the file: - - ```console - $ docker buildx bake -f docker-compose.dev.yaml - - [+] Building 66.3s (30/30) FINISHED - => [frontend internal] load build definition from Dockerfile 0.1s - => => transferring dockerfile: 36B 0.0s - => [backend internal] load build definition from Dockerfile 0.2s - => => transferring dockerfile: 3.73kB 0.0s - => [database internal] load build definition from Dockerfile 0.1s - => => transferring dockerfile: 5.77kB 0.0s - ... - ``` - - Pass the names of the targets to build, to build only specific target(s). The - following example builds the `backend` and `database` targets that are defined - in the `docker-compose.dev.yaml` file, skipping the build for the `frontend` - target: - - ```console - $ docker buildx bake -f docker-compose.dev.yaml backend database - - [+] Building 2.4s (13/13) FINISHED - => [backend internal] load build definition from Dockerfile 0.1s - => => transferring dockerfile: 81B 0.0s - => [database internal] load build definition from Dockerfile 0.2s - => => transferring dockerfile: 36B 0.0s - => [backend internal] load .dockerignore 0.3s - ... - ``` - - You can also use a remote `git` bake definition: - - ```console - $ docker buildx bake "git://github.com/docker/cli#master" --print - #1 [internal] load git source git://github.com/docker/cli#master - #1 0.686 2776a6d694f988c0c1df61cad4bfac0f54e481c8 refs/heads/master - #1 CACHED - { - "group": { - "default": [ - "binary" - ] - }, - "target": { - "binary": { - "context": "git://github.com/docker/cli#master", - "dockerfile": "Dockerfile", - "args": { - "BASE_VARIANT": "alpine", - "GO_STRIP": "", - "VERSION": "" - }, - "target": "binary", - "platforms": [ - "local" - ], - "output": [ - "build" - ] - } - } - } - ``` - - As you can see the context is fixed to `git://github.com/docker/cli` even if - [no context is actually defined](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26) - in the definition. - - If you want to access the main context for bake command from a bake file - that has been imported remotely, you can use the `BAKE_CMD_CONTEXT` builtin var: - - ```console - $ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl - target "default" { - context = BAKE_CMD_CONTEXT - dockerfile-inline = < [4/4] RUN ls -l && stop: - #8 0.101 total 0 - #8 0.102 -rw-r--r-- 1 root root 0 Jul 27 18:47 bar - #8 0.102 -rw-r--r-- 1 root root 0 Jul 27 18:47 foo - #8 0.102 /bin/sh: stop: not found - ``` - - ```console - $ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#master" --print - #1 [internal] load git source git://github.com/tonistiigi/buildx#remote-test - #1 0.401 577303add004dd7efeb13434d69ea030d35f7888 refs/heads/remote-test - #1 CACHED - { - "group": { - "default": [ - "default" - ] - }, - "target": { - "default": { - "context": "git://github.com/docker/cli#master", - "dockerfile": "Dockerfile", - "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n" - } - } - } - ``` - - ```console - $ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#master" - ... - > [4/4] RUN ls -l && stop: - #8 0.136 drwxrwxrwx 5 root root 4096 Jul 27 18:31 kubernetes - #8 0.136 drwxrwxrwx 3 root root 4096 Jul 27 18:31 man - #8 0.136 drwxrwxrwx 2 root root 4096 Jul 27 18:31 opts - #8 0.136 -rw-rw-rw- 1 root root 1893 Jul 27 18:31 poule.yml - #8 0.136 drwxrwxrwx 7 root root 4096 Jul 27 18:31 scripts - #8 0.136 drwxrwxrwx 3 root root 4096 Jul 27 18:31 service - #8 0.136 drwxrwxrwx 2 root root 4096 Jul 27 18:31 templates - #8 0.136 drwxrwxrwx 10 root root 4096 Jul 27 18:31 vendor - #8 0.136 -rwxrwxrwx 1 root root 9620 Jul 27 18:31 vendor.conf - #8 0.136 /bin/sh: stop: not found - ``` - - ### Do not use cache when building the image (--no-cache) {#no-cache} - - Same as `build --no-cache`. Do not use cache when building the image. - - ### Print the options without building (--print) {#print} - - Prints the resulting options of the targets desired to be built, in a JSON - format, without starting a build. - - ```console - $ docker buildx bake -f docker-bake.hcl --print db - { - "group": { - "default": [ - "db" - ] - }, - "target": { - "db": { - "context": "./", - "dockerfile": "Dockerfile", - "tags": [ - "docker.io/tiborvass/db" - ] - } - } - } - ``` - - ### Set type of progress output (--progress) {#progress} - - Same as [`build --progress`](buildx_build.md#progress). Set type of progress - output (auto, plain, tty). Use plain to show container output (default "auto"). - - > You can also use the `BUILDKIT_PROGRESS` environment variable to set its value. - - The following example uses `plain` output during the build: - - ```console - $ docker buildx bake --progress=plain - - #2 [backend internal] load build definition from Dockerfile.test - #2 sha256:de70cb0bb6ed8044f7b9b1b53b67f624e2ccfb93d96bb48b70c1fba562489618 - #2 ... - - #1 [database internal] load build definition from Dockerfile.test - #1 sha256:453cb50abd941762900a1212657a35fc4aad107f5d180b0ee9d93d6b74481bce - #1 transferring dockerfile: 36B done - #1 DONE 0.1s - ... - ``` - - - ### Always attempt to pull a newer version of the image (--pull) {#pull} - - Same as `build --pull`. - - ### Override target configurations from command line (--set) {#set} - - ``` - --set targetpattern.key[.subkey]=value - ``` - - Override target configurations from command line. The pattern matching syntax - is defined in https://golang.org/pkg/path/#Match. - - - **Examples** - - ```console - $ docker buildx bake --set target.args.mybuildarg=value - $ docker buildx bake --set target.platform=linux/arm64 - $ docker buildx bake --set foo*.args.mybuildarg=value # overrides build arg for all targets starting with 'foo' - $ docker buildx bake --set *.platform=linux/arm64 # overrides platform for all targets - $ docker buildx bake --set foo*.no-cache # bypass caching only for targets starting with 'foo' - ``` - - Complete list of overridable fields: - `args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `labels`, `no-cache`, - `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target` - - ### File definition - - In addition to compose files, bake supports a JSON and an equivalent HCL file - format for defining build groups and targets. - - A target reflects a single docker build invocation with the same options that - you would specify for `docker build`. A group is a grouping of targets. - - Multiple files can include the same target and final build options will be - determined by merging them together. - - In the case of compose files, each service corresponds to a target. - - A group can specify its list of targets with the `targets` option. A target can - inherit build options by setting the `inherits` option to the list of targets or - groups to inherit from. - - Note: Design of bake command is work in progress, the user experience may change - based on feedback. - - - **Example HCL definition** - - ```hcl - group "default" { - targets = ["db", "webapp-dev"] - } - - target "webapp-dev" { - dockerfile = "Dockerfile.webapp" - tags = ["docker.io/username/webapp"] - } - - target "webapp-release" { - inherits = ["webapp-dev"] - platforms = ["linux/amd64", "linux/arm64"] - } - - target "db" { - dockerfile = "Dockerfile.db" - tags = ["docker.io/username/db"] - } - ``` - - Complete list of valid target fields: - - `args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `inherits`, `labels`, - `no-cache`, `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target` - - ### Global scope attributes - - You can define global scope attributes in HCL/JSON and use them for code reuse - and setting values for variables. This means you can do a "data-only" HCL file - with the values you want to set/override and use it in the list of regular - output files. - - ```hcl - # docker-bake.hcl - variable "FOO" { - default = "abc" - } - - target "app" { - args = { - v1 = "pre-${FOO}" - } - } - ``` - - You can use this file directly: - - ```console - $ docker buildx bake --print app - { - "group": { - "default": [ - "app" - ] - }, - "target": { - "app": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "v1": "pre-abc" - } - } - } - } - ``` - - Or create an override configuration file: - - ```hcl - # env.hcl - WHOAMI="myuser" - FOO="def-${WHOAMI}" - ``` - - And invoke bake together with both of the files: - - ```console - $ docker buildx bake -f docker-bake.hcl -f env.hcl --print app - { - "group": { - "default": [ - "app" - ] - }, - "target": { - "app": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "v1": "pre-def-myuser" - } - } - } - } - ``` - - ### HCL variables and functions - - Similar to how Terraform provides a way to [define variables](https://www.terraform.io/docs/configuration/variables.html#declaring-an-input-variable), - the HCL file format also supports variable block definitions. These can be used - to define variables with values provided by the current environment, or a - default value when unset. - - A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hclparser/stdlib.go) - provided by [go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib) - are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc) - are also supported. - - #### Using interpolation to tag an image with the git sha - - Bake supports variable blocks which are assigned to matching environment - variables or default values. - - ```hcl - # docker-bake.hcl - variable "TAG" { - default = "latest" - } - - group "default" { - targets = ["webapp"] - } - - target "webapp" { - tags = ["docker.io/username/webapp:${TAG}"] - } - ``` - - ```console - $ docker buildx bake --print webapp - { - "group": { - "default": [ - "webapp" - ] - }, - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "tags": [ - "docker.io/username/webapp:latest" - ] - } - } - } - ``` - - ```console - $ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp - { - "group": { - "default": [ - "webapp" - ] - }, - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "tags": [ - "docker.io/username/webapp:985e9e9" - ] - } - } - } - ``` - - #### Using the `add` function - - You can use [`go-cty` stdlib functions]([go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib)). - Here we are using the `add` function. - - ```hcl - # docker-bake.hcl - variable "TAG" { - default = "latest" - } - - group "default" { - targets = ["webapp"] - } - - target "webapp" { - args = { - buildno = "${add(123, 1)}" - } - } - ``` - - ```console - $ docker buildx bake --print webapp - { - "group": { - "default": [ - "webapp" - ] - }, - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "buildno": "124" - } - } - } - } - ``` - - #### Defining an `increment` function - - It also supports [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc). - The following example defines a simple an `increment` function. - - ```hcl - # docker-bake.hcl - function "increment" { - params = [number] - result = number + 1 - } - - group "default" { - targets = ["webapp"] - } - - target "webapp" { - args = { - buildno = "${increment(123)}" - } - } - ``` - - ```console - $ docker buildx bake --print webapp - { - "group": { - "default": [ - "webapp" - ] - }, - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "buildno": "124" - } - } - } - } - ``` - - #### Only adding tags if a variable is not empty using an `notequal` - - Here we are using the conditional `notequal` function which is just for - symmetry with the `equal` one. - - ```hcl - # docker-bake.hcl - variable "TAG" {default="" } - - group "default" { - targets = [ - "webapp", - ] - } - - target "webapp" { - context="." - dockerfile="Dockerfile" - tags = [ - "my-image:latest", - notequal("",TAG) ? "my-image:${TAG}": "", - ] - } - ``` - - ```console - $ docker buildx bake --print webapp - { - "group": { - "default": [ - "webapp" - ] - }, - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "tags": [ - "my-image:latest" - ] - } - } - } - ``` - - #### Using variables in functions - - You can refer variables to other variables like the target blocks can. Stdlib - functions can also be called but user functions can't at the moment. - - ```hcl - # docker-bake.hcl - variable "REPO" { - default = "user/repo" - } - - function "tag" { - params = [tag] - result = ["${REPO}:${tag}"] - } - - target "webapp" { - tags = tag("v1") - } - ``` - - ```console - $ docker buildx bake --print webapp - { - "group": { - "default": [ - "webapp" - ] - }, - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "tags": [ - "user/repo:v1" - ] - } - } - } - ``` - - #### Using variables in variables across files - - When multiple files are specified, one file can use variables defined in - another file. - - ```hcl - # docker-bake1.hcl - variable "FOO" { - default = upper("${BASE}def") - } - - variable "BAR" { - default = "-${FOO}-" - } - - target "app" { - args = { - v1 = "pre-${BAR}" - } - } - ``` - - ```hcl - # docker-bake2.hcl - variable "BASE" { - default = "abc" - } - - target "app" { - args = { - v2 = "${FOO}-post" - } - } - ``` - - ```console - $ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app - { - "group": { - "default": [ - "app" - ] - }, - "target": { - "app": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "v1": "pre--ABCDEF-", - "v2": "ABCDEF-post" - } - } - } - } - ``` - - #### Using typed variables - - Non-string variables are also accepted. The value passed with env is parsed - into suitable type first. - - ```hcl - # docker-bake.hcl - variable "FOO" { - default = 3 - } - - variable "IS_FOO" { - default = true - } - - target "app" { - args = { - v1 = FOO > 5 ? "higher" : "lower" - v2 = IS_FOO ? "yes" : "no" - } - } - ``` - - ```console - $ docker buildx bake --print app - { - "group": { - "default": [ - "app" - ] - }, - "target": { - "app": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "v1": "lower", - "v2": "yes" - } - } - } - } - ``` - - ### Extension field with Compose - - [Special extension](https://github.com/compose-spec/compose-spec/blob/master/spec.md#extension) - field `x-bake` can be used in your compose file to evaluate fields that are not - (yet) available in the [build definition](https://github.com/compose-spec/compose-spec/blob/master/build.md#build-definition). - - ```yaml - # docker-compose.yml - services: - addon: - image: ct-addon:bar - build: - context: . - dockerfile: ./Dockerfile - args: - CT_ECR: foo - CT_TAG: bar - x-bake: - tags: - - ct-addon:foo - - ct-addon:alp - platforms: - - linux/amd64 - - linux/arm64 - cache-from: - - user/app:cache - - type=local,src=path/to/cache - cache-to: type=local,dest=path/to/cache - pull: true - - aws: - image: ct-fake-aws:bar - build: - dockerfile: ./aws.Dockerfile - args: - CT_ECR: foo - CT_TAG: bar - x-bake: - secret: - - id=mysecret,src=./secret - - id=mysecret2,src=./secret2 - platforms: linux/arm64 - output: type=docker - no-cache: true - ``` - - ```console - $ docker buildx bake --print - { - "target": { - "addon": { - "context": ".", - "dockerfile": "./Dockerfile", - "args": { - "CT_ECR": "foo", - "CT_TAG": "bar" - }, - "tags": [ - "ct-addon:foo", - "ct-addon:alp" - ], - "cache-from": [ - "user/app:cache", - "type=local,src=path/to/cache" - ], - "cache-to": [ - "type=local,dest=path/to/cache" - ], - "platforms": [ - "linux/amd64", - "linux/arm64" - ], - "pull": true - }, - "aws": { - "context": ".", - "dockerfile": "./aws.Dockerfile", - "args": { - "CT_ECR": "foo", - "CT_TAG": "bar" - }, - "tags": [ - "ct-fake-aws:bar" - ], - "secret": [ - "id=mysecret,src=./secret", - "id=mysecret2,src=./secret2" - ], - "platforms": [ - "linux/arm64" - ], - "output": [ - "type=docker" - ], - "no-cache": true - } - } - } - ``` - - Complete list of valid fields for `x-bake`: - - `tags`, `cache-from`, `cache-to`, `secret`, `ssh`, `platforms`, `output`, - `pull`, `no-cache` - - ### Built-in variables - - * `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command - from a bake file that has been [imported remotely](#file). - * `BAKE_LOCAL_PLATFORM` returns the current platform's default platform - specification (e.g. `linux/amd64`). -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_build.yaml b/docs/reference/docker_buildx_build.yaml deleted file mode 100644 index b31dad5f..00000000 --- a/docs/reference/docker_buildx_build.yaml +++ /dev/null @@ -1,649 +0,0 @@ -command: docker buildx build -aliases: b -short: Start a build -long: |- - The `buildx build` command starts a build using BuildKit. This command is similar - to the UI of `docker build` command and takes the same flags and arguments. - - For documentation on most of these flags, refer to the [`docker build` - documentation](/engine/reference/commandline/build/). In - here we’ll document a subset of the new flags. -usage: docker buildx build [OPTIONS] PATH | URL | - -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: add-host - value_type: stringSlice - default_value: '[]' - description: Add a custom host-to-IP mapping (host:ip) - details_url: /engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: allow - value_type: stringSlice - default_value: '[]' - description: | - Allow extra privileged entitlement, e.g. network.host, security.insecure - details_url: '#allow' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: build-arg - value_type: stringArray - default_value: '[]' - description: Set build-time variables - details_url: /engine/reference/commandline/build/#set-build-time-variables---build-arg - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cache-from - value_type: stringArray - default_value: '[]' - description: | - External cache sources (eg. user/app:cache, type=local,src=path/to/dir) - details_url: '#cache-from' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cache-to - value_type: stringArray - default_value: '[]' - description: | - Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) - details_url: '#cache-to' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cgroup-parent - value_type: string - description: Optional parent cgroup for the container - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: compress - value_type: bool - default_value: "false" - description: Compress the build context using gzip - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-period - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) period - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-quota - value_type: int64 - default_value: "0" - description: Limit the CPU CFS (Completely Fair Scheduler) quota - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpu-shares - shorthand: c - value_type: int64 - default_value: "0" - description: CPU shares (relative weight) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-cpus - value_type: string - description: CPUs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: cpuset-mems - value_type: string - description: MEMs in which to allow execution (0-3, 0,1) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: file - shorthand: f - value_type: string - description: Name of the Dockerfile (Default is 'PATH/Dockerfile') - details_url: /engine/reference/commandline/build/#specify-a-dockerfile--f - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force-rm - value_type: bool - default_value: "false" - description: Always remove intermediate containers - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: iidfile - value_type: string - description: Write the image ID to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: isolation - value_type: string - description: Container isolation technology - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: label - value_type: stringArray - default_value: '[]' - description: Set metadata for an image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: load - value_type: bool - default_value: "false" - description: Shorthand for --output=type=docker - details_url: '#load' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory - shorthand: m - value_type: string - description: Memory limit - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: memory-swap - value_type: string - description: | - Swap limit equal to memory plus swap: '-1' to enable unlimited swap - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: metadata-file - value_type: string - description: Write build result metadata to the file - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: network - value_type: string - default_value: default - description: Set the networking mode for the RUN instructions during build - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: no-cache - value_type: bool - default_value: "false" - description: Do not use cache when building the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: output - shorthand: o - value_type: stringArray - default_value: '[]' - description: 'Output destination (format: type=local,dest=path)' - details_url: '#output' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: stringArray - default_value: '[]' - description: Set target platform for build - details_url: '#platform' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: progress - value_type: string - default_value: auto - description: | - Set type of progress output (auto, plain, tty). Use plain to show container output - details_url: '#progress' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: pull - value_type: bool - default_value: "false" - description: Always attempt to pull a newer version of the image - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: push - value_type: bool - default_value: "false" - description: Shorthand for --output=type=registry - details_url: '#push' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: quiet - shorthand: q - value_type: bool - default_value: "false" - description: Suppress the build output and print image ID on success - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: rm - value_type: bool - default_value: "true" - description: Remove intermediate containers after a successful build - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: secret - value_type: stringArray - default_value: '[]' - description: 'Secret file to expose to the build: id=mysecret,src=/local/secret' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: security-opt - value_type: stringSlice - default_value: '[]' - description: Security options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: shm-size - value_type: string - description: Size of /dev/shm - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: squash - value_type: bool - default_value: "false" - description: Squash newly built layers into a single new layer - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ssh - value_type: stringArray - default_value: '[]' - description: | - SSH agent socket or keys to expose to the build (format: `default|[=|[,]]`) - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tag - shorthand: t - value_type: stringArray - default_value: '[]' - description: Name and optionally a tag in the 'name:tag' format - details_url: /engine/reference/commandline/build/#tag-an-image--t - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: target - value_type: string - description: Set the target build stage to build. - details_url: /engine/reference/commandline/build/#specifying-target-build-stage---target - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: ulimit - value_type: string - description: Ulimit options - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Set the target platforms for the build (--platform) {#platform} - - ``` - --platform=value[,value] - ``` - - Set the target platform for the build. All `FROM` commands inside the Dockerfile - without their own `--platform` flag will pull base images for this platform and - this value will also be the platform of the resulting image. The default value - will be the current platform of the buildkit daemon. - - When using `docker-container` driver with `buildx`, this flag can accept multiple - values as an input separated by a comma. With multiple values the result will be - built for all of the specified platforms and joined together into a single manifest - list. - - If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime - support for the specified platform. In a clean setup, you can only execute `RUN` - commands for your system architecture. - If your kernel supports [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc) - launchers for secondary architectures, buildx will pick them up automatically. - Docker desktop releases come with `binfmt_misc` automatically configured for `arm64` - and `arm` architectures. You can see what runtime platforms your current builder - instance supports by running `docker buildx inspect --bootstrap`. - - Inside a `Dockerfile`, you can access the current platform value through - `TARGETPLATFORM` build argument. Please refer to the [`docker build` - documentation](/engine/reference/builder/#automatic-platform-args-in-the-global-scope) - for the full description of automatic platform argument variants . - - The formatting for the platform specifier is defined in the [containerd source - code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63). - - **Examples** - - ```console - $ docker buildx build --platform=linux/arm64 . - $ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 . - $ docker buildx build --platform=darwin . - ``` - - ### Set type of progress output (--progress) {#progress} - - ``` - --progress=VALUE - ``` - - Set type of progress output (auto, plain, tty). Use plain to show container - output (default "auto"). - - > You can also use the `BUILDKIT_PROGRESS` environment variable to set - > its value. - - The following example uses `plain` output during the build: - - ```console - $ docker buildx build --load --progress=plain . - - #1 [internal] load build definition from Dockerfile - #1 transferring dockerfile: 227B 0.0s done - #1 DONE 0.1s - - #2 [internal] load .dockerignore - #2 transferring context: 129B 0.0s done - #2 DONE 0.0s - ... - ``` - - ### Set the export action for the build result (-o, --output) {#output} - - ``` - -o, --output=[PATH,-,type=TYPE[,KEY=VALUE] - ``` - - Sets the export action for the build result. In `docker build` all builds finish - by creating a container image and exporting it to `docker images`. `buildx` makes - this step configurable allowing results to be exported directly to the client, - oci image tarballs, registry etc. - - Buildx with `docker` driver currently only supports local, tarball exporter and - image exporter. `docker-container` driver supports all the exporters. - - If just the path is specified as a value, `buildx` will use the local exporter - with this path as the destination. If the value is "-", `buildx` will use `tar` - exporter and write to `stdout`. - - **Examples** - - ```console - $ docker buildx build -o . . - $ docker buildx build -o outdir . - $ docker buildx build -o - - > out.tar - $ docker buildx build -o type=docker . - $ docker buildx build -o type=docker,dest=- . > myimage.tar - $ docker buildx build -t tonistiigi/foo -o type=registry - ``` - - Supported exported types are: - - #### `local` - - The `local` export type writes all result files to a directory on the client. The - new files will be owned by the current user. On multi-platform builds, all results - will be put in subdirectories by their platform. - - Attribute key: - - - `dest` - destination directory where files will be written - - #### `tar` - - The `tar` export type writes all result files as a single tarball on the client. - On multi-platform builds all results will be put in subdirectories by their platform. - - Attribute key: - - - `dest` - destination path where tarball will be written. “-” writes to stdout. - - #### `oci` - - The `oci` export type writes the result image or manifest list as an [OCI image - layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md) - tarball on the client. - - Attribute key: - - - `dest` - destination path where tarball will be written. “-” writes to stdout. - - #### `docker` - - The `docker` export type writes the single-platform result image as a [Docker image - specification](https://github.com/docker/docker/blob/v20.10.2/image/spec/v1.2.md) - tarball on the client. Tarballs created by this exporter are also OCI compatible. - - Currently, multi-platform images cannot be exported with the `docker` export type. - The most common usecase for multi-platform images is to directly push to a registry - (see [`registry`](#registry)). - - Attribute keys: - - - `dest` - destination path where tarball will be written. If not specified the - tar will be loaded automatically to the current docker instance. - - `context` - name for the docker context where to import the result - - #### `image` - - The `image` exporter writes the build result as an image or a manifest list. When - using `docker` driver the image will appear in `docker images`. Optionally, image - can be automatically pushed to a registry by specifying attributes. - - Attribute keys: - - - `name` - name (references) for the new image. - - `push` - boolean to automatically push the image. - - #### `registry` - - The `registry` exporter is a shortcut for `type=image,push=true`. - - - ### Push the build result to a registry (--push) {#push} - - Shorthand for [`--output=type=registry`](#registry). Will automatically push the - build result to registry. - - ### Load the single-platform build result to `docker images` (--load) {#load} - - Shorthand for [`--output=type=docker`](#docker). Will automatically load the - single-platform build result to `docker images`. - - ### Use an external cache source for a build (--cache-from) {#cache-from} - - ``` - --cache-from=[NAME|type=TYPE[,KEY=VALUE]] - ``` - - Use an external cache source for a build. Supported types are `registry`, - `local` and `gha`. - - - [`registry` source](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) - can import cache from a cache manifest or (special) image configuration on the - registry. - - [`local` source](https://github.com/moby/buildkit#local-directory-1) can - import cache from local files previously exported with `--cache-to`. - - [`gha` source](https://github.com/moby/buildkit#github-actions-cache-experimental) - can import cache from a previously exported cache with `--cache-to` in your - GitHub repository - - If no type is specified, `registry` exporter is used with a specified reference. - - `docker` driver currently only supports importing build cache from the registry. - - **Examples** - - ```console - $ docker buildx build --cache-from=user/app:cache . - $ docker buildx build --cache-from=user/app . - $ docker buildx build --cache-from=type=registry,ref=user/app . - $ docker buildx build --cache-from=type=local,src=path/to/cache . - $ docker buildx build --cache-from=type=gha . - ``` - - More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache - - ### Export build cache to an external cache destination (--cache-to) {#cache-to} - - ``` - --cache-to=[NAME|type=TYPE[,KEY=VALUE]] - ``` - - Export build cache to an external cache destination. Supported types are - `registry`, `local`, `inline` and `gha`. - - - [`registry` type](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) exports build cache to a cache manifest in the registry. - - [`local` type](https://github.com/moby/buildkit#local-directory-1) type - exports cache to a local directory on the client. - - [`inline` type](https://github.com/moby/buildkit#inline-push-image-and-cache-together) - type writes the cache metadata into the image configuration. - - [`gha` type](https://github.com/moby/buildkit#github-actions-cache-experimental) - type exports cache through the [Github Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication). - - `docker` driver currently only supports exporting inline cache metadata to image - configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used - to trigger inline cache exporter. - - Attribute key: - - - `mode` - Specifies how many layers are exported with the cache. `min` on only - exports layers already in the final build stage, `max` exports layers for - all stages. Metadata is always exported for the whole build. - - **Examples** - - ```console - $ docker buildx build --cache-to=user/app:cache . - $ docker buildx build --cache-to=type=inline . - $ docker buildx build --cache-to=type=registry,ref=user/app . - $ docker buildx build --cache-to=type=local,dest=path/to/cache . - $ docker buildx build --cache-to=type=gha . - ``` - - More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache - - ### Allow extra privileged entitlement (--allow) {#allow} - - ``` - --allow=ENTITLEMENT - ``` - - Allow extra privileged entitlement. List of entitlements: - - - `network.host` - Allows executions with host networking. - - `security.insecure` - Allows executions without sandbox. See - [related Dockerfile extensions](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox). - - For entitlements to be enabled, the `buildkitd` daemon also needs to allow them - with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](buildx_create.md#--buildkitd-flags-flags)) - - **Examples** - - ```console - $ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure' - $ docker buildx build --allow security.insecure . - ``` -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_create.yaml b/docs/reference/docker_buildx_create.yaml deleted file mode 100644 index f0f4fea3..00000000 --- a/docs/reference/docker_buildx_create.yaml +++ /dev/null @@ -1,297 +0,0 @@ -command: docker buildx create -short: Create a new builder instance -long: |- - Create makes a new builder instance pointing to a docker context or endpoint, - where context is the name of a context from `docker context ls` and endpoint is - the address for docker socket (eg. `DOCKER_HOST` value). - - By default, the current Docker configuration is used for determining the - context/endpoint value. - - Builder instances are isolated environments where builds can be invoked. All - Docker contexts also get the default builder instance. -usage: docker buildx create [OPTIONS] [CONTEXT|ENDPOINT] -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: append - value_type: bool - default_value: "false" - description: Append a node to builder instead of changing it - details_url: '#append' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: bootstrap - value_type: bool - default_value: "false" - description: Boot builder after creation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: buildkitd-flags - value_type: string - description: Flags for buildkitd daemon - details_url: '#buildkitd-flags' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: config - value_type: string - description: BuildKit config file - details_url: '#config' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: driver - value_type: string - description: 'Driver to use (available: [])' - details_url: '#driver' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: driver-opt - value_type: stringArray - default_value: '[]' - description: Options for the driver - details_url: '#driver-opt' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: leave - value_type: bool - default_value: "false" - description: Remove a node from builder instead of changing it - details_url: '#leave' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: name - value_type: string - description: Builder instance name - details_url: '#name' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: node - value_type: string - description: Create/modify node with given name - details_url: '#node' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: platform - value_type: stringArray - default_value: '[]' - description: Fixed platforms for current node - details_url: '#platform' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: use - value_type: bool - default_value: "false" - description: Set the current builder instance - details_url: '#use' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Append a new node to an existing builder (--append) {#append} - - The `--append` flag changes the action of the command to append a new node to an - existing builder specified by `--name`. Buildx will choose an appropriate node - for a build based on the platforms it supports. - - **Examples** - - ```console - $ docker buildx create mycontext1 - eager_beaver - - $ docker buildx create --name eager_beaver --append mycontext2 - eager_beaver - ``` - - ### Specify options for the buildkitd daemon (--buildkitd-flags) {#buildkitd-flags} - - ``` - --buildkitd-flags FLAGS - ``` - - Adds flags when starting the buildkitd daemon. They take precedence over the - configuration file specified by [`--config`](#--config-file). See `buildkitd --help` - for the available flags. - - **Example** - - ``` - --buildkitd-flags '--debug --debugaddr 0.0.0.0:6666' - ``` - - ### Specify a configuration file for the buildkitd daemon (--config) {#config} - - ``` - --config FILE - ``` - - Specifies the configuration file for the buildkitd daemon to use. The configuration - can be overridden by [`--buildkitd-flags`](#--buildkitd-flags-flags). - See an [example buildkitd configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md). - - ### Set the builder driver to use (--driver) {#driver} - - ``` - --driver DRIVER - ``` - - Sets the builder driver to be used. There are two available drivers, each have - their own specificities. - - #### `docker` driver - - Uses the builder that is built into the docker daemon. With this driver, - the [`--load`](buildx_build.md#--load) flag is implied by default on - `buildx build`. However, building multi-platform images or exporting cache is - not currently supported. - - #### `docker-container` driver - - Uses a BuildKit container that will be spawned via docker. With this driver, - both building multi-platform images and exporting cache are supported. - - Unlike `docker` driver, built images will not automatically appear in - `docker images` and [`build --load`](buildx_build.md#--load) needs to be used - to achieve that. - - #### `kubernetes` driver - - Uses a kubernetes pods. With this driver, you can spin up pods with defined - BuildKit container image to build your images. - - Unlike `docker` driver, built images will not automatically appear in - `docker images` and [`build --load`](buildx_build.md#--load) needs to be used - to achieve that. - - ### Set additional driver-specific options (--driver-opt) {#driver-opt} - - ``` - --driver-opt OPTIONS - ``` - - Passes additional driver-specific options. Details for each driver: - - - `docker` - No driver options - - `docker-container` - - `image=IMAGE` - Sets the container image to be used for running buildkit. - - `network=NETMODE` - Sets the network mode for running the buildkit container. - - Example: - - ```console - --driver docker-container --driver-opt image=moby/buildkit:master,network=host - ``` - - `kubernetes` - - `image=IMAGE` - Sets the container image to be used for running buildkit. - - `namespace=NS` - Sets the Kubernetes namespace. Defaults to the current namespace. - - `replicas=N` - Sets the number of `Pod` replicas. Defaults to 1. - - `requests.cpu` - Sets the request CPU value specified in units of Kubernetes CPU. Example `requests.cpu=100m`, `requests.cpu=2` - - `requests.memory` - Sets the request memory value specified in bytes or with a valid suffix. Example `requests.memory=500Mi`, `requests.memory=4G` - - `limits.cpu` - Sets the limit CPU value specified in units of Kubernetes CPU. Example `limits.cpu=100m`, `limits.cpu=2` - - `limits.memory` - Sets the limit memory value specified in bytes or with a valid suffix. Example `limits.memory=500Mi`, `limits.memory=4G` - - `nodeselector="label1=value1,label2=value2"` - Sets the kv of `Pod` nodeSelector. No Defaults. Example `nodeselector=kubernetes.io/arch=arm64` - - `rootless=(true|false)` - Run the container as a non-root user without `securityContext.privileged`. [Using Ubuntu host kernel is recommended](https://github.com/moby/buildkit/blob/master/docs/rootless.md). Defaults to false. - - `loadbalance=(sticky|random)` - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky" - - `qemu.install=(true|false)` - Install QEMU emulation for multi platforms support. - - `qemu.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest` - - ### Remove a node from a builder (--leave) {#leave} - - The `--leave` flag changes the action of the command to remove a node from a - builder. The builder needs to be specified with `--name` and node that is removed - is set with `--node`. - - **Examples** - - ```console - $ docker buildx create --name mybuilder --node mybuilder0 --leave - ``` - - ### Specify the name of the builder (--name) {#name} - - ``` - --name NAME - ``` - - The `--name` flag specifies the name of the builder to be created or modified. - If none is specified, one will be automatically generated. - - ### Specify the name of the node (--node) {#node} - - ``` - --node NODE - ``` - - The `--node` flag specifies the name of the node to be created or modified. If - none is specified, it is the name of the builder it belongs to, with an index - number suffix. - - ### Set the platforms supported by the node {#platform} - - ``` - --platform PLATFORMS - ``` - - The `--platform` flag sets the platforms supported by the node. It expects a - comma-separated list of platforms of the form OS/architecture/variant. The node - will also automatically detect the platforms it supports, but manual values take - priority over the detected ones and can be used when multiple nodes support - building for the same platform. - - **Examples** - - ```console - $ docker buildx create --platform linux/amd64 - $ docker buildx create --platform linux/arm64,linux/arm/v8 - ``` - - ### Automatically switch to the newly created builder {#use} - - The `--use` flag automatically switches the current builder to the newly created - one. Equivalent to running `docker buildx use $(docker buildx create ...)`. -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_du.yaml b/docs/reference/docker_buildx_du.yaml deleted file mode 100644 index 063f0adb..00000000 --- a/docs/reference/docker_buildx_du.yaml +++ /dev/null @@ -1,39 +0,0 @@ -command: docker buildx du -short: Disk usage -long: Disk usage -usage: docker buildx du -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: filter - value_type: filter - description: Provide filter values - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: verbose - value_type: bool - default_value: "false" - description: Provide a more verbose output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_imagetools.yaml b/docs/reference/docker_buildx_imagetools.yaml deleted file mode 100644 index 65bffa42..00000000 --- a/docs/reference/docker_buildx_imagetools.yaml +++ /dev/null @@ -1,28 +0,0 @@ -command: docker buildx imagetools -short: Commands to work on images in registry -long: |- - Imagetools contains commands for working with manifest lists in the registry. - These commands are useful for inspecting multi-platform build results. -pname: docker buildx -plink: docker_buildx.yaml -cname: -- docker buildx imagetools create -- docker buildx imagetools inspect -clink: -- docker_buildx_imagetools_create.yaml -- docker_buildx_imagetools_inspect.yaml -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_imagetools_create.yaml b/docs/reference/docker_buildx_imagetools_create.yaml deleted file mode 100644 index 8903cb83..00000000 --- a/docs/reference/docker_buildx_imagetools_create.yaml +++ /dev/null @@ -1,118 +0,0 @@ -command: docker buildx imagetools create -short: Create a new image based on source images -long: |- - Imagetools contains commands for working with manifest lists in the registry. - These commands are useful for inspecting multi-platform build results. - - Create a new manifest list based on source manifests. The source manifests can - be manifest lists or single platform distribution manifests and must already - exist in the registry where the new manifest is created. If only one source is - specified, create performs a carbon copy. -usage: docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...] -pname: docker buildx imagetools -plink: docker_buildx_imagetools.yaml -options: -- option: append - value_type: bool - default_value: "false" - description: Append to existing manifest - details_url: '#append' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: dry-run - value_type: bool - default_value: "false" - description: Show final image instead of pushing - details_url: '#dry-run' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: file - shorthand: f - value_type: stringArray - default_value: '[]' - description: Read source descriptor from file - details_url: '#file' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: tag - shorthand: t - value_type: stringArray - default_value: '[]' - description: Set reference for new image - details_url: '#tag' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Append new sources to an existing manifest list (--append) {#append} - - Use the `--append` flag to append the new sources to an existing manifest list - in the destination. - - ### Show final image instead of pushing (--dry-run) {#dry-run} - - Use the `--dry-run` flag to not push the image, just show it. - - ### Read source descriptor from a file (-f, --file) {#file} - - ``` - -f FILE or --file FILE - ``` - - Reads source from files. A source can be a manifest digest, manifest reference, - or a JSON of OCI descriptor object. - - In order to define annotations or additional platform properties like `os.version` and - `os.features` you need to add them in the OCI descriptor object encoded in JSON. - - ``` - docker buildx imagetools inspect --raw alpine | jq '.manifests[0] | .platform."os.version"="10.1"' > descr.json - docker buildx imagetools create -f descr.json myuser/image - ``` - - The descriptor in the file is merged with existing descriptor in the registry if it exists. - - The supported fields for the descriptor are defined in [OCI spec](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties) . - - - ### Set reference for new image (-t, --tag) {#tag} - - ``` - -t IMAGE or --tag IMAGE - ``` - - Use the `-t` or `--tag` flag to set the name of the image to be created. - - **Examples** - - ```console - $ docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204 - - $ docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2 - ``` -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_imagetools_inspect.yaml b/docs/reference/docker_buildx_imagetools_inspect.yaml deleted file mode 100644 index 1c0a8f63..00000000 --- a/docs/reference/docker_buildx_imagetools_inspect.yaml +++ /dev/null @@ -1,58 +0,0 @@ -command: docker buildx imagetools inspect -short: Show details of image in the registry -long: |- - Show details of image in the registry. - - Example: - - ```console - $ docker buildx imagetools inspect alpine - - Name: docker.io/library/alpine:latest - MediaType: application/vnd.docker.distribution.manifest.list.v2+json - Digest: sha256:28ef97b8686a0b5399129e9b763d5b7e5ff03576aa5580d6f4182a49c5fe1913 - - Manifests: - Name: docker.io/library/alpine:latest@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/amd64 - - Name: docker.io/library/alpine:latest@sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204 - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/arm/v6 - ... - ``` - - ### Show original, unformatted JSON manifest (--raw) {#raw} - - Use the `--raw` option to print the original JSON bytes instead of the formatted - output. -usage: docker buildx imagetools inspect [OPTIONS] NAME -pname: docker buildx imagetools -plink: docker_buildx_imagetools.yaml -options: -- option: raw - value_type: bool - default_value: "false" - description: Show original JSON manifest - details_url: '#raw' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_inspect.yaml b/docs/reference/docker_buildx_inspect.yaml deleted file mode 100644 index ee70293b..00000000 --- a/docs/reference/docker_buildx_inspect.yaml +++ /dev/null @@ -1,66 +0,0 @@ -command: docker buildx inspect -short: Inspect current builder instance -long: Shows information about the current or specified builder. -usage: docker buildx inspect [NAME] -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: bootstrap - value_type: bool - default_value: "false" - description: Ensure builder has booted before inspecting - details_url: '#bootstrap' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Get information about a builder instance - - By default, `inspect` shows information about the current builder. Specify the - name of the builder to inspect to get information about that builder. - The following example shows information about a builder instance named - `elated_tesla`: - - ```console - $ docker buildx inspect elated_tesla - - Name: elated_tesla - Driver: docker-container - - Nodes: - Name: elated_tesla0 - Endpoint: unix:///var/run/docker.sock - Status: running - Platforms: linux/amd64 - - Name: elated_tesla1 - Endpoint: ssh://ubuntu@1.2.3.4 - Status: running - Platforms: linux/arm64, linux/arm/v7, linux/arm/v6 - ``` - - ### Ensure that the builder is running before inspecting (--bootstrap) {#bootstrap} - - Use the `--bootstrap` option to ensure that the builder is running before - inspecting it. If the driver is `docker-container`, then `--bootstrap` starts - the buildkit container and waits until it is operational. Bootstrapping is - automatically done during build, and therefore not necessary. The same BuildKit - container is used during the lifetime of the associated builder node (as - displayed in `buildx ls`). -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_install.yaml b/docs/reference/docker_buildx_install.yaml deleted file mode 100644 index 0f771a6c..00000000 --- a/docs/reference/docker_buildx_install.yaml +++ /dev/null @@ -1,21 +0,0 @@ -command: docker buildx install -short: Install buildx as a 'docker builder' alias -long: Install buildx as a 'docker builder' alias -usage: docker buildx install -pname: docker buildx -plink: docker_buildx.yaml -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_ls.yaml b/docs/reference/docker_buildx_ls.yaml deleted file mode 100644 index b248c2b7..00000000 --- a/docs/reference/docker_buildx_ls.yaml +++ /dev/null @@ -1,38 +0,0 @@ -command: docker buildx ls -short: List builder instances -long: |- - Lists all builder instances and the nodes for each instance - - **Example** - - ```console - $ docker buildx ls - - NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS - elated_tesla * docker-container - elated_tesla0 unix:///var/run/docker.sock running linux/amd64 - elated_tesla1 ssh://ubuntu@1.2.3.4 running linux/arm64, linux/arm/v7, linux/arm/v6 - default docker - default default running linux/amd64 - ``` - - Each builder has one or more nodes associated with it. The current builder's - name is marked with a `*`. -usage: docker buildx ls -pname: docker buildx -plink: docker_buildx.yaml -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_prune.yaml b/docs/reference/docker_buildx_prune.yaml deleted file mode 100644 index 237c9c8d..00000000 --- a/docs/reference/docker_buildx_prune.yaml +++ /dev/null @@ -1,68 +0,0 @@ -command: docker buildx prune -short: Remove build cache -long: Remove build cache -usage: docker buildx prune -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: all - shorthand: a - value_type: bool - default_value: "false" - description: Remove all unused images, not just dangling ones - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: filter - value_type: filter - description: Provide filter values (e.g. 'until=24h') - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: force - shorthand: f - value_type: bool - default_value: "false" - description: Do not prompt for confirmation - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: keep-storage - value_type: bytes - default_value: "0" - description: Amount of disk space to keep for cache - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: verbose - value_type: bool - default_value: "false" - description: Provide a more verbose output - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_rm.yaml b/docs/reference/docker_buildx_rm.yaml deleted file mode 100644 index ab643731..00000000 --- a/docs/reference/docker_buildx_rm.yaml +++ /dev/null @@ -1,39 +0,0 @@ -command: docker buildx rm -short: Remove a builder instance -long: |- - Removes the specified or current builder. It is a no-op attempting to remove the - default builder. -usage: docker buildx rm [NAME] -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: keep-state - value_type: bool - default_value: "false" - description: Keep BuildKit state - details_url: '#keep-state' - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### Keep BuildKit state (--keep-state) {#keep-state} - - Keep BuildKit state, so it can be reused by a new builder with the same name. - Currently, only supported by the [`docker-container` driver](buildx_create.md#driver). -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_stop.yaml b/docs/reference/docker_buildx_stop.yaml deleted file mode 100644 index d9473763..00000000 --- a/docs/reference/docker_buildx_stop.yaml +++ /dev/null @@ -1,23 +0,0 @@ -command: docker buildx stop -short: Stop builder instance -long: |- - Stops the specified or current builder. This will not prevent buildx build to - restart the builder. The implementation of stop depends on the driver. -usage: docker buildx stop [NAME] -pname: docker buildx -plink: docker_buildx.yaml -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_uninstall.yaml b/docs/reference/docker_buildx_uninstall.yaml deleted file mode 100644 index 802544c4..00000000 --- a/docs/reference/docker_buildx_uninstall.yaml +++ /dev/null @@ -1,21 +0,0 @@ -command: docker buildx uninstall -short: Uninstall the 'docker builder' alias -long: Uninstall the 'docker builder' alias -usage: docker buildx uninstall -pname: docker buildx -plink: docker_buildx.yaml -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_use.yaml b/docs/reference/docker_buildx_use.yaml deleted file mode 100644 index ba4d66fa..00000000 --- a/docs/reference/docker_buildx_use.yaml +++ /dev/null @@ -1,43 +0,0 @@ -command: docker buildx use -short: Set the current builder instance -long: |- - Switches the current builder instance. Build commands invoked after this command - will run on a specified builder. Alternatively, a context name can be used to - switch to the default builder of that context. -usage: docker buildx use [OPTIONS] NAME -pname: docker buildx -plink: docker_buildx.yaml -options: -- option: default - value_type: bool - default_value: "false" - description: Set builder as default for current context - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -- option: global - value_type: bool - default_value: "false" - description: Builder persists context changes - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/docs/reference/docker_buildx_version.yaml b/docs/reference/docker_buildx_version.yaml deleted file mode 100644 index b3eff7cb..00000000 --- a/docs/reference/docker_buildx_version.yaml +++ /dev/null @@ -1,29 +0,0 @@ -command: docker buildx version -short: Show buildx version information -long: Show buildx version information -usage: docker buildx version -pname: docker buildx -plink: docker_buildx.yaml -inherited_options: -- option: builder - value_type: string - description: Override the configured builder instance - deprecated: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false -examples: |- - ### View version information - - - ```console - $ docker buildx version - github.com/docker/buildx v0.5.1-docker 11057da37336192bfc57d81e02359ba7ba848e4a - ``` -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/hack/dockerfiles/docs.Dockerfile b/hack/dockerfiles/docs.Dockerfile index 47a06e6f..9014802d 100644 --- a/hack/dockerfiles/docs.Dockerfile +++ b/hack/dockerfiles/docs.Dockerfile @@ -1,6 +1,7 @@ # syntax=docker/dockerfile:1.3-labs ARG GO_VERSION=1.17.0 +ARG FORMATS=md,yaml FROM golang:${GO_VERSION}-alpine AS docsgen WORKDIR /src @@ -12,11 +13,12 @@ FROM alpine AS gen RUN apk add --no-cache rsync git WORKDIR /src COPY --from=docsgen /out/docsgen /usr/bin +ARG FORMATS RUN --mount=target=/context \ --mount=target=.,type=tmpfs <