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 4642e0f76..fe3c88164 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,43 @@ 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. - - +> `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. -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: -[[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. + +### 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. -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.