From 5b883551c48ac0ec14f8617b22afb22548a6719a Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Mon, 27 Feb 2023 12:45:45 -0500 Subject: [PATCH] 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 --- README.md | 1 + docs/build.md | 2 + docs/kpack-vs-pack.md | 158 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 161 insertions(+) create mode 100644 docs/kpack-vs-pack.md diff --git a/README.md b/README.md index 65bb4a69c..8e5454e19 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ kpack also provides a build type to execute a single Cloud Native Buildpack OCI - [Install kpack](docs/install.md) - Get started with [the tutorial](docs/tutorial.md) +- Are you familiar with pack? check our [comparison section](docs/kpack-vs-pack.md) - Check out the documentation on kpack concepts: - [Stacks](docs/stack.md) - [Images](docs/image.md) diff --git a/docs/build.md b/docs/build.md index cb65d06e8..845cd4bd7 100644 --- a/docs/build.md +++ b/docs/build.md @@ -6,6 +6,8 @@ Corresponding `kp` cli command docs [here](https://github.com/vmware-tanzu/kpack 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. +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) + ### Configuration ```yaml diff --git a/docs/kpack-vs-pack.md b/docs/kpack-vs-pack.md new file mode 100644 index 000000000..73df39c37 --- /dev/null +++ b/docs/kpack-vs-pack.md @@ -0,0 +1,158 @@ + +# kpack vs pack + +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]. + +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. + +We will define some basic use case scenarios and see how we can get the output from both tools. + +## Assumptions + +In order to make our comparison very simple, lets make some assumptions: +1. Our application source code is one of the [samples](https://github.com/buildpacks/samples/tree/main/apps) application +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 +3. We need **write** access to a remote registry to publish our application image + +## Build scenario + +Let's define our most basic use case as follows: + +`As a [pack|kpack] user, I want to convert my application source code into an image and publish it into a remote registry` + +### Pack Implementation + +In order to build our application source code using [pack][_pack] we need to run a command similar to this: + +`pack build --publish --path apps/ --builder cnbs/sample-builder: ` + +After building your '' must be written into your remote registry. + +### Kpack Implementation + +How do we get a similar functionality to a `pack build` command using [kpack][_kpack]? the answer is the Build resource! + +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: + +```yaml +apiVersion: kpack.io/v1alpha2 +kind: Build +metadata: + name: sample-build # This can be any name +spec: + tags: + - + builder: + image: cnbs/sample-builder: + source: + git: + url: https://github.com/buildpacks/samples.git + revision: main + subPath: "apps/" +``` + +Once you create yaml file, the next step is just to apply the resource into your kubernetes cluster, for example using + +```bash +kubectl apply -f +``` + +After building, your '' must be also written into your remote registry. + +**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 + +## Re-build scenario + +`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` + +### Pack Implementation + +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 + +### Kpack Implementation + +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. + +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. + +```yaml +apiVersion: kpack.io/v1alpha2 +kind: Build +metadata: + generateName: sample-build- # this value will be a prefix +spec: + tags: + - + builder: + image: cnbs/sample-builder: + source: + git: + url: https://github.com/buildpacks/samples.git + revision: main + subPath: "apps/" +``` +Once you create yaml file, any time you want to create a build, just run + +```bash +kubectl create -f +``` + +A new build resource will be created and a unique suffix will be added to the value provided, for example: `sample-build-2vsz5` + +Note: use `create` instead of `apply` when using `generateName` + +## Rebase scenario + +`As a [pack|kpack] user, I want to rebase my application image with a new run-image from the stack` + +### Pack Implementation + +[pack][_pack] offers the `pack rebase` command to accomplish this goal, for example: + +```bash +pack rebase --publish +``` + +### Kpack Implementation + +A standalone build can be triggered to be rebase if [kpack][_kpack] detects it is a "rebase-able" build. + +A build is considered "rebase-able" if the following conditions are met: + +- the field `spec.lastBuild.stackId` is equal to +- An annotation key `image.kpack.io/reason` is equal to `STACK` + +An example resource that also is configured to use the `generateName` field could be as follows: + +```yaml +apiVersion: kpack.io/v1alpha2 +kind: Build +metadata: + generateName: sample-build- # this value will be a prefix + annotations: + image.kpack.io/reason: STACK +spec: + lastBuild: + stackId: + tags: + - + builder: + image: cnbs/sample-builder: + source: + git: + url: https://github.com/buildpacks/samples.git + revision: main + subPath: "apps/" +``` +Once you create yaml file, just run + +```bash +kubectl create -f +``` + +[kpack][_kpack] will create a pod execution the rebase operation + + +[_pack]:https://github.com/buildpacks/pack +[_kpack]:https://github.com/pivotal/kpack +[_cnb]:https://buildpacks.io