Blubber is a BuildKit frontend for building application container images from a minimal set of declarative constructs in YAML. Its focus is on composability, determinism, cache efficiency, and secure default behaviors.

Examples

To skip to the examples, see the feature files in the examples directory. The examples are implemented as executable Cucumber tests to ensure Blubber is always working as expected by users.

Concepts

Variants

Blubber supports a concept of composeable configuration variants for defining slightly different container images while still maintaining a sufficient degree of parity between them. For example, images for development and testing may require some development and debugging packages which you wouldn't want in production lest they contain vulnerabilities and somehow end up linked or included in the application runtime.

See the copying from other variants example.

Builders

Builders represent a discrete process and a set of files that is needed to produce an application artifact.

See the builders example.

When defining multiple builders, be sure to use the builders field to ensure an explicit ordering.

Similarly to other configuration keys, builders appearing at the top level of the file will be applied to all variant configurations. Builder keys appearing both at the top level and in a variant, will be merged; whereas builders present only at the top level will be placed first in the execution order.

For a particular variant, builders and the standalone builder keys are mutually exclusive, but different styles can be used for different variants. However, note that top level definitions are applied to all variants, so using one style at the top level precludes the use of the other for all variants.

Usage

Blubber used to include both a CLI and microservice for transpiling to Dockerfile text. It is now exclusively a BuildKit frontend that works with both BuildKit's buildctl command and with docker build directly.

To build from Blubber configuration using buildctl, do:

$ buildctl build --frontend gateway.v0 \
  --opt source=docker-registry.wikimedia.org/repos/releng/blubber/buildkit:v1.0.1 \
  --local context=. \
  --local dockerfile=. \
  --opt filename=blubber.yaml \
  --opt variant=test

If you'd like to build directly with docker build (or other toolchains that invoke it like docker-compose), specify a syntax directive at the top of your Blubber configuration like so.

# syntax=docker-registry.wikimedia.org/repos/releng/blubber/buildkit:v1.0.1
version: v4
variants:
  my-variant:
  [...]

And invoke docker build --target my-variant -f blubber.yaml .. Note that Docker must have BuildKit enabled as the default builder. You can also use docker buildx which always uses BuildKit.

Docker's build-time arguments are also supported, including those used to provide proxies to build processes.

buildctl build --frontend gateway.v0 \
  --opt source=docker-registry.wikimedia.org/repos/releng/blubber/buildkit:v1.0.1 \
  --opt build-arg:http_proxy=http://proxy.example \
  --opt variant=pulls-in-stuff-from-the-internet
  ...

Additional options for the Buildkit frontend

The following options can be passed via command line (via --opt) to configure the build process:

• run-variant: bool. Instructs Blubber to run the target variant's entrypoint (if any) as part of the BuildKit image build process
• entrypoint-args: JSON array. List of additional arguments for the entrypoint
• run-variant-env: JSON object of key/value pairs to set in the environment when run-variant is true.

Example usage:

$ buildctl build --frontend gateway.v0 \
  --opt source=docker-registry.wikimedia.org/repos/releng/blubber/buildkit:v1.0.1 \
  --local context=. \
  --local dockerfile=. \
  --opt filename=blubber.yaml \
  --opt variant=test \
  --opt run-variant=true \
  --opt entrypoint-args='["extraParam1", "extraParam2"]' \
  --opt run-variant-env='{"SOME_VARIABLE": "somevalue"}'
  ...

Building for multiple platforms

Blubber's BuildKit frontend supports building for multiple platforms at once and publishing a single manifest index for the given platforms (aka a "fat" manifest). See the OCI Image Index Specification for details.

Note that your build process must be aware of the environment variables set for multi-platform builds in order to perform any cross-compilation needed.

Example usage:

$ buildctl build --frontend gateway.v0 \
  --opt source=docker-registry.wikimedia.org/repos/releng/blubber/buildkit:v1.0.1 \
  --local context=. \
  --local dockerfile=. \
  --opt filename=blubber.yaml \
  --opt variant=production \
  --opt platform=linux/amd64,linux/arm64 \
  --output type=image,name=my/multi-platform-app:v1.0,push=true

$ docker manifest inspect my/multi-platform-app:v1.0
{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": <n>,
         "digest": "sha256:<digest>",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": <n>,
         "digest": "sha256:<digest>",
         "platform": {
            "architecture": "arm64",
            "os": "linux"
         }
      }
   ]
}

Image attestations

The Blubber BuildKit frontend supports the creation and export of Software Bill of Materials (SBOM) and provenance metadata in the form of in-toto attestations.

Attestations are exported in the form of image manifests that live alongside your images within the same manifest list/index. See the upstream BuildKit documentation on image attestation storage for details.

Provenance

To have Blubber create provenance metadata for your build...

Using buildctl:

$ buildctl build --frontend gateway.v0 \
  --opt source=docker-registry.wikimedia.org/repos/releng/blubber/buildkit:v1.0.1 \
  --opt attest:provenance= \
  # ...

Using docker buildx:

$ docker buildx build \
  --attest=type=provenance \
  # ...

See the BuildKit provenance documentation for details and additional options.

Software Bill of Materials

To have Blubber produce an SBOM for your build using Docker's default scanner...

Using buildctl:

$ buildctl build --frontend gateway.v0 \
  --opt source=docker-registry.wikimedia.org/repos/releng/blubber/buildkit:v1.0.1 \
  --opt attest:sbom= \
  # ...

Using docker buildx:

$ docker buildx build \
  --attest=type=sbom \
  # ...

See the BuildKit SBOM documentation for details and additional options including how to provide your own scanner.