Merge branch 'main' into build-config-env

Author: AidanDelaney

.github/workflows/main.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install pack
         uses: buildpacks/github-actions/[email protected]
         with:
-          pack-version: '0.30.0-rc1' # FIXME: update to 0.30.0 when available
+          pack-version: '0.31.0'
       - name: Test
         run: make test
         env:

content/docs/app-developer-guide/run-an-app.md

@@ -48,7 +48,7 @@ Base Image:
   Top Layer: sha256:700c764e7c5d5c75e6a0fc7d272b7e1c70ab327c03fbdf4abd9313e5ec3217f7
 
 Run Images:
-  cnbs/sample-stack-run:alpine
+  cnbs/sample-base-run:alpine
 
 Rebasable: true
 

content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md

@@ -25,7 +25,7 @@ You should see the following:
 <!-- test:assert=contains;ignore-lines=... -->
 ```text
 Run Images:
-  cnbs/sample-stack-run:jammy
+  cnbs/sample-base-run:jammy
 ...
 
 Buildpacks:
@@ -55,9 +55,13 @@ api = "0.8"
   version = "0.0.1"
   sbom-formats = [ "application/vnd.cyclonedx+json" ]
 
-# Stacks that the buildpack will work with
+# Targets the buildpack will work with
+[[targets]]
+os = "linux"
+
+# Stacks (deprecated) the buildpack will work with
 [[stacks]]
-  id = "io.buildpacks.samples.stacks.jammy"
+  id = "*"
 ```
 
 Then, in our buildpack implementation we will generate the necessary SBOM metadata:

content/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb.md

@@ -28,8 +28,8 @@ This command will create `ruby-buildpack` directory which contains `buildpack.to
 ### Additional Parameters
 - `-a, --api` Buildpack API compatibility of the generated buildpack
 - `-h, --help` Help for 'new'
-- `--path` the location on the filesystem to generate the artifacts.
-- `--stacks` Stack(s) this buildpack will be compatible with. Repeat for each stack in order, or supply once by comma-separated list
+- `--path` the location on the filesystem to generate the artifacts
+- `--stacks` Stacks (deprecated) the buildpack will work with
 - `-V, --version` the version of the buildpack in buildpack.toml
 
 
@@ -48,13 +48,19 @@ api = "0.8"
   id = "examples/ruby"
   version = "0.0.1"
 
-# Stacks that the buildpack will work with
+# Targets the buildpack will work with
+[[targets]]
+os = "linux"
+
+# Stacks (deprecated) the buildpack will work with
 [[stacks]]
   id = "io.buildpacks.samples.stacks.jammy"
 
 ```
 
-You will notice two specific fields in the file: `buildpack.id` and `stack.id`. The buildpack ID is the way you will reference the buildpack when you create buildpack groups, builders, etc. The stack ID is the root file system in which the buildpack will be run. This example can be run on one of two different stacks, both based upon Ubuntu Bionic.
+The buildpack ID is the way you will reference the buildpack when you create buildpack groups, builders, etc.
+[Targets](/docs/concepts/components/targets/) identifies the kind of build and run base images the buildpack will work with.
+The stack ID (deprecated) uniquely identifies a build and run image configuration the buildpack will work with. This example can be run on Ubuntu Jammy.
 
 ### `detect` and `build`
 

content/docs/concepts/_index.md

@@ -47,7 +47,8 @@ For example:
 
 ![builder](/docs/concepts/builder.svg)
 
