From 8d14e68e5beb80ea411cb4bef1f40e00d3438ba3 Mon Sep 17 00:00:00 2001 From: Aidan Delaney Date: Sun, 7 Jun 2026 17:36:21 +0100 Subject: [PATCH 1/2] docs: collapse deprecated stack concept page The stack concept was deprecated in Platform API 0.12 and Buildpack API 0.10 in favour of standard OCI image constructs such as OS, architecture, and distribution. Keeping a full tutorial here misleads app developers into using an outdated workflow. The page is reduced to a deprecation notice with forwarding links to the relevant migration guides and current base-image concepts, and the title is updated to make the deprecation unambiguous in the navigation. A note is also added calling out that `pack stack suggest` is deprecated in favour of `pack builder suggest`. Signed-off-by: Aidan Delaney --- .../concepts/base-images/stack.md | 42 ++----------------- 1 file changed, 4 insertions(+), 38 deletions(-) diff --git a/content/docs/for-app-developers/concepts/base-images/stack.md b/content/docs/for-app-developers/concepts/base-images/stack.md index 4642e0f76..ca5b58095 100644 --- a/content/docs/for-app-developers/concepts/base-images/stack.md +++ b/content/docs/for-app-developers/concepts/base-images/stack.md @@ -1,6 +1,6 @@ +++ -title="Stack" +title="Stack (deprecated)" aliases=[ "/docs/concepts/components/stack", "/docs/using-pack/stacks/" @@ -15,46 +15,12 @@ A stack (deprecated) is the grouping together of the build and run base images, 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/for-platform-operators/how-to/migrate/platform-api-0.11-0.12/) * Buildpack API 0.10 [migration guide](/docs/for-buildpack-authors/how-to/migrate/buildpack-api-0.9-0.10/) * [Build image](/docs/for-app-developers/concepts/base-images/build/) concept * [Run image](/docs/for-app-developers/concepts/base-images/run/) concept * [Target data](/docs/for-buildpack-authors/concepts/targets/) -For older API versions, see below on using stacks. - - - -## 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. - -Stacks are used by [builders][builder] and are configured through a builder's -[configuration file](/docs/reference/config/builder-config/): - -```toml -[[buildpacks]] - # ... - -[[order]] - # ... - -[stack] - id = "com.example.stack" - build-image = "example/build" - run-image = "example/run" - run-image-mirrors = ["gcr.io/example/run", "registry.example.com/example/run"] -``` - -By providing the required `[stack]` section, a builder author can configure a stack's ID, build image, and run image -(including any mirrors). - -## Resources - -To learn how to create your own stack, see our [Operator's Guide][operator-guide]. - -[operator-guide]: /docs/for-platform-operators/ -[builder]: /docs/for-platform-operators/concepts/builder/ -[buildpack]: /docs/for-platform-operators/concepts/buildpack/ -[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/ +> `pack stack suggest` is also deprecated. Use `pack builder suggest` to find +> recommended builders that use current base images. From 87d33620312b2484331ae310b74f248a228bf875 Mon Sep 17 00:00:00 2001 From: Aidan Delaney Date: Sun, 7 Jun 2026 17:44:12 +0100 Subject: [PATCH 2/2] docs: add stack replacement guidance for app devs App developers reading the stack deprecation notice had nowhere to turn for practical guidance on what to do differently. This adds a short section explaining that builder selection is still the right starting point, that run images now carry OS/arch/distro target data instead of a stack ID, and how to use the --platform flag for multi-architecture builds. The rebase behaviour change is also documented so developers understand why a previously-working rebase might now fail. Signed-off-by: Aidan Delaney --- .../config/vocabularies/Buildpacks/accept.txt | 1 + .../concepts/base-images/stack.md | 31 +++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/.github/styles/config/vocabularies/Buildpacks/accept.txt b/.github/styles/config/vocabularies/Buildpacks/accept.txt index ecb1e385c..fd1b070b0 100644 --- a/.github/styles/config/vocabularies/Buildpacks/accept.txt +++ b/.github/styles/config/vocabularies/Buildpacks/accept.txt @@ -6,6 +6,7 @@ buildpackage bundler CLI [Cc]loud +cnbs CNB containerd CycloneDX diff --git a/content/docs/for-app-developers/concepts/base-images/stack.md b/content/docs/for-app-developers/concepts/base-images/stack.md index ca5b58095..fe3c88164 100644 --- a/content/docs/for-app-developers/concepts/base-images/stack.md +++ b/content/docs/for-app-developers/concepts/base-images/stack.md @@ -24,3 +24,34 @@ For more information, see > `pack stack suggest` is also deprecated. Use `pack builder suggest` to find > recommended builders that use current base images. + +## What replaces stacks for app developers? + +As an app developer you never needed to specify a stack ID directly; the builder you chose implied a stack. That relationship still holds: choose a builder and the run image it provides determines your app's base environment. The difference is that run images are now described by standard OCI properties (OS, architecture, and Linux distribution) rather than an opaque stack ID. + +### Choosing a builder + +Use `pack builder suggest` for a list of recommended builders, or `pack builder inspect` to examine a specific builder. The **Run Images** section shows the run image your app image will be based on: + +```text +$ pack builder inspect cnbs/sample-builder:alpine + +Run Images: + cnbs/sample-base-run:alpine +``` + +The run image tag identifies the OS distribution the builder targets. `cnbs/sample-base-run:alpine` is an Alpine Linux image; the sample builder declares both `linux/amd64` and `linux/arm64` as supported targets. + +### Building for a specific architecture + +When a builder supports multiple architectures, `pack` defaults to the architecture of the host machine. To target a different architecture explicitly, use the `--platform` flag: + +```bash +pack build my-app --builder cnbs/sample-builder:alpine --platform linux/arm64 +``` + +See the [Linux ARM build guide](/docs/for-app-developers/how-to/special-cases/build-for-arm/) for a worked example. + +### Rebasing + +Rebasing an app image used to require that the old and new run images shared the same stack ID. It now requires that they share the same OS, architecture, and Linux distribution. This is enforced automatically by `pack rebase`; no action is needed on your part unless a rebase that previously succeeded now fails, in which case the run images are genuinely incompatible targets.