Skip to content

docs: collapse dperecated stack concept page #943

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AidanDelaney wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: collapse dperecated stack concept page #943

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d14e68
docs: collapse deprecated stack concept page
AidanDelaney Jun 7, 2026
87d3362
docs: add stack replacement guidance for app devs
AidanDelaney Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/styles/config/vocabularies/Buildpacks/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ buildpackage
bundler
CLI
[Cc]loud
cnbs
CNB
containerd
CycloneDX
Expand Down
51 changes: 24 additions & 27 deletions content/docs/for-app-developers/concepts/base-images/stack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

+++
title="Stack"
title="Stack (deprecated)"

Check warning on line 3 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 3, "column": 14}}}, "severity": "INFO"}
aliases=[
"/docs/concepts/components/stack",
"/docs/using-pack/stacks/"
Expand All @@ -15,46 +15,43 @@
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.

<!--more-->
> `pack stack suggest` is also deprecated. Use `pack builder suggest` to find
> recommended builders that use current base images.

## Using stacks
## What replaces stacks for app developers?

> 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.
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.

Check warning on line 30 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 30, "column": 306}}}, "severity": "INFO"}

Check warning on line 30 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Semicolons] Use semicolons judiciously.

Raw Output:
{"message": "[Google.Semicolons] Use semicolons judiciously.", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 30, "column": 68}}}, "severity": "INFO"}

Stacks are used by [builders][builder] and are configured through a builder's
[configuration file](/docs/reference/config/builder-config/):
### Choosing a builder

```toml
[[buildpacks]]
# ...
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:

Check warning on line 34 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('be based').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('be based').", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 34, "column": 188}}}, "severity": "INFO"}

Check warning on line 34 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Will] Avoid using 'will'.

Raw Output:
{"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 34, "column": 183}}}, "severity": "WARNING"}

[[order]]
# ...
```text
$ pack builder inspect cnbs/sample-builder:alpine

[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"]
Run Images:
cnbs/sample-base-run:alpine
```

By providing the required `[stack]` section, a builder author can configure a stack's ID, build image, and run image
(including any mirrors).
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.

Check warning on line 43 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Semicolons] Use semicolons judiciously.

Raw Output:
{"message": "[Google.Semicolons] Use semicolons judiciously.", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 43, "column": 125}}}, "severity": "INFO"}

### 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
```

## Resources
See the [Linux ARM build guide](/docs/for-app-developers/how-to/special-cases/build-for-arm/) for a worked example.

Check warning on line 53 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'ARM', if it's unfamiliar to the audience.

Raw Output:
{"message": "[Google.Acronyms] Spell out 'ARM', if it's unfamiliar to the audience.", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 53, "column": 16}}}, "severity": "INFO"}

To learn how to create your own stack, see our [Operator's Guide][operator-guide].
### Rebasing

[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/
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.

Check warning on line 57 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('is needed').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('is needed').", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 57, "column": 239}}}, "severity": "INFO"}

Check warning on line 57 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Semicolons] Use semicolons judiciously.

Raw Output:
{"message": "[Google.Semicolons] Use semicolons judiciously.", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 57, "column": 227}}}, "severity": "INFO"}

Check warning on line 57 in content/docs/for-app-developers/concepts/base-images/stack.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('is enforced').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('is enforced').", "location": {"path": "content/docs/for-app-developers/concepts/base-images/stack.md", "range": {"start": {"line": 57, "column": 185}}}, "severity": "INFO"}
Loading