From 7d27d005ac4260567935ab771acc0f7c668cfbe3 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 6 Mar 2024 12:22:01 -0500 Subject: [PATCH] Break up Platform API section into separate "how to" pages Signed-off-by: Natalie Arellano --- .../how-to/design-platform/_index.md | 5 ++++ .../design-platform/prepare-filesystem.md | 16 ++++++++++++ content/docs/reference/spec/platform-api.md | 26 +++++++++---------- 3 files changed, 33 insertions(+), 14 deletions(-) create mode 100644 content/docs/for-platform-operators/how-to/design-platform/_index.md create mode 100644 content/docs/for-platform-operators/how-to/design-platform/prepare-filesystem.md diff --git a/content/docs/for-platform-operators/how-to/design-platform/_index.md b/content/docs/for-platform-operators/how-to/design-platform/_index.md new file mode 100644 index 000000000..7f43260f7 --- /dev/null +++ b/content/docs/for-platform-operators/how-to/design-platform/_index.md @@ -0,0 +1,5 @@ ++++ +title="Design your own platform" +weight=3 +include_summaries=true ++++ diff --git a/content/docs/for-platform-operators/how-to/design-platform/prepare-filesystem.md b/content/docs/for-platform-operators/how-to/design-platform/prepare-filesystem.md new file mode 100644 index 000000000..57fe78b1b --- /dev/null +++ b/content/docs/for-platform-operators/how-to/design-platform/prepare-filesystem.md @@ -0,0 +1,16 @@ ++++ +title="Prepare the filesystem" +weight=99 ++++ + +This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon. + +If you are familiar with this content and would like to make a contribution, please feel free to open a PR :) + +To cover: + +* Buildpacks are stored on the filesystem as unarchived files such that: + * Each top-level directory is a buildpack ID. + * Each second-level directory is a buildpack version. +* Mount points +* Users diff --git a/content/docs/reference/spec/platform-api.md b/content/docs/reference/spec/platform-api.md index cf974aa48..02f0a2ced 100644 --- a/content/docs/reference/spec/platform-api.md +++ b/content/docs/reference/spec/platform-api.md @@ -5,27 +5,25 @@ aliases=[ ] +++ -The Platform specification defines the interface between the CNB [lifecycle](/docs/for-platform-operators/concepts/lifecycle/) and a [platform](/docs/for-app-developers/concepts/platform/) that runs it. +The Platform API specifies the interface between a [lifecycle] program +and a [platform] that runs it. -## Buildpacks +## API Compatibility -Buildpacks are stored on the filesystem as unarchived files such that: +A [platform] may implement more than one Platform API version at a time, although it is not required to do so. +Platforms can control the Platform API version expected by the lifecycle by setting the `CNB_PLATFORM_API` environment variable. -* Each top-level directory is a buildpack ID. -* Each second-level directory is a buildpack version. +A [lifecycle] may (and usually does) support more than one Platform API version at a time. +The supported Platform API version(s) can be found in the `lifecycle.toml` file in a lifecycle tarball, +or in a label on the [lifecycle image](https://hub.docker.com/r/buildpacksio/lifecycle). -## Users - -For security reasons, images built with platforms, such as `pack`, build and run as non-root users. - -## Stacks (deprecated) - -A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID. - -The build image is used to run the buildpack lifecycle, and the run image is the base image for the application image. +A lifecycle "supports" a platform (and vice versa) if they both declare support for the same Platform API version in format: `.`. ## Further Reading You can read the complete [Platform API specification on Github](https://github.com/buildpacks/spec/blob/main/platform.md). + +[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/ +[platform]: /docs/for-app-developers/concepts/platform/