README
¶
zbuild
Building container images without the hassle of writing Dockerfiles.
zbuild is a high-level container image build format providing an alternative to Dockerfiles but still fully compatible with Docker CLI. You don't have to write system commands to build images anymore and you can instead focus on what matters.
How to use?
0. Enable Docker Experimental features
As of now (2019-11-14), Buildkit is integrated into Docker but as an experimental feature. Thus, you need to enable experimental features to use Buildkit and this syntax provider.
If you are using Docker v18.06 or later, BuildKit mode can be enabled by setting export DOCKER_BUILDKIT=1 on the client side. Docker v18.06 also requires the daemon to be running in experimental mode.
1. Write zbuild files
Instead of writing Dockerfiles, you have to write zbuild files in YAML format. As zbuild implements builder backends for multiple kinds of images, you have to refer to their specific parameters.
Moreover, note that all zbuild files have to start with following header in order to use zbuild to build your images:
# syntax=akerouanton/zbuilder:test9
2. Create or Update the lock file
zbuild uses a lock file to ensure that dependencies installed during the build
process don't change randomly from one build to another. This is in line with
the Dockerfile best-practice that consist of pinning the version of each and
every dependency installed. As such, you can update your system dependencies
like you do with most modern library/package managers: zbuild update.
3. Build images
Finally, you can build your images using
$ docker build -f zbuild.yml -t prod .
How to work on this?
Debug LLB DAG
$ zbuild debug-llb --target prod | buildctl debug dump-llb
# Or
$ zbuild debug-llb --target prod --json | zbuild llbgraph | dot /dev/stdin -o /dev/stdout -T png | feh -
Review LLB DAGs changes
# Visually review differences between two LLB DAGs
$ ./tools/diff-dotgraph.py "$(cat graph1)" "$(cat graph2)"
# Visually review unstaged changes
$ ./tools/diff-dumps-from-git.py
# Visually review changes from a commit range
$ ./tools/diff-dumps-from-git.py HEAD~10:HEAD~1
# Visually review a bunch of graphs from a commit range
$ ./tools/diff-dumps-from-git.py HEAD~10:HEAD~1 path/to/graph1 path/to/graph2
Run with buildkitd
-
Start buildkit:
sudo buildkitd --debug -
Then run following command. Note that buildkit and docker don't share their images, so you have to build and push using Docker before executing this command:
$ buildctl build \
--frontend dockerfile.v0 \
--opt target=prod \
--opt filename=zbuild.yml \
--local context=. \
--local dockerfile=. \
--output type=image,name=some-image:dev
Build and push a new version
IMAGE_TAG=v<...> make build-image push
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pkg
|
|
|
builder
builder package implements the generic zbuild Builder, which is responsible of building specialized images from generic build definitions.
|
builder package implements the generic zbuild Builder, which is responsible of building specialized images from generic build definitions. |
|
llbtest
Package llbtest is a generated GoMock package.
|
Package llbtest is a generated GoMock package. |
|
mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |