A [buildpack](https://buildpacks.io/) converts source code into an executable, and is used to deliver a simple, reliable, and repeatable way to create containers. Kf supports both V2 and V3 buildpacks, and it is important to understand the differences between them.

## V2 buildpacks

Most Cloud Foundry applications already use V2 buildpacks. When using V2 buildpacks with Kf, the lifecycle binaries and the buildpacks are downloaded and configured from their git URLs. Kf then uses the `lifecycle` CLI to execute each buildpack against the source code.

### Pros

- Ready out of the box without pipeline or code changes.

### Cons

- Legacy buildpack supersceded by V3.
- Weaker performance and reliability. The Kf build pipeline requires more IO for V2 buildpacks.
- Fewer community resources.
- Kf only supports OSS git repos.

## V3 buildpacks

V3 buildpacks are a Cloud Native Computing Foundation (CNCF) project with a well defined [spec](https://github.com/buildpacks/spec/blob/main/buildpack.md), a CLI ([pack](https://github.com/buildpacks/pack)) and a growing community that is innovating around different languages and frameworks. Google Cloud also has its own set of
[Google Cloud's buildpacks](https://docs.cloud.google.com/docs/buildpacks/overview.md.txt).

V3 buildpacks have two overarching OCI containers:

- Builder image
- Run image

### Builder image

The builder image is used while your source code is being built into a runnable container. The image has the necessary `detect` scripts and other utilities to compile source code.

> [!NOTE]
> **Note:** Most buildpacks don't package the compilers with the builder image. Instead, they may have the build pipelines download any dependencies required to compile.

### Run image

The run image is the base image that a container is built on. This means that it is the base image that will run when the App executes.

### Layers

V3 buildpacks use layers to compose the final container. Each buildpack included in a build is given the opportunity to manipulate the file system and environment variables of the App. This layering approach allows for buildpacks to be thinner and more generic.

V3 buildpacks are built on OCI containers. This requires that the V3 builder image be stored in a container registry that the Kf build pipeline has access to. The build pipeline uses the builder image to apply the underlying scripts to build the source code into a runnable container.

### Pros

- Google supported [builder and run image](https://docs.cloud.google.com/docs/buildpacks/overview.md.txt).
- Works with various Google Cloud products like [Cloud Build](https://docs.cloud.google.com/functions/docs/building/pack).
- Growing community and [buildpack registry](https://registry.buildpacks.io/).

### Cons

- May require code/process updates. For example, the Java buildpack requires source code while the V2 buildpack requires a jar file.
- V3 buildpacks are newer and might require additional validation (is using community developed buildpacks).

## Kf Stacks

### View Stacks

When pushing an App, the build pipeline determines the buildpack based on the selected Stack (specified via the `--stack` flag or the manifest).

To see which Stacks are available in a Space first ensure a Space is targeted:

```bash
kf target -s myspace
```

The `kf stacks` subcommand can then be used to list the Stacks:

```bash
kf stacks
```

The output shows both V2 and V3 Stacks:

    Getting stacks in Space: myspace
    Version  Name                                Build Image                                                                                          Run Image                                                                                          Description
    V2       cflinuxfs3                          cloudfoundry/cflinuxfs3@sha256:5219e9e30000e43e5da17906581127b38fa6417f297f522e332a801e737928f5      cloudfoundry/cflinuxfs3@sha256:5219e9e30000e43e5da17906581127b38fa6417f297f522e332a801e737928f5
    V3       org.cloudfoundry.stacks.cflinuxfs3  cloudfoundry/cnb:cflinuxfs3@sha256:f96b6e3528185368dd6af1d9657527437cefdaa5fa135338462f68f9c9db3022  cloudfoundry/run:full-cnb@sha256:dbe17be507b1cc6ffae1e9edf02806fe0e28ffbbb89a6c7ef41f37b69156c3c2  A large Cloud Foundry stack based on Ubuntu 18.04

### Configure Stacks

The Stack configuration can be updated by editing the `kfsystem` Custom Resource:

```bash
kubectl edit kfsystem kfsystem
```

This example sets the Google Cloud buildpacks a V3 Stack:

    spec:
      kf:
        config:
          spaceStacksV3:
          - name: google
            description: Google buildpacks (https://github.com/GoogleCloudPlatform/buildpacks)
            buildImage: gcr.io/buildpacks/builder:v1
            runImage: gcr.io/buildpacks/gcp/run:v1

This new Stack can now be pushed:

```bash
kf push myapp --stack google
```

This example configures the Ruby V2 buildpack and sets the build pipeline defaults to use V2 Stacks:

    spec:
      kf:
        config:
          spaceDefaultToV3Stack: false
          spaceBuildpacksV2:
          - name: ruby_buildpack
            url: https://github.com/cloudfoundry/ruby-buildpack
          spaceStacksV2:
          - name: cflinuxfs3
            image: cloudfoundry/cflinuxfs3@sha256:5219e9e30000e43e5da17906581127b38fa6417f297f522e332a801e737928f5

## Migration

*Note: This feature is currently experimental and subject to change.*

Kf has a migration tool that can wrap a V2 buildpack. The result is a V3 buildpack that can be used within a V3 builder. The wrapped buildpack can then be used anywhere V3 buildpacks are available.

```bash
kf wrap-v2-buildpack gcr.io/your-project/v2-go-buildpack https://github.com/cloudfoundry/go-buildpack --publish
```

This will create a buildpack image named `gcr.io/your-project/v2-go-buildpack`. It can then be used to create a builder by following the [create a builder](https://buildpacks.io/docs/operator-guide/create-a-builder/) docs.

This subcommand uses the following CLIs transparently:

- `go`
- `git`
- `pack`

It is recommended that you use Cloud Shell Editor to ensure each subcommand is available on the correct path and is the correct version.

## Known issues

The following are features that don't yet work with Kf. If one is high priority for your organization, please reach out to your sales representative:

- Private container registries for V3 builder images.
- V3 caching.
- V2 buildpacks that require git credentials.