Skip to content

Commit 22995ef

Browse files
qu1queeequ1queee
committed
Enhance docs with Buildkit
Document usage of BuildKit and update all related docs
1 parent fdc394e commit 22995ef

File tree

4 files changed

+162
-0
lines changed

4 files changed

+162
-0
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Shipwright supports any tool that can build container images in Kubernetes clust
2626

2727
- [Kaniko](https://github.com/GoogleContainerTools/kaniko)
2828
- [Cloud Native Buildpacks](https://buildpacks.io/)
29+
- [Buildkit](https://github.com/moby/buildkit)
2930
- [Buildah](https://buildah.io/)
3031

3132
## Try It!

‎docs/buildstrategies.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ SPDX-License-Identifier: Apache-2.0
1616
- [Try it](#try-it)
1717
- [Kaniko](#kaniko)
1818
- [Installing Kaniko Strategy](#installing-kaniko-strategy)
19+
- [Buildkit](#buildkit)
20+
- [Cache Exporters](#cache-exporters)
21+
- [Known Limitations](#known-limitations)
22+
- [Installing Buildkit Strategy](#installing-buildkit-strategy)
1923
- [ko](#ko)
2024
- [Installing ko Strategy](#installing-ko-strategy)
2125
- [Source to Image](#source-to-image)
@@ -106,6 +110,32 @@ kubectl apply -f samples/buildstrategy/kaniko/buildstrategy_kaniko_cr.yaml
106110

107111
---
108112

113+
## Buildkit
114+
115+
[Buildkit](https://github.com/moby/buildkit) is composed of the `buildctl` client and the `buildkitd` daemon. For the `buildkit` ClusterBuildStrategy, it runs on a [daemonless](https://github.com/moby/buildkit#daemonless) mode, where both client and ephemeral daemon run in a single container. In addition, it runs without privileges ( _[rootless](https://github.com/moby/buildkit/blob/master/docs/rootless.md)_ ).
116+
117+
### Cache Exporters
118+
119+
By default, the `buildkit` ClusterBuildStrategy will use caching to optimize the build times. When pushing an image to a registry, it will use the `inline` export cache, which pushes the image and cache together. Please refer to [export-cache docs](https://github.com/moby/buildkit#export-cache) for more information.
120+
121+
### Known Limitations
122+
123+
The `buildkit` ClusterBuildStrategy currently locks the following parameters:
124+
125+
- A `Dockerfile` name needs to be `Dockerfile`, this is currently not configurable.
126+
- Exporter caches are enable by default, this is currently not configurable.
127+
- To allow running rootless, it requires both [AppArmor](https://kubernetes.io/docs/tutorials/clusters/apparmor/) as well as [SecComp](https://kubernetes.io/docs/tutorials/clusters/seccomp/) to be disabled using the `unconfined` profile.
128+
129+
### Installing Buildkit Strategy
130+
131+
To install the cluster scope strategy, use:
132+
133+
```sh
134+
kubectl apply -f samples/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml
135+
```
136+
137+
---
138+
109139
## ko
110140

111141
The `ko` ClusterBuilderStrategy is using [ko](https://github.com/google/ko)'s publish command to build an image from a Golang main package.

‎docs/tutorials/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ The default installation includes these [buildstrategies](/docs/buildstrategies.
3434

3535
* [Buildpacks-v3](docs/buildstrategies.md#buildpacks-v3)
3636
* [Kaniko](docs/buildstrategies.md#kaniko)
37+
* [Buildkit](docs/buildstrategies.md#buildkit)
3738
* [Source-to-Image](docs/buildstrategies.md#source-to-image)
3839
* [Buildah](docs/buildstrategies.md#buildah)
3940
* [ko](docs/buildstrategies.md#ko)
@@ -46,6 +47,8 @@ For more information about strategies see the related [docs](/docs/buildstrategi
4647

4748
* [Example with Buildpacks](/docs/tutorials/building_with_buildpacks.md)
4849

50+
* [Example with Buildkit](/docs/tutorials/building_with_buildkit.md)
51+
4952
Depending on your source code you might want to try a specific example. The following table serves as a guide to help you understand which
5053
strategy to choose:
5154

‎docs/tutorials/building_with_buildkit.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
2+
# Building with Buildkit
3+
4+
Before starting, make sure you have Tekton and Shipwright Build installed.
5+
6+
See the [Try It!](../../README.md#try-it) section for more information.
7+
8+
## Getting Started
9+
10+
### Registry Authentication
11+
12+
For this tutorial, we will require to create a `tutorial-secret` Kubernetes secret to access a [DockerHub](https://hub.docker.com/) registry, as follows:
13+
14+
```sh
15+
$ REGISTRY_SERVER=https://index.docker.io/v1/ REGISTRY_USER=<your_registry_user> REGISTRY_PASSWORD=<your_registry_password>
16+
$ kubectl create secret docker-registry tutorial-secret --docker-server=$REGISTRY_SERVER --docker-username=$REGISTRY_USER --docker-password=$REGISTRY_PASSWORD [email protected]
17+
```
18+
19+
_Note_: For more information about authentication, please refer to the related [docs](/docs/development/authentication.md).
20+
21+
## Create the strategy
22+
23+
Ensure all strategies are in place, see the [Try It!](../../README.md#try-it) section for more information.
24+
25+
```sh
26+
$ kubectl get cbs
27+
NAME AGE
28+
buildah 96s
29+
buildkit 78s
30+
buildpacks-v3 96s
31+
kaniko 96s
32+
ko 96s
33+
source-to-image 96s
34+
```
35+
36+
_Note_: For more information about strategies, please refer to the related [docs](/docs/buildstrategies.md).
37+
38+
## Creating a Build
39+
40+
For the Build definition, we will require the following:
41+
42+
- A GitHub repository containing a Go [application](https://github.com/shipwright-io/sample-go/tree/main/docker-build) that requires a `Dockerfile`.
43+
- The `tutorial-secret` we just created.
44+
- The `buildkit` ClusterBuildStrategy.
45+
46+
Let's apply our Build and wait for it to be ready:
47+
48+
```bash
49+
$ export REGISTRY_ORG=<your_registry_org>
50+
$ cat <<EOF | kubectl apply -f -
51+
apiVersion: shipwright.io/v1alpha1
52+
kind: Build
53+
metadata:
54+
name: go-tutorial-buildkit
55+
spec:
56+
source:
57+
url: https://github.com/shipwright-io/sample-go
58+
contextDir: docker-build/
59+
dockerfile: docker-build/
60+
strategy:
61+
name: buildkit
62+
kind: ClusterBuildStrategy
63+
output:
64+
image: docker.io/${REGISTRY_ORG}/go-tutorial:latest
65+
credentials:
66+
name: tutorial-secret
67+
EOF
68+
```
69+
70+
_Note_: Pay attention to the definition under `spec.source.dockerfile`. The `buildkit` expects a path to where your `Dockerfile` is located.
71+
72+
Verify that the `go-tutorial` Build was created successfully:
73+
74+
```sh
75+
$ kubectl get build
76+
NAME REGISTERED REASON BUILDSTRATEGYKIND BUILDSTRATEGYNAME CREATIONTIME
77+
go-tutorial-buildkit True Succeeded ClusterBuildStrategy buildkit 4s
78+
```
79+
80+
_Note_: For more information about Build resources, please refer to the related [docs](/docs/build.md).
81+
82+
## Creating a BuildRun
83+
84+
Second, we will create a `BuildRun` resource that references our previous `go-tutorial` Build:
85+
86+
```sh
87+
$ cat <<EOF | kubectl create -f -
88+
apiVersion: shipwright.io/v1alpha1
89+
kind: BuildRun
90+
metadata:
91+
name: a-buildkit-buildrun
92+
spec:
93+
buildRef:
94+
name: go-tutorial-buildkit
95+
EOF
96+
```
97+
98+
Wait until your `go-tutorial-buildrun` buildrun is completed:
99+
100+
```sh
101+
$ kubectl get buildrun
102+
NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME
103+
a-buildkit-buildrun Unknown Pending 4s
104+
```
105+
106+
To know more about the state of the BuildRun, the `.Status.Conditions` fields provide more data:
107+
108+
```sh
109+
$ kubectl get buildrun a-buildkit-buildrun -o json | jq '.status.conditions[]'
110+
{
111+
"lastTransitionTime": "2021-04-01T09:15:13Z",
112+
"message": "All Steps have completed executing",
113+
"reason": "Succeeded",
114+
"status": "True",
115+
"type": "Succeeded"
116+
}
117+
```
118+
119+
_Note_: A BuildRun is a resource that runs to completion. The `REASON` column reflects the state of the resource. If the BuildRun ran to completion successfully,
120+
a `Succeeded` `REASON` is expected.
121+
122+
_Note_: For more information about BuildRun resources, please refer to the related [docs](/docs/buildrun.md).
123+
124+
## Closing
125+
126+
Congratulations! You just created a container image from https://github.com/shipwright-io/sample-go using [Buildkit](https://github.com/moby/buildkit).
127+
128+
The new container image should now be available in your container registry.

0 commit comments

Comments
 (0)