buildpacks · joe-kimmel-vmw · Apr 4, 2023 · Apr 8, 2023 · Apr 8, 2023 · Apr 8, 2023
@@ -6,7 +6,47 @@ aliases=[
 ]
 +++
 
-## What is a stack?
+## What is a stack and Why is it deprecated?
+
+### Deprecation
+A stack restricts buildpacks to run on top of a set of related **build images** (where your app is built)
+and **run images** (where your app runs).  Practical experience of the buildpacks community has not found that the stack concept adds any value therefore [the community decided](https://github.com/buildpacks/rfcs/blob/main/text/0096-remove-stacks-mixins.md)
+to use buildpacks with build and run images without the additional concept formerly known as _stack_. 
+
+Stacks will continue to be supported with full backwards compatibility.
+
+### What's Next?
+[Targets](https://github.com/buildpacks/rfcs/blob/main/text/0096-remove-stacks-mixins.md#example-buildpacktoml-targets-table) replace stacks.
+Targets allow buildpack authors to directly specify details such as OS and architecture directly without the intermediate object known as a "stack".
+Targets are available starting with the 0.12 Platform API but should be safely ignored by older platforms.
+
+
+#### How long can I keep using stacks?
+We do not yet have a defined end-date. Historically this project allows deprecated features to remain for 6-24+ months.
+
+
+#### What is the current recommended best practice?
+We currently recommend that buildpack authors use both a stack and a target.
+We anticipate it will take some time before all platforms catch up with this change, but by using both your buildpacks will work with all platforms past, present, and future.
+
+In order to ease this process for those using the io.buildpacks.stacks.bionic, lifecycle will translate any section that sets this as on of the stacks:
+
+```
+[[stacks]]
+id = "io.buildpacks.stacks.bionic"
+```
+
+to
+```
+[[targets]]
+os = "linux"
+arch = "amd64"
+[[targets.distributions]]
+name = "ubuntu"
+versions = ["18.04"]
+```
+
+## (Deprecated) stack documentation
 
 A stack is composed of two images that are intended to work together:
 

@@ -0,0 +1,26 @@
++++
+title="Targets"
+weight=4
+aliases=[
+    "/docs/using-pack/targets/"
+]
++++
+
+## What is a Target?
+
+A target is the essential information about an operating system and architecture necessary to ensure that binaries will be placed in environments where they can execute successfully.
+A buildpack may specify one or several targets. A build image or run image must specific one target. 
+
+
+For full documentation see the (RFC where targets are introduced)[https://github.com/buildpacks/rfcs/blob/main/text/0096-remove-stacks-mixins.md].
+
+### Example
+```
+[[targets]]
+os = "linux"
+arch = "amd64"
+[[targets.distributions]]
+name = "ubuntu"
+versions = ["18.04", "20.04"]
+```
+
@@ -97,10 +97,10 @@ For additional sample builders and buildpacks, check out our [samples][samples]
 
 You can also check out our reference of the builder config [here][builder-config].
 
-If you would like to customize the stack used by your builder, check out our [Create a stack][create-a-stack] tutorial.
+If you would like to customize the image your builder builds in, check out our [Create custom build and run images][create-targets] tutorial.
 
 [build]: /docs/concepts/operations/build/
 [builder]: /docs/concepts/components/builder/
 [builder-config]: /docs/reference/builder-config/
-[create-a-stack]: /docs/operator-guide/create-a-stack
+[create-targets]: /docs/operator-guide/create-targets
 [samples]: https://github.com/buildpacks/samples
@@ -1,9 +1,9 @@
 +++
-title="Create a stack"
+title="Create Target Images"
 weight=2
 +++
 
-Creating a custom [stack][stack] allows you to configure the base images for the build-time environment for your [builder][builder] and the run-time for your application.
+Creating a custom Build and Run images allows you to configure the base images for the build-time environment for your [builder][builder] and the run-time for your application.
 
 <!--more-->
 
@@ -13,55 +13,52 @@ Before we get started, make sure you've got the following installed:
 
 {{< download-button href="https://store.docker.com/search?type=edition&offering=community" color="blue" >}} Install Docker {{</>}}
 
+## Creating custom images
 
-## Creating a custom stack
-
-In this tutorial we will create a sample stack based on `Ubuntu Bionic`. To create a custom stack, we need to create customized build and run images. Let's see how we can do so!
-
+In this tutorial we will create sample build and run images based on `Ubuntu Jammy`.
 
 ### Create a common base image
 
-Let's start by creating a base image containing layers that will be required by both the `build` and `run` images. In order to do this, switch to a clean workspace and create a `Dockerfile` as specified below:
+Let's start by creating a base image containing layers that will be required both the `build` and `run` images.
+In order to do this, switch to a clean workspace and create a `Dockerfile` as specified below:
 
 #### Defining the base
-We start with `ubuntu:jammy` as our `base` image. Since we will be reusing these layers in both our build and run images we will be defining a common base image and leveraging [Docker's multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) to ensure this acts as the common base image for both our build-time and run-time environment.
+We start with `ubuntu:jammy` as our `base` image, and we hope you like jammy too!
+Since we will be reusing these layers in both our build and run images we will be defining a common base image and leveraging [Docker's multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) to ensure this acts as the common base image for both our build-time and run-time environment.
 
 ```Dockerfile
 # 1. Set a common base
 FROM ubuntu:jammy as base
 ```
 
+
 #### Set required CNB information
 
-Next, we will be setting up the base image as required by the [Cloud-Native Buildpack specification][stack-spec] noted below.
+Next, we will be setting up the base image as required by the [Cloud-Native Buildpack specification](https://github.com/buildpacks/spec/blob/main/platform.md).
 
 ##### Specification
 
-**Labels**
-
-| Name                     | Description              | Format |
-| ------------------------ | ------------------------ | ------ |
-| `io.buildpacks.stack.id` | Identifier for the stack | String |
+The image's config's `os` and `architecture` should be set ot valid values according to the
+[OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) with the addition of wildcards: 
+Buildpack images may have their architecture set to `*` to indicate "any" - e.g. a shell script that is expected to succeed in any architecture could specify `*`. 
+Similarly 
 
 **Environment Variables**
 
 | Name           | Description                            |
 | -------------- | -------------------------------------- |
-| `CNB_STACK_ID` | Identifier for the stack               |
 | `CNB_USER_ID`  | UID of the user specified in the image |
 | `CNB_GROUP_ID` | GID of the user specified in the image |
 <p class="spacer"></p>
 
-> **NOTE:** The **stack identifier** implies compatibility with other stacks of that same identifier. For instance, a custom stack may use
-> `io.buildpacks.stacks.jammy` as its identifier so long as it will work with buildpacks that declare compatibility with the
-> `io.buildpacks.stacks.jammy` stack.
 
 
 The `CNB_USER_ID` is the `UID`  of the user as which the `detect` and `build` steps are run. The given user **MUST NOT** be a root user
 and have it's home directly writable. `CNB_GROUP_ID` is the primary `GID` of the above user.
 
 Let's update the `Dockerfile` to reflect the above specification.
 
+
 ```Dockerfile
 # 1. Set a common base
 FROM ubuntu:jammy as base
@@ -70,8 +67,6 @@ FROM ubuntu:jammy as base
 # 2. Set required CNB information
 ENV CNB_USER_ID=1000
 ENV CNB_GROUP_ID=1000
-ENV CNB_STACK_ID="io.buildpacks.samples.stacks.jammy"
-LABEL io.buildpacks.stack.id="io.buildpacks.samples.stacks.jammy"
 
 # 3. Create the user
 RUN groupadd cnb --gid ${CNB_GROUP_ID} && \
@@ -84,13 +79,13 @@ Next up, we will be installing any system packages that we want to make availabl
 
 ```Dockerfile
 # 1. Set a common base
-FROM ubuntu:jammy as base
+FROM ubuntu:bionic as base
 
 # 2. Set required CNB information
 ENV CNB_USER_ID=1000
 ENV CNB_GROUP_ID=1000
-ENV CNB_STACK_ID="io.buildpacks.samples.stacks.jammy"
-LABEL io.buildpacks.stack.id="io.buildpacks.samples.stacks.jammy"
+ENV CNB_STACK_ID="io.buildpacks.samples.stacks.bionic"
+LABEL io.buildpacks.stack.id="io.buildpacks.samples.stacks.bionic"
 
 # 3. Create the user
 RUN groupadd cnb --gid ${CNB_GROUP_ID} && \
@@ -123,8 +118,6 @@ FROM ubuntu:jammy as base
 # 2. Set required CNB information
 ENV CNB_USER_ID=1000
 ENV CNB_GROUP_ID=1000
-ENV CNB_STACK_ID="io.buildpacks.samples.stacks.jammy"
-LABEL io.buildpacks.stack.id="io.buildpacks.samples.stacks.jammy"
 
 # 3. Create the user
 RUN groupadd cnb --gid ${CNB_GROUP_ID} && \
@@ -146,7 +139,7 @@ USER ${CNB_USER_ID}:${CNB_GROUP_ID}
 That should be it for our run image! Let's verify that we can successfully build this image by running:
 
 ```bash
-docker build . -t cnbs/sample-stack-run:jammy --target run
+docker build . -t cnbs/sample-run:jammy --target run
 ```
 
 ### Creating the build image
@@ -166,8 +159,6 @@ FROM ubuntu:jammy as base
 # 2. Set required CNB information
 ENV CNB_USER_ID=1000
 ENV CNB_GROUP_ID=1000
-ENV CNB_STACK_ID="io.buildpacks.samples.stacks.jammy"
-LABEL io.buildpacks.stack.id="io.buildpacks.samples.stacks.jammy"
 
 # 3. Create the user
 RUN groupadd cnb --gid ${CNB_GROUP_ID} && \
@@ -207,8 +198,6 @@ FROM ubuntu:jammy as base
 # 2. Set required CNB information
 ENV CNB_USER_ID=1000
 ENV CNB_GROUP_ID=1000
-ENV CNB_STACK_ID="io.buildpacks.samples.stacks.jammy"
-LABEL io.buildpacks.stack.id="io.buildpacks.samples.stacks.jammy"
 
 # 3. Create the user
 RUN groupadd cnb --gid ${CNB_GROUP_ID} && \
@@ -243,70 +232,21 @@ USER ${CNB_USER_ID}:${CNB_GROUP_ID}
 That should be it for our build image! Let's verify that we can successfully build this image by running:
 
 ```bash
-docker build . -t cnbs/sample-stack-build:jammy --target build
+docker build . -t cnbs/sample-build:jammy --target build
 ```
 
-**Congratulations!** You've got a custom stack!
-
-
-## Additional information
-
-### Mixins
-
-Mixins provide a way to document OS-level dependencies that a stack provides to buildpacks. Mixins can be provided at build-time
-(name prefixed with `build:`), run-time (name prefixed with `run:`), or both (name unprefixed).
-
-#### Declaring provided mixins
 
-When declaring provided mixins, both the build and run image of a stack must contain the following label:
 
-| Name                         | Description             | Format            |
-| ---------------------------- | ----------------------- | ----------------- |
-| `io.buildpacks.stack.mixins` | List of provided mixins | JSON string array |
+**Congratulations!** You've got custom build and run images!
 
-\
-The following rules apply for mixin declarations:
 
- - `build:`-prefixed mixins may not be declared on a run image
- - `run:`-prefixed mixins may not be declared on a build image
- - Unprefixed mixins must be declared on both stack images
 
-##### Example
+## Resources and Additional Information
 
-_Build image:_
-```json
-io.buildpacks.stack.mixins: ["build:git", "wget"]
-```
-
-_Run image:_
-```json
-io.buildpacks.stack.mixins: ["run:imagemagick", "wget"]
-```
-
-#### Declaring required mixins
-
-A buildpack must list any required mixins in the `stacks` section of its `buildpack.toml` file.
-
-When validating whether the buildpack's mixins are satisfied by a stack, the following rules apply:
-
-- `build:`-prefixed mixins must be provided by stack's build image
-- `run:`-prefixed mixins must be provided by stack's run image
-- Unprefixed mixins must be provided by both stack images
-
-##### Example
-
-```toml
-[[stacks]]
-id = "io.buildpacks.stacks.jammy"
-mixins = ["build:git", "run:imagemagick", "wget"]
-```
+**Image Extensions** provide a way to add functionality that could be shared by multiple base images. see:
 
-## Resources
+[Image Extension Spec](https://github.com/buildpacks/spec/blob/main/image_extension.md) and [Extension Author Guide](https://buildpacks.io/docs/extension-author-guide/)
 
-For sample stacks, see our [samples][samples] repo.
-For technical details on stacks, see the [platform specification for stacks][stack-spec].
 
-[stack]: /docs/concepts/components/stack/
 [builder]: /docs/concepts/components/builder/
 [samples]: https://github.com/buildpacks/samples
-[stack-spec]: https://github.com/buildpacks/spec/blob/main/platform.md#stacks