Skip to content

build(bake): update remote bake definitions page #20889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dvdksn merged 1 commit into from
Sep 20, 2024
Merged

build(bake): update remote bake definitions page #20889

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 70 additions & 66 deletions content/manuals/build/bake/remote-definition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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": {
Expand All @@ -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 = <<EOT
FROM alpine
WORKDIR /src
Expand All @@ -62,25 +63,9 @@ EOT
}
```

```console
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" --print
```

```json
{
"target": {
"default": {
"context": ".",
"dockerfile": "Dockerfile",
"dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
}
}
}
```

```console
$ touch foo bar
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test"
$ docker buildx bake "https://github.com/dvdksn/buildx.git#bake-remote-example"
```

```text
Expand All @@ -92,48 +77,37 @@ $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test"
#8 0.102 /bin/sh: stop: not found
```

```console
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11" --print
#1 [internal] load git source https://github.com/tonistiigi/buildx.git#remote-test
#1 0.429 577303add004dd7efeb13434d69ea030d35f7888 refs/heads/remote-test
#1 CACHED
```
You can append a path to the `cwd://` prefix if you want to use a specific
local directory as a context. Note that if you do specify a path, it must be
within the working directory where the command gets executed. If you use an
absolute path, or a relative path leading outside of the working directory,
Bake will throw an error.

```json
{
"target": {
"default": {
"context": "https://github.com/docker/cli.git#v20.10.11",
"dockerfile": "Dockerfile",
"dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
}
### Local named contexts

You can also use the `cwd://` prefix to define local directories in the Bake
execution context as named contexts.

The following example defines the `docs` context as `./src/docs/content`,
relative to the current working directory where Bake is run as a named context.

```hcl
target "default" {
contexts = {
docs = "cwd://src/docs/content"
}
dockerfile = "Dockerfile"
}
```

```console
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11"
```

```text
...
> [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"
Expand All @@ -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
Expand All @@ -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.
Comment thread
dvdksn marked this conversation as resolved.

```console
docker buildx bake -f bake.hcl -f cwd://local.hcl "https://github.com/crazy-max/buildx.git#remote-with-local" --print
```
Expand All @@ -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 }}"
Copy link
Copy Markdown
Member

@crazy-max crazy-max Sep 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

marking this one for docker/bake-action#193 to remember we need to remove that as follow-up

Copy link
Copy Markdown
Member

@crazy-max crazy-max Sep 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fyi, source: "{{defaultContext}}" also works: https://github.com/docker/bake-action/blob/cdf7e1c5cbb6b6a740f80bfe3ed7939f5c30424f/.github/workflows/ci.yml#L419

https://github.com/docker/bake-action/blob/cdf7e1c5cbb6b6a740f80bfe3ed7939f5c30424f/src/context.ts#L136-L138

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,
Expand Down