-[`Builders`](/docs/concepts/components/builder) are an ordered combination of [`buildpacks`](/docs/concepts/components/buildpack) with a base `build` image, a lifecycle, and reference to a `run image`. They take in your `app` source code and build the output `app image`. The `build` image provides the base environment for the `builder` (for eg. an Ubuntu Bionic OS image with build tooling) and a `run` image provides the base environment for the `app image` during runtime. A combination of a `build` image and a `run` image is called a [`stack`](/docs/concepts/components/stack).
+[`Builders`](/docs/concepts/components/builder) are an ordered combination of [`buildpacks`](/docs/concepts/components/buildpack) with a base `build image`, a lifecycle, and reference to a `run image`.
+They take in your `app` source code and build the output `app image`. The `build image` provides the base environment for the `builder` (for eg. an Ubuntu Bionic OS image with build tooling) and a `run image` provides the base environment for the `app image` during runtime.
 
 Under the hood a builder uses the [`lifecycle`](/docs/concepts/components/lifecycle) to run the `detect` phase for all the `buildpacks` it contains in order and then proceeds to run the `build` phase of all the `buildpacks` that passed detection.
 

content/docs/concepts/components/base-images/build.md

@@ -0,0 +1,9 @@
++++
+title="Build image"
+weight=1
++++
+
+## What is a build image?
+
+The **build image** provides the base image from which the build environment is constructed.
+The build environment is the containerized environment in which the [lifecycle][lifecycle] (and thereby [buildpacks][buildpack]) are executed.

content/docs/concepts/components/base-images/run.md

@@ -0,0 +1,41 @@
++++
+title="Run image"
+weight=2
++++
+
+## What is a run image?
+
+The **run image** provides the base image for application images.
+The lifecycle requires a reference to a run image and (where necessary) possible run image mirrors in order to construct the application image.
+
+### Run image mirrors
+
+Run image mirrors provide alternate locations for run images, for use during `build` or `rebase`.
+When running `build` with a builder containing run image mirrors, `pack` will select a run image
+whose registry location matches that of the specified app image (if no registry host is specified in the image name,
+DockerHub is assumed). This is useful when publishing the resulting app image (via the `--publish` flag or via
+`docker push`), as the app's base image (i.e. run image) will be located on the same registry as the app image itself,
+reducing the amount of data transfer required to push the app image.
+
+In the following example, assuming a builder configured with the example TOML above, the selected run image will be
+`registry.example.com/example/run`.
+
+```bash
+$ pack build registry.example.com/example/app
+```
+
+while naming the app without a registry specified, `example/app`, will cause `example/run` to be selected as the app's
+run image.
+
+```bash
+$ pack build example/app
+```
+
+> For local development, it's often helpful to override the run image mirrors in a builder. For this, the
+> `pack config run-image-mirrors` command can be used. This command does not modify the builder, and instead configures the
+> local environment.
+>
+> To see what run images are configured for a builder, the
+> `builder inspect` command can be used. `builder inspect` will output built-in and locally-configured run images for
+> a given builder, along with other useful information. The order of the run images in the output denotes the order in
+> which they will be matched during `build`.

content/docs/concepts/components/builder.md

