-
Notifications
You must be signed in to change notification settings - Fork 70
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.
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
Add terminology section to the buildpack spec #300
Changes from all commits
ad46084
7578a07
ff54426
2af7150
b34152e
8e70e24
b75f220
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,17 +2,6 @@ | |
|
||
This document specifies the interface between a lifecycle program and one or more buildpacks. | ||
|
||
The lifecycle program uses buildpacks to build software artifacts from source code and pack the result into an OCI image. | ||
|
||
This is accomplished in four phases: | ||
|
||
1. **Detection,** where an optimal selection of compatible buildpacks is chosen. | ||
2. **Analysis,** where metadata about OCI layers generated during a previous build are made available to buildpacks. | ||
3. **Build,** where buildpacks use that metadata to generate only the OCI layers that need to be replaced. | ||
4. **Export,** where the remote layers are replaced by the generated layers. | ||
|
||
The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle that executes during the **Launch** phase. | ||
|
||
## Table of Contents | ||
|
||
<!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc --> | ||
|
@@ -75,30 +64,76 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th | |
- [Buildpack Plan (TOML)](#buildpack-plan-toml) | ||
- [Layer Content Metadata (TOML)](#layer-content-metadata-toml) | ||
- [buildpack.toml (TOML)](#buildpacktoml-toml) | ||
- [Buildpack Implementations](#buildpack-implementations) | ||
- [Order Buildpacks](#order-buildpacks) | ||
- [Stacks](#stacks) | ||
- [Order](#order) | ||
- [Exec.d Output (TOML)](#execd-output-toml) | ||
- [Deprecations](#deprecations) | ||
- [`0.3`](#03) | ||
- [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key) | ||
|
||
## Buildpack API Version | ||
This document specifies Buildpack API version `0.8` | ||
This document specifies Buildpack API version `0.9` | ||
|
||
Buildpack API versions: | ||
- MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0` | ||
- `<major>` and `<minor>` MUST only contain numbers (unsigned 64 bit integer) | ||
- When `<major>` is greater than `0` increments to `<minor>` SHALL exclusively indicate additive changes | ||
|
||
## Terminology | ||
|
||
### CNB Terminology | ||
|
||
A **buildpack** is a directory containing a `buildpack.toml`. A buildpack analyzes application source code and determines the best way to build it. | ||
|
||
A **buildpack group**, or **group**, is a list of one or more buildpacks that are designed to work together - for example, a buildpack that provides `node` and a buildpack that provides `npm`. | ||
|
||
An **order** is a list of one or more groups to be tested against application source code, so that the appropriate group for a build can be determined. | ||
|
||
A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables. Component buildpacks implement the [Buildpack Interface](#buildpack-interface). | ||
|
||
A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables. They MUST be [resolvable](#order-resolution) into a collection of component buildpacks. | ||
|
||
**Resolving an order** is the process by which an order (which may contain composite buildpacks) is evaluated together with application source code to produce a group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each component buildpack is invoked. | ||
|
||
An **optional buildpack** is a buildpack (either component or composite) that, when failing detection, will be excluded from the group without causing the entire group to fail. | ||
|
||
A **build plan** is a file used during detection, in which each component buildpack may express the dependencies that it requires and the dependencies that it provides. A group of component buildpacks will only pass detection if a valid build plan can be produced from the dependencies that all component buildpacks in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each component buildpack will have its required dependencies provided by a component buildpack that runs before it. | ||
|
||
A **buildpack plan** is a file unique to each component buildpack, used during the build phase to communicate the dependencies that the component buildpack is expected to provide. | ||
|
||
A **lifecycle** is software that orchestrates a build. It executes in a series of phases that each have a distinct responsibility. | ||
|
||
A **launcher** is an executable that is the `ENTRYPOINT` of the exported OCI image. It is used to start processes at runtime. Having a launcher enables multiple process types to be defined on an image, with process-specific environment variables and other functionality. | ||
|
||
**Launch** describes the process of running an application by creating a container from the exported OCI image. | ||
|
||
A **platform** is a system or software that orchestrates the lifecycle by invoking each lifecycle phase in order. | ||
|
||
A **process definition** is a description, provided by component buildpacks during the build phase, of a process to launch at runtime. | ||
|
||
An **application directory** is a directory containing application source code. Component buildpacks may make changes to the application directory during the build phase. | ||
|
||
A **layer** is a set of filesystem changes packaged according to the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/layer.md). | ||
|
||
A **layer directory** is a directory created by a component buildpack that contains build and/or runtime dependencies, and can be used to configure the build and/or runtime environment. There are three **layer types**: | ||
* a **launch layer** is added as a layer in the exported OCI image; it can be re-used on the next build (the lifecycle can avoid re-uploading it) if the component buildpack that created the layer has the same requirements on the next build | ||
* a **cache layer** is saved to the cache and its contents may be restored on the next build | ||
* a **build layer** contains child directories with paths that are added to the environment (e.g., `PATH`, `LD_LIBRARY_PATH`, etc.) for subsequent buildpacks in the same build | ||
Any combination of the three layer types are valid for a particular layer directory. | ||
|
||
A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to component buildpacks through the `CNB_STACK_ID` environment variable, enabling each component buildpack to modify its behavior when executed on different stacks. | ||
|
||
A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract. Buildpacks can express their required mixins in `buildpack.toml`. | ||
|
||
## Buildpack Interface | ||
|
||
The following specifies the interface implemented by executables in each buildpack. | ||
The lifecycle MUST invoke these executables as described in the Phase sections. | ||
The following specifies the interface implemented by component buildpacks. | ||
The lifecycle MUST invoke executables in component buildpacks as described in the Phase sections. | ||
|
||
### Buildpack API Compatibility | ||
Given a buildpack declaring `<buildpack API Version>` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle: | ||
- MUST either conform to the matching version of this specification when interfacing with the buildpack or | ||
- return an error to the platform if it does not support `<buildpack API Version>` | ||
- MUST return an error to the platform if it does not support `<buildpack API Version>` | ||
|
||
The lifecycle MAY return an error to the platform if two or more buildpacks within a group declare buildpack API versions that the lifecycle cannot support together within a single build, even if both are supported independently. | ||
|
||
|
@@ -134,7 +169,6 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>` | |
| Standard error | Logs (warnings, errors) | | ||
| `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML) | | ||
|
||
|
||
### Build | ||
|
||
Executable: `/bin/build`, Working Dir: `<app[AI]>` | ||
|
@@ -306,13 +340,13 @@ At the end of each individual buildpack's build phase: | |
|
||
### Purpose | ||
|
||
The purpose of detection is to find an ordered group of buildpacks to use during the build phase. | ||
The purpose of detection is to find an ordered group of component buildpacks to use during the build phase. | ||
These buildpacks must be compatible with the app. | ||
|
||
### Process | ||
|
||
**GIVEN:** | ||
- An ordered list of buildpack groups resolved into buildpack implementations as described in [Order Resolution](#order-resolution) | ||
- An ordered list of buildpack groups resolved into component buildpacks as described in [Order Resolution](#order-resolution) | ||
- A directory containing application source code | ||
- A shell, if needed, | ||
|
||
|
@@ -378,13 +412,13 @@ A buildpack's mixin requirements must be satisfied by the stack in one of the fo | |
|
||
#### Order Resolution | ||
|
||
During detection, an order definition MUST be resolved into individual buildpack implementations. | ||
During detection, an order definition MUST be resolved into individual component buildpacks. | ||
|
||
The resolution process MUST follow this pattern: | ||
|
||
Where: | ||
- O and P are buildpack orders. | ||
- A through H are buildpack implementations. | ||
- A through H are component buildpacks. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think this is correct. But I'm a bit less sure of myself here. |
||
|
||
Given: | ||
|
||
|
@@ -438,7 +472,7 @@ If a buildpack order entry within a group has the parameter `optional = true`, t | |
|
||
### Purpose | ||
|
||
The purpose of analysis is to restore `<layers>/<layer>.toml`, `<layers>/<layer>.sbom.<ext>`, and `<layers>/store.toml` files that buildpacks may use to optimize the build and export phases. | ||
The purpose of analysis is to restore `<layers>/<layer>.toml`, `<layers>/<layer>.sbom.<ext>`, and `<layers>/store.toml` files that component buildpacks may use to optimize the build and export phases. | ||
|
||
### Process | ||
|
||
|
@@ -467,9 +501,9 @@ After analysis, the lifecycle MUST proceed to the build phase. | |
|
||
### Purpose | ||
|
||
The purpose of build is to transform application source code into runnable artifacts that can be packaged into a container. | ||
The purpose of build is to transform application source code into runnable artifacts that can be packaged into a container image. | ||
|
||
During the build phase, typical buildpacks might: | ||
During the build phase, typical component buildpacks might: | ||
|
||
1. Read the Buildpack Plan in `<plan>` to determine what dependencies to provide. | ||
1. Provide the application with dependencies for launch in `<layers>/<layer>`. | ||
|
@@ -901,7 +935,7 @@ working-dir = "<working directory>" | |
paths = ["<app sub-path glob>"] | ||
``` | ||
|
||
The buildpack MAY specify any number of labels, processes, or slices. | ||
The component buildpack MAY specify any number of labels, processes, or slices. | ||
|
||
For each label, the buildpack: | ||
|
||
|
@@ -950,7 +984,7 @@ The lifecycle MUST include all unmatched files in the app directory in any numbe | |
name = "<dependency name>" | ||
``` | ||
|
||
For each unmet entry in the Buildpack Plan, the buildpack: | ||
For each unmet entry in the Buildpack Plan, the component buildpack: | ||
- SHOULD add an entry to `unmet`. | ||
|
||
For each entry in `unmet`: | ||
|
@@ -1015,7 +1049,6 @@ For a given layer, the buildpack MAY specify: | |
- Whether the layer is cached, intended for build, and/or intended for launch. | ||
- Metadata that describes the layer contents. | ||
|
||
|
||
### buildpack.toml (TOML) | ||
This section describes the 'Buildpack descriptor'. | ||
|
||
|
@@ -1085,9 +1118,9 @@ The `[[buildpack.licenses]]` table is optional and MAY contain a list of buildpa | |
*Key: `sbom-formats = [ "<string>" ]`* | ||
- MUST be supported SBOM media types as described in [Software-Bill-of-Materials](#software-bill-of-materials). | ||
|
||
#### Buildpack Implementations | ||
#### Stacks | ||
|
||
A buildpack descriptor that specifies `stacks` MUST describe a buildpack that implements the [Buildpack Interface](#buildpack-interface). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't really know what the latter half of this sentence is for |
||
A buildpack descriptor may specify `stacks`. | ||
|
||
Each stack in `stacks` either: | ||
- MUST identify a compatible stack: | ||
|
@@ -1097,9 +1130,7 @@ Each stack in `stacks` either: | |
- `id` MUST be set to the special value `"*"`. | ||
- `mixins` MUST be empty. | ||
|
||
#### Order Buildpacks | ||
|
||
A buildpack descriptor that specifies `order` MUST be [resolvable](#order-resolution) into an ordering of buildpacks that implement the [Buildpack Interface](#buildpack-interface). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Moved to terminology |
||
#### Order | ||
|
||
A buildpack reference inside of a `group` MUST contain an `id` and `version`. | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Feedback from 4/21 Working Group: (if possible, without making each term its own section) we should link back to this section as much as is practical.