Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* examples/kubernetes: newly added * docs/rootless.md: cleaned up for better readability * examples/README.md: split out from the main README.md * examples/build-using-dockerfile/README.md: split out from the main README.md * README.md: add TOC using https://github.com/thlorenz/doctoc * README.md: add mTLS configuration (relates to #1074) * README.md: add more adoptions * README.md: add inline cache (fix #976) Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
- Loading branch information
1 parent
170ab6f
commit 1bde5d9
Showing
21 changed files
with
719 additions
and
270 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,3 @@ | ||
| bin | ||
| .certs | ||
| .tmp |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,4 @@ | ||
| bin | ||
| release-out | ||
| .certs | ||
| .tmp | ||
| release-out |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # BuildKit Examples | ||
|
|
||
| ## Kubernetes manifests | ||
| - [`./kubernetes`](./kubernetes): Kubernetes manifests (`Pod`, `Deployment`, `StatefulSet`, `Job`) | ||
|
|
||
| ## CLI examples | ||
| - [`./buildctl-daemonless`](./buildctl-daemonless): buildctl without daemon | ||
| - [`./build-using-dockerfile`](./build-using-dockerfile): an example BuildKit client with `docker build`-style CLI | ||
|
|
||
| ## LLB examples | ||
|
|
||
| For understanding the basics of LLB, `buildkit*` directory contains scripts that define how to build different configurations of BuildKit itself and its dependencies using the `client` package. Running one of these scripts generates a protobuf definition of a build graph. Note that the script itself does not execute any steps of the build. | ||
|
|
||
| You can use `buildctl debug dump-llb` to see what data is in this definition. Add `--dot` to generate dot layout. | ||
|
|
||
| ```bash | ||
| go run examples/buildkit0/buildkit.go \ | ||
| | buildctl debug dump-llb \ | ||
| | jq . | ||
| ``` | ||
|
|
||
| To start building use `buildctl build` command. The example script accepts `--with-containerd` flag to choose if containerd binaries and support should be included in the end result as well. | ||
|
|
||
| ```bash | ||
| go run examples/buildkit0/buildkit.go \ | ||
| | buildctl build | ||
| ``` | ||
|
|
||
| `buildctl build` will show interactive progress bar by default while the build job is running. If the path to the trace file is specified, the trace file generated will contain all information about the timing of the individual steps and logs. | ||
|
|
||
| Different versions of the example scripts show different ways of describing the build definition for this project to show the capabilities of the library. New versions have been added when new features have become available. | ||
|
|
||
| - `./buildkit0` - uses only exec operations, defines a full stage per component. | ||
| - `./buildkit1` - cloning git repositories has been separated for extra concurrency. | ||
| - `./buildkit2` - uses git sources directly instead of running `git clone`, allowing better performance and much safer caching. | ||
| - `./buildkit3` - allows using local source files for separate components eg. `./buildkit3 --runc=local | buildctl build --local runc-src=some/local/path` | ||
| - `./dockerfile2llb` - can be used to convert a Dockerfile to LLB for debugging purposes | ||
| - `./nested-llb` - shows how to use nested invocation to generate LLB | ||
| - `./gobuild` - shows how to use nested invocation to generate LLB for Go package internal dependencies |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| # `build-using-dockerfile` example | ||
|
|
||
| :information_source: [BuildKit has been integrated to `docker build` since Docker 18.06.](https://docs.docker.com/develop/develop-images/build_enhancements/) | ||
| The `build-using-dockerfile` CLI is just provided as an example for writing a BuildKit client application. | ||
|
|
||
| For people familiar with `docker build` command, `build-using-dockerfile` is provided as an example for building Dockerfiles with BuildKit using a syntax similar to `docker build`. | ||
|
|
||
| ```bash | ||
| go get . | ||
|
|
||
| build-using-dockerfile -t myimage /path/to/dir | ||
|
|
||
| # build-using-dockerfile will automatically load the resulting image to Docker | ||
| docker inspect myimage | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| kubernetes/consistenthash |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| # Kubernetes manifests for BuildKit | ||
|
|
||
| This directory contains Kubernetes manifests for `Pod`, `Deployment` (with `Service`), `StatefulSet`, and `Job`. | ||
| * `Pod`: good for quick-start | ||
| * `Deployment` + `Service`: good for random load balancing with registry-side cache | ||
| * `StateFulset`: good for client-side load balancing, without registry-side cache | ||
| * `Job`: good if you don't want to have daemon pods | ||
|
|
||
| Using Rootless mode (`*.rootless.yaml`) is recommended because Rootless mode image is executed as non-root user (UID 1000) and doesn't need `securityContext.privileged`. | ||
|
|
||
| :warning: Rootless mode may not work on some host kernels. See [`../../docs/rootless.md`](../../docs/rootless.md). | ||
|
|
||
| See also ["Building Images Efficiently And Securely On Kubernetes With BuildKit" (KubeCon EU 2019)](https://kccnceu19.sched.com/event/MPX5). | ||
|
|
||
| ## `Pod` | ||
|
|
||
| ```console | ||
| $ kubectl apply -f pod.rootless.yaml | ||
| $ buildctl \ | ||
| --addr kube-pod://buildkitd \ | ||
| build --frontend dockerfile.v0 --local context=/path/to/dir --local dockerfile=/path/to/dir | ||
| ``` | ||
|
|
||
| If rootless mode doesn't work, try `pod.privileged.yaml`. | ||
|
|
||
| :warning: `kube-pod://` connection helper requires Kubernetes role that can access `pods/exec` resources. If `pods/exec` is not accessible, use `Service` instead (See below). | ||
|
|
||
| ## `Deployment` + `Service` | ||
|
|
||
| Setting up mTLS is highly recommended. | ||
|
|
||
| `./create-certs.sh SAN [SAN...]` can be used for creating certificates. | ||
| ```console | ||
| $ ./create-certs.sh 127.0.0.1 | ||
| ``` | ||
|
|
||
| The daemon certificates is created as `Secret` manifest named `buildkit-daemon-certs`. | ||
| ```console | ||
| $ kubectl apply -f .certs/buildkit-daemon-certs.yaml | ||
| ``` | ||
|
|
||
| Apply the `Deployment` and `Service` manifest: | ||
| ```console | ||
| $ kubectl apply -f deployment+service.rootless.yaml | ||
| $ kubectl scale --replicas=10 deployment/buildkitd | ||
| ``` | ||
|
|
||
| Run `buildctl` with TLS client certificates: | ||
| ```console | ||
| $ kubectl port-forward service/buildkitd 1234 | ||
| $ buildctl \ | ||
| --addr tcp://127.0.0.1:1234 \ | ||
| --tlscacert .certs/client/ca.pem \ | ||
| --tlscert .certs/client/cert.pem \ | ||
| --tlskey .certs/client/key.pem \ | ||
| build --frontend dockerfile.v0 --local context=/path/to/dir --local dockerfile=/path/to/dir | ||
| ``` | ||
|
|
||
| ## `StatefulSet` | ||
| `StatefulSet` is useful for consistent hash mode. | ||
|
|
||
| ```console | ||
| $ kubectl apply -f statefulset.rootless.yaml | ||
| $ kubectl scale --replicas=10 statefulset/buildkitd | ||
| $ buildctl \ | ||
| --addr kube-pod://buildkitd-4 \ | ||
| build --frontend dockerfile.v0 --local context=/path/to/dir --local dockerfile=/path/to/dir | ||
| ``` | ||
|
|
||
| See `[./consistenthash`](./consistenthash) for how to use consistent hashing. | ||
|
|
||
| ## `Job` | ||
|
|
||
| ```console | ||
| $ kubectl apply -f job.rootless.yaml | ||
| ``` | ||
|
|
||
| To push the image to the registry, you also need to mount `~/.docker/config.json` | ||
| and set `$DOCKER_CONFIG` to `/path/to/.docker` directory. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
Oops, something went wrong.