@@ -18,8 +18,9 @@ aliases=[
 A builder consists of the following components:
 
 * [Buildpacks][buildpack]
-* [Lifecycle][lifecycle]   
-* [Stack's][stack] build image   
+* A [lifecycle][lifecycle]
+* A [build image](/docs/concepts/components/base-images/build/)
+* A reference to a [run image](/docs/concepts/components/base-images/run/)
 
 ### Resources
 
@@ -29,4 +30,3 @@ To learn how to create your own builder, see our [Operator's Guide][operator-gui
 [operator-guide]: /docs/operator-guide/
 [buildpack]: /docs/concepts/components/buildpack/
 [lifecycle]: /docs/concepts/components/lifecycle/
-[stack]: /docs/concepts/components/stack/

content/docs/concepts/components/stack.md

@@ -8,18 +8,26 @@ aliases=[
 
 ## What is a stack?
 
-A stack is composed of two images that are intended to work together:
+A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID.
 
-1. The **build image** of a stack provides the base image from which the build environment is constructed. The build environment is the containerized environment in which the [lifecycle][lifecycle] (and thereby [buildpacks][buildpack]) are executed.
-2. The **run image** of a stack provides the base image from which application images are built.
+As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.
+
+For more information, see
+* Platform API 0.12 [migration guide](/docs/reference/spec/migration/platform-api-0.11-0.12/)
+* Buildpack API 0.10 [migration guide](/docs/reference/spec/migration/buildpack-api-0.9-0.10/)
+* [Build image](/docs/concepts/components/base-images/build/) concept
+* [Run image](/docs/concepts/components/base-images/run/) concept
+* [Target data](/docs/concepts/components/targets/)
+
+For older API versions, see below on using stacks.
 
 <!--more-->
 
+## Using stacks
+
 > If you're using the `pack` CLI, running `pack stack suggest` will display a list of recommended
 stacks that can be used when running `pack builder create`, along with each stack's associated build and run images.
 
-## Using stacks
-
 Stacks are used by [builders][builder] and are configured through a builder's
 [configuration file](/docs/reference/config/builder-config/):
 
@@ -40,38 +48,6 @@ Stacks are used by [builders][builder] and are configured through a builder's
 By providing the required `[stack]` section, a builder author can configure a stack's ID, build image, and run image
 (including any mirrors).
 
-### Run image mirrors
-
-Run image mirrors provide alternate locations for run images, for use during `build` (or `rebase`).
-When running `build` with a builder containing run image mirrors, `pack` will select a run image
-whose registry location matches that of the specified app image (if no registry host is specified in the image name,
-DockerHub is assumed). This is useful when publishing the resulting app image (via the `--publish` flag or via
-`docker push`), as the app's base image (i.e. run image) will be located on the same registry as the app image itself,
-reducing the amount of data transfer required to push the app image.
-
-In the following example, assuming a builder configured with the example TOML above, the selected run image will be
-`registry.example.com/example/run`.
-
-```bash
-$ pack build registry.example.com/example/app
-```
-
-while naming the app without a registry specified, `example/app`, will cause `example/run` to be selected as the app's
-run image.
-
-```bash
-$ pack build example/app
-```
-
-> For local development, it's often helpful to override the run image mirrors in a builder. For this, the
-> `pack config run-image-mirrors` command can be used. This command does not modify the builder, and instead configures the
-> user's local machine.
->
-> To see what run images are configured for a builder, the
-> `inspect-builder` command can be used. `inspect-builder` will output built-in and locally-configured run images for
-> a given builder, among other useful information. The order of the run images in the output denotes the order in
-> which they will be matched during `build`.
-
 ## Resources
 
 To learn how to create your own stack, see our [Operator's Guide][operator-guide].

content/docs/concepts/components/targets.md

@@ -0,0 +1,28 @@
++++
+title="Targets"
+weight=4
++++
+
+The concept of "targets" is used to identify compatibility between buildpacks and base images.
+
+Target data includes:
+* Operating system name (e.g., "linux")
+* Architecture (e.g., "amd64", "arm64")
+* Architecture variant
+* Operating system distribution name (e.g., "ubuntu", "alpine")
+* Operating system distribution version (e.g., "22.04", "3.18.3")
+
+For Linux-based images, operating system distribution name and version should be the values in `/etc/os-release` (`$ID` and `$VERSION_ID`).
+For Windows-based images, operating system distribution name is blank, and version should be the value of `os.version` in the image config (e.g., `10.0.14393.1066`).
+
+Buildpacks may declare the targets they are compatible with in `buildpack.toml`.
+This information will be used by `pack` (or other platforms) and the lifecycle to avoid running buildpacks on images they aren't designed to work with.
+
+Additionally, during builds this information will be read by the lifecycle from the run image and exposed to buildpacks through `CNB_TARGET_` environment variables:
+* `CNB_TARGET_OS`
+* `CNB_TARGET_ARCH`
+* `CNB_TARGET_ARCH_VARIANT`
+* `CNB_TARGET_DISTRO_NAME`
+* `CNB_TARGET_DISTRO_VERSION`
+
+Buildpacks can use this information to modify their behavior depending on the target.