docker / buildx

Build Secrets and Entitlements - docker/buildx

In the context of the github.com/docker/buildx project, managing secrets and entitlements during the build process is an essential aspect of ensuring secure and efficient builds. This document will cover the possible options and provide examples for managing secrets and entitlements during the build process using the buildx tool.

Environment Variables for Docker Build

buildx supports various environment variables that can be used to configure the behavior of building features. Here are some relevant environment variables for managing secrets and entitlements:

  • BUILDKIT_HOST: Specify the host to use for remote builders.
  • BUILDKIT_PROGRESS: Configure the type of progress output.
  • BUILDX_BUILDER: Specify the builder instance to use.
  • BUILDX_CONFIG: Specify the location for configuration, state, and logs.
  • BUILDX_EXPERIMENTAL: Turn on experimental features.
  • BUILDX_GIT_CHECK_DIRTY: Enable dirty Git checkout detection.
  • BUILDX_GIT_INFO: Remove Git information in provenance attestations.
  • BUILDX_GIT_LABELS: Add Git provenance labels to images.
  • BUILDX_NO_DEFAULT_ATTESTATIONS: Turn off default provenance attestations.
  • BUILDX_NO_DEFAULT_LOAD: Turn off loading images to the image store by default.

For more information, refer to the Docker Build Environment Variables documentation.

Compose Build Specification

The docker-compose.yml file can be used to define build configurations, including secrets and entitlements. Here’s an example:

version: "3.9"
services:
my_service:
build:
context: .
secrets:
- server-certificate

secrets:
server-certificate:
external: true

In this example, the secrets key is used to define a secret named server-certificate that is external to the Compose file. The secret is granted access to the service build as read-only at /run/secrets/<secret_name> within the container.

For more information, refer to the Compose Build Specification documentation.

Trusted Builders

buildx supports the concept of trusted builders, which can be used to improve build efficiency. When a builder is trusted, pack build operations will use a single lifecycle binary called the creator, which is more efficient than using an untrusted builder.

To configure trusted builders, you can use the pack config trusted-builders command. Here’s an example:

$ pack config trusted-builders add my-trusted-builder

For more information, refer to the Trusted Builders documentation.

Buildpack API

The Buildpack API is used to define the interface between builders and buildpacks. It includes the Build Plan, which is a document that buildpacks can use to pass information between the detect and build phases.

Here’s an example of a Build Plan:

{
"buildpacks": [
{
"id": "my-buildpack",
"version": "1.0.0",
"optional": false,
"metadata": {
"my-key": "my-value"
}
}
]
}

For more information, refer to the Buildpack API documentation.

Azure Integration

packer supports building images in Azure. Here’s an example of an Azure builder configuration:

{
"builders": [{
"type": "azure-arm",
"client_id": "my-client-id",
"client_secret": "my-client-secret",
"subscription_id": "my-subscription-id",
"build_resource_group_name": "my-resource-group"
}]
}

For more information, refer to the HashiCorp Developer documentation on Packer and Azure.

Docker Build Architecture

buildx uses the BuildKit architecture to perform builds. BuildKit supports requesting resources from Buildx, including local filesystem build contexts, build secrets, SSH sockets, and registry authentication tokens.

Here’s an example of a build sequence involving Buildx and BuildKit:

schedule
|
v
docker buildx create --use my-builder
|
v
docker buildx build --platform linux/amd64,linux/arm64 -t my-image .
|
v
BuildKit performs the build using resources requested from Buildx
|
v
docker image push my-image

For more information, refer to the Docker Build architecture documentation.

SLSA Definitions

SLSA (Supply-chain Levels for Software Artifacts) is a framework for ensuring the integrity of software artifacts throughout the software supply chain. BuildKit supports generating SLSA Provenance for builds that it runs.

Here’s an example of an SLSA Provenance document:

{
"builder": {
"id": "https://github.com/docker/buildx/actions/runs/3709599520"
},
"buildType": "https://mobyproject.org/buildkit@v1",
"invocation": {
"config": {
"platforms": [
"linux/amd64",
"linux/arm64"
]
},
"image": "my-image",
"metadata": {
"docker": "19.03.13",
"buildkit": "v0.10.2"
}
}
}

For more information, refer to the SLSA definitions documentation.

Bake File Reference

bake is a tool for defining and building Docker applications. It supports defining targets, secrets, and other build configurations.

Here’s an example of a Bakefile:

target "default" {
platforms = ["linux/amd64", "linux/arm64"]
pull = "always"
secret = [
"type = env,id = KUBECONFIG",
"type = file,id = aws,src = ${HOME}/.aws/credentials"
]
}

For more information, refer to the Bake file reference documentation.

Faster Multi-Platform Builds

buildx supports cross-compilation, which can be used to perform faster multi-platform builds. The BUILDPLATFORM variable can be used to match the current machine’s platform or the builder’s platform.

Here’s an example of a Dockerfile that uses cross-compilation:

FROM --platform=$BUILDPLATFORM golang:1.17 as builder

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY *.go ./
RUN go build -o my-binary

FROM --platform=$BUILDPLATFORM alpine:latest

COPY --from=builder /app/my-binary /usr/local/bin/
CMD ["my-binary"]

For more information, refer to the Faster Multi-Platform Builds documentation.

Conclusion

In this document, we have covered the possible options and provided examples for managing secrets and entitlements during the build process using the buildx tool. By using environment variables, Compose build specifications, trusted builders, the Buildpack API, Azure integration, Docker build architecture, SLSA definitions, Bake file reference, and faster multi-platform builds, you can ensure secure and efficient builds