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 theexamplesdirectory. 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 thecopying from other variants example.

Builders​

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

See thebuilders example.

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

Similarly to other configuration keys,buildersappearing 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,buildersand 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 aBuildKit frontendthat works with both BuildKit'sbuildctlcommand and withdocker builddirectly.

To build from Blubber configuration usingbuildctl,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 withdocker build(or other toolchains that invoke it likedocker-compose), specify asyntax directiveat 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 invokedocker build --target my-variant -f blubber.yaml..Note that Docker must have BuildKit enabled as the default builder. You can also usedocker buildxwhich always uses BuildKit.

Docker'sbuild-time argumentsare 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 whenrun-variantis 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 theOCI Image Index Specificationfor details.

Note that your build process must be aware of theenvironment variablesset 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 ofin-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 onimage attestation storagefor details.

Provenance​

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

Usingbuildctl:

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

Usingdocker buildx:

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

See the BuildKitprovenance documentationfor details and additional options.

Software Bill of Materials​

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

Usingbuildctl:

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

Usingdocker buildx:

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

See the BuildKitSBOM documentationfor details and additional options including how to provide your own scanner.