diff --git a/content/manuals/build/bake/remote-definition.md b/content/manuals/build/bake/remote-definition.md index 2ab78efa57eb..b3caab8f57f8 100644 --- a/content/manuals/build/bake/remote-definition.md +++ b/content/manuals/build/bake/remote-definition.md @@ -4,7 +4,7 @@ description: Build with Bake using a remote file definition using Git or HTTP keywords: build, buildx, bake, file, remote, git, http --- -You can also build Bake files directly from a remote Git repository or HTTPS URL: +You can build Bake files directly from a remote Git repository or HTTPS URL: ```console $ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print @@ -15,6 +15,12 @@ $ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print #1 DONE 2.9s ``` +This fetches the Bake definition from the specified remote location and +executes the groups or targets defined in that file. If the remote Bake +definition doesn't specify a build context, the context is automatically set to +the Git remote. For example, [this case](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26) +uses `https://github.com/docker/cli.git`: + ```json { "group": { @@ -39,20 +45,15 @@ $ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print } ``` -As you can see the context is fixed to `https://github.com/docker/cli.git` 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` built-in var](reference.md#built-in-variables). +## Use the local context with a remote definition -```console -$ curl -s https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl -``` +When building with a remote Bake definition, you may want to consume local +files relative to the directory where the Bake command is executed. You can +define contexts as relative to the command context using a `cwd://` prefix. -```hcl +```hcl {title="https://github.com/dvdksn/buildx/blob/bake-remote-example/docker-bake.hcl"} target "default" { - context = BAKE_CMD_CONTEXT + context = "cwd://" dockerfile-inline = < [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 -``` +By contrast, if you omit the `cwd://` prefix, the path would be resolved +relative to the build context. -## Remote definition with the --file flag +## Specify the Bake definition to use -You can also specify the Bake definition to load from the remote repository, -using the `--file` or `-f` flag: +When loading a Bake file from a remote Git repository, if the repository +contains more than one Bake file, you can specify which Bake definition to use +with the `--file` or `-f` flag: ```console docker buildx bake -f bake.hcl "https://github.com/crazy-max/buildx.git#remote-with-local" @@ -146,8 +120,12 @@ docker buildx bake -f bake.hcl "https://github.com/crazy-max/buildx.git#remote-w #4 DONE 0.3s ``` -If you want to use a combination of local and remote definitions, you can -specify a local definition using the `cwd://` prefix with `-f`: +## Combine local and remote Bake definitions + +You can also combine remote definitions with local ones using the `cwd://` +prefix with `-f`. + +Given the following local Bake definition in the current working directory: ```hcl # local.hcl @@ -158,6 +136,12 @@ target "default" { } ``` +The following example uses `-f` to specify two Bake definitions: + +- `-f bake.hcl`: this definition is loaded relative to the Git URL. +- `-f cwd://local.hcl`: this definition is loaded relative to the current + working directory where the Bake command is executed. + ```console docker buildx bake -f bake.hcl -f cwd://local.hcl "https://github.com/crazy-max/buildx.git#remote-with-local" --print ``` @@ -180,6 +164,26 @@ docker buildx bake -f bake.hcl -f cwd://local.hcl "https://github.com/crazy-max/ } ``` +One case where combining local and remote Bake definitions becomes necessary is +when you're building with a remote Bake definition in GitHub Actions and want +to use the [metadata-action](https://github.com/docker/metadata-action) to +generate tags, annotations, or labels. The metadata action generates a Bake +file available in the runner's local Bake execution context. To use both the +remote definition and the local "metadata-only" Bake file, specify both files +and use the `cwd://` prefix for the metadata Bake file: + +```yml + - + name: Build + uses: docker/bake-action@v4 + with: + source: "${{ github.server_url }}/${{ github.repository }}.git#${{ github.ref }}" + files: | + ./docker-bake.hcl + cwd://${{ steps.meta.outputs.bake-file }} + targets: build +``` + ## Remote definition in a private repository If you want to use a remote definition that lives in a private repository,