apple / apple/container

[Request]: Support Docker/BuildKit named build contexts in container build

Open
#1,930 0 comments 6 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
49.9k
Forks
1.8k
Avg merge
1d 20h
Merged PRs (30d)
22

Description

### Feature or enhancement request details

`container build` should support Docker/BuildKit named build contexts, equivalent to Docker/Buildx and Podman `--build-context name=value`.

This is a Dockerfile/BuildKit feature used by higher-level build tooling to pass additional local directories, Git contexts, URLs, OCI layouts, or image references into a build without copying them under the primary build context. Typical Dockerfile usage is:

```Dockerfile
FROM alpine
COPY --from=deps /some/file /some/file
```

with a CLI invocation like:

```sh
container build \
--build-context deps=/path/to/deps \
-t example:latest \
.
```

Today `container build --help` does not expose `--build-context`, and the public build RPC/config path appears to carry only one primary context directory. That means tools that rely on named contexts cannot transparently use Apple `container` as a Docker-compatible builder even though the underlying builder is BuildKit-based.

### Why this matters

Named contexts are not only a convenience feature. They are used by libraries and build systems that need to:

- avoid copying large generated/source trees into the main context;
- keep Dockerfile context boundaries explicit;
- consume additional local source roots in monorepos;
- pin or lock base images via `docker-image://...` contexts;
- match Docker/Buildx and Podman behavior for existing consumers.

For example, AWS CDK-style container asset builders can receive a user-supplied map of build contexts. Without this flag, such libraries must either reject Apple `container` for those builds or switch to a separate BuildKit path and only load the final OCI image into `container` afterward.

### Existing ecosystem support

Docker/Buildx supports named build contexts:

```sh
docker buildx build --build-context deps=/path/to/deps .
docker buildx build --build-context base=docker-image://alpine:latest .
```

Podman supports the same concept:

```sh
podman build --build-context deps=/path/to/deps .
podman build --build-context base=docker-image://alpine:latest .
```

Direct BuildKit supports the underlying mechanism through Dockerfile frontend options. For local named contexts this is roughly:

```sh
buildctl build \
--frontend=dockerfile.v0 \
--local context=. \
--local dockerfile=. \
--local deps=/path/to/deps \
--opt context:deps=local:deps
```

For image/OCI contexts BuildKit frontend attrs use forms such as:

```sh
--opt context:base=docker-image://alpine:latest
--opt context:base=oci-layout:/path/to/oci-layout@sha256:...
```

So the underlying BuildKit machinery already supports this. The missing piece seems to be Apple `container` CLI/API/shim plumbing for multiple named contexts and the corresponding context transfer/serving logic.

### Suggested behavior

Add support for one or more `--build-context name=value` flags to `container build`, matching Docker/Podman syntax where practical.

At minimum, support these common values:

- `name=/absolute/or/relative/local/path`
- `name=docker-image://registry/name:tag`
- `name=docker-image://registry/name@sha256:...`
- `name=oci-layout:/path/to/layout@sha256:...`
- URL/Git contexts if they are already supported by the selected Dockerfile frontend

The local path case likely needs the build request/shim protocol to carry more than the current primary context and expose each named local context to BuildKit as a separate local source.

### Current workaround

The practical workaround is to bypass `container build`, run BuildKit directly with named context frontend options, export an OCI archive, and then load the result into Apple `container`:

```sh
buildctl build ... --output type=oci,dest=image.tar
container image load -i image.tar
container image tag example:latest
```

That works, but it loses the simplicity of `container build` and requires users/tools to manage a separate BuildKit daemon, auth, cache, and networking behavior.

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Contributor guide

Open the contributing guide

Research direction

Start by tracing the `container build` CLI, the public build RPC/config path, and the shim or context-serving logic described in the issue. Compare how the existing primary context reaches BuildKit, then verify that repeated `--build-context name=value` entries support local contexts and the requested Dockerfile `COPY --from` behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, swift
Domain
backend-api-design, build-system, cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.