Skip to content

Commit 5b88355

Browse files
jjbustamantejjbustamante
committed
Adding documentation for build resource vs pack in a new file, and also
adding links from README and build resource. Signed-off-by: Juan Bustamante <jbustamante@vmware.com>
1 parent fbc48e7 commit 5b88355

3 files changed

Lines changed: 161 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ kpack also provides a build type to execute a single Cloud Native Buildpack OCI
2020

2121
- [Install kpack](docs/install.md)
2222
- Get started with [the tutorial](docs/tutorial.md)
23+
- Are you familiar with pack? check our [comparison section](docs/kpack-vs-pack.md)
2324
- Check out the documentation on kpack concepts:
2425
- [Stacks](docs/stack.md)
2526
- [Images](docs/image.md)

‎docs/build.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ Corresponding `kp` cli command docs [here](https://github.com/vmware-tanzu/kpack
66

77
Unlike with the [Image resource](image.md), using Builds directly allows granular control of when builds execute. Each build resource is immutable and corresponds to a single build execution. You will need to create a new build for every build execution as builds will not rebuild on source code and buildpack updates. Additionally, you will need to manually specify the source, and the cache volume.
88

9+
A Build resource is comparable to `pack build`. Are you familiar with pack? if so, you can check the [comparison section](kpack-vs-pack.md)
10+
911
### Configuration
1012

1113
```yaml

‎docs/kpack-vs-pack.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
2+
# kpack vs pack
3+
4+
So, you are a [pack][_pack] user trying to learn about [kpack][_kpack] and get your [Cloud Native Buildpacks][_cnb] journey to the next level? then you are in the right place, on the next sections we are going to explain the similarities between [pack][_pack] and [kpack][_kpack].
5+
6+
First of all, both [kpack][_kpack] and [pack][_pack] implement the [platform interface](https://github.com/buildpacks/spec/blob/main/platform.md) [specification](https://github.com/buildpacks/spec/blob/main/platform.md), but they do it for two non-overlapping contexts: while [pack][_pack] targets developers and local builds, [kpack][_kpack] manages containerization on day-2 and at scale and is a [Kubernetes](https://kubernetes.io/) native implementation.
7+
8+
We will define some basic use case scenarios and see how we can get the output from both tools.
9+
10+
## Assumptions
11+
12+
In order to make our comparison very simple, lets make some assumptions:
13+
1. Our application source code is one of the [samples](https://github.com/buildpacks/samples/tree/main/apps) application
14+
2. We are going to use [Cloud Native Buildpacks](_cnb) [sample builder](https://hub.docker.com/r/cnbs/sample-builder) to build our application source code
15+
3. We need **write** access to a remote registry to publish our application image
16+
17+
## Build scenario
18+
19+
Let's define our most basic use case as follows:
20+
21+
`As a [pack|kpack] user, I want to convert my application source code into an image and publish it into a remote registry`
22+
23+
### Pack Implementation
24+
25+
In order to build our application source code using [pack][_pack] we need to run a command similar to this:
26+
27+
`pack build --publish --path apps/<APP> --builder cnbs/sample-builder:<bionic OR alpine> <app-image-name>`
28+
29+
After building your '<app-image-name>' must be written into your remote registry.
30+
31+
### Kpack Implementation
32+
33+
How do we get a similar functionality to a `pack build` command using [kpack][_kpack]? the answer is the Build resource!
34+
35+
Once you have [kpack][_kpack] up and running on a kubernetes cluster, you need to create a Build resource and apply it to your cluster. for our scenario it looks like this:
36+
37+
```yaml
38+
apiVersion: kpack.io/v1alpha2
39+
kind: Build
40+
metadata:
41+
name: sample-build # This can be any name
42+
spec:
43+
tags:
44+
- <app-image-name>
45+
builder:
46+
image: cnbs/sample-builder:<bionic OR alpine>
47+
source:
48+
git:
49+
url: https://github.com/buildpacks/samples.git
50+
revision: main
51+
subPath: "apps/<APP>"
52+
```
53+
54+
Once you create yaml file, the next step is just to apply the resource into your kubernetes cluster, for example using
55+
56+
```bash
57+
kubectl apply -f <your-build-resource.yaml>
58+
```
59+
60+
After building, your '<app-image-name>' must be also written into your remote registry.
61+
62+
**Note** Probably you will need to create some [secrets](secrets.md) to give [kpack][_kpack] access to your remote registry, but this is also required on [pack][_pack], so please check the documentation depending on your registry provider
63+
64+
## Re-build scenario
65+
66+
`As a [pack|kpack] user, I want to rebuild my application source code after some change and publish a new image into a remote registry`
67+
68+
### Pack Implementation
69+
70+
In [pack][_pack], in order to re-build your application image, you just need to run the `pack build` command after saving your application source code changes
71+
72+
### Kpack Implementation
73+
74+
As we mentioned above, All fields on a build are immutable, this mean that every time we want to run a build we must create a new `Build` resource. One way to do this is using `generateName` field in our resource definition.
75+
76+
From our previous resource definition, let's remove the `metadata.name` field, and replace it with a `metadata.generateName` this value will be used by the server, to generate a unique name ONLY IF the Name field has not been provided.
77+
78+
```yaml
79+
apiVersion: kpack.io/v1alpha2
80+
kind: Build
81+
metadata:
82+
generateName: sample-build- # this value will be a prefix
83+
spec:
84+
tags:
85+
- <app-image-name>
86+
builder:
87+
image: cnbs/sample-builder:<bionic OR alpine>
88+
source:
89+
git:
90+
url: https://github.com/buildpacks/samples.git
91+
revision: main
92+
subPath: "apps/<APP>"
93+
```
94+
Once you create yaml file, any time you want to create a build, just run
95+
96+
```bash
97+
kubectl create -f <your-build-resource.yaml>
98+
```
99+
100+
A new build resource will be created and a unique suffix will be added to the value provided, for example: `sample-build-2vsz5`
101+
102+
Note: use `create` instead of `apply` when using `generateName`
103+
104+
## Rebase scenario
105+
106+
`As a [pack|kpack] user, I want to rebase my application image with a new run-image from the stack`
107+
108+
### Pack Implementation
109+
110+
[pack][_pack] offers the `pack rebase` command to accomplish this goal, for example:
111+
112+
```bash
113+
pack rebase --publish <app-image-name>
114+
```
115+
116+
### Kpack Implementation
117+
118+
A standalone build can be triggered to be rebase if [kpack][_kpack] detects it is a "rebase-able" build.
119+
120+
A build is considered "rebase-able" if the following conditions are met:
121+
122+
- the field `spec.lastBuild.stackId` is equal to <same-stack-id-as-the-builder>
123+
- An annotation key `image.kpack.io/reason` is equal to `STACK`
124+
125+
An example resource that also is configured to use the `generateName` field could be as follows:
126+
127+
```yaml
128+
apiVersion: kpack.io/v1alpha2
129+
kind: Build
130+
metadata:
131+
generateName: sample-build- # this value will be a prefix
132+
annotations:
133+
image.kpack.io/reason: STACK
134+
spec:
135+
lastBuild:
136+
stackId: <same-stack-id-as-the-builder>
137+
tags:
138+
- <app-image-name>
139+
builder:
140+
image: cnbs/sample-builder:<bionic OR alpine>
141+
source:
142+
git:
143+
url: https://github.com/buildpacks/samples.git
144+
revision: main
145+
subPath: "apps/<APP>"
146+
```
147+
Once you create yaml file, just run
148+
149+
```bash
150+
kubectl create -f <your-build-resource.yaml>
151+
```
152+
153+
[kpack][_kpack] will create a pod execution the rebase operation
154+
155+
156+
[_pack]:https://github.com/buildpacks/pack
157+
[_kpack]:https://github.com/pivotal/kpack
158+
[_cnb]:https://buildpacks.io

0 commit comments

Comments
 (0)