Skip to content

Commit

Permalink
Clarify stack concepts
Browse files Browse the repository at this point in the history
Previously stack ID requirements including:
* allowed characters
* global uniqueness
were only specified in the buildpack spec, in the buildpack.toml data formt section. This PR moves stack ID description and requirements in the Platform spec with the rest of the stack concepts.

Clarifies stack concepts, incorporating feedback that surfaced in previous PR reviews #87 (comment).

Signed-off-by: Emily Casey <ecasey@vmware.com>
  • Loading branch information
ekcasey committed Oct 16, 2020
1 parent e4575d0 commit ddc2164
Showing 1 changed file with 34 additions and 10 deletions.
44 changes: 34 additions & 10 deletions platform.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,11 @@ Examples of a platform might include:
- [CNB Terminology](#cnb-terminology)
- [Additional Terminology](#additional-terminology)
- [Stacks](#stacks)
- [Compatibility Guarantees](#compatibility-guarantees)
- [Stack ID](#stack-id)
- [Build Image](#build-image)
- [Run Image](#run-image)
- [Mixins](#mixins)
- [Compatibility Guarantees](#compatibility-guarantees)
- [Lifecycle Interface](#lifecycle-interface)
- [Platform API Compatibility](#platform-api-compatibility)
- [Operations](#operations)
Expand Down Expand Up @@ -98,15 +99,17 @@ Platform API versions:
#### CNB Terminology
A **buildpack** refers to software compliant with the [Buildpack Interface Specification](buildpack.md).

A **stack** is a contract defined by a **build image** and a **run image** that are only updated with security patches.
A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**.

A **stack ID** uniquely identifies a particular **stack**.

A **build image** is an OCI image that provides the base of the **build environment**.

A **run image** is an OCI image that provides the base from which **app images** are built.

The **build environment** refers to the containerized environment in which the lifecycle executes buildpacks.
A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract.

A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract.
The **build environment** refers to the containerized environment in which the lifecycle executes buildpacks.

An **app image** refers to an OCI image generated by the lifecycle by extending the **run image** with any or all of the following: **app layers**, **launch layers**, **launcher layers**, image configuration.

Expand All @@ -133,16 +136,26 @@ The following is a non-exhaustive list of terms defined in the [OCI Image Format
* **diffID** - https://github.com/opencontainers/image-spec/blob/master/config.md#layer-diffid

## Stacks
### Compatibility Guarantees

Stack image authors SHOULD ensure that build image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions, although violating this requirement will not change the behavior of previously built images containing app and launch layers.
A typical stack might specify:
* The OS distro in the build environment.
* OS packages installed in the build environment.
* Trusted CA certificates in the build environment.
* The OS distro or distroless OS in the launch environment.
* OS packages installed in the launch environment.
* Trusted CA certificates in the launch environment.
* The default user and the build and launch environments.

Stack image authors MUST ensure that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions.
Stack image authors MUST ensure that app and launch layers do not change behavior when the run image layers are upgraded to newer versions, unless those behavior changes are intended to fix security vulnerabilities.
Stack authors SHOULD define the contract such that any stack images CVEs can be addressed with security patches without violating the [compatibility guarantees](#compatibility-guarantees).

Mixin authors MUST ensure that mixins do not affect the [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) of any object code compiled to run on the base stack images without mixins.
### Stack ID

During build, platforms MUST use the same set of mixins for the run image as were used in the build image (excluding mixins that have a stage specifier).
Stack authors MUST choose a globally unique ID, for example: "io.buildpacks.mystack".

The stack ID:
- MUST NOT be identical to any other stack ID when using a case-insensitive comparison.
- MUST only contain numbers, letters, and the characters `.`, `/`, and `-`.
- SHOULD use reverse domain name notation to avoid name collisions.

### Build Image

Expand Down Expand Up @@ -199,6 +212,17 @@ A platform MAY support any number of mixins for a given stack in order to suppor
Changes introduced by mixins SHOULD be restricted to the addition of operating system software packages that are regularly patched with strictly backwards-compatible security fixes.
However, mixins MAY consist of any changes that follow the [Compatibility Guarantees](#compatibility-guarantees).

### Compatibility Guarantees

Stack image authors SHOULD ensure that build image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions, although violating this requirement will not change the behavior of previously built images containing app and launch layers.

Stack image authors MUST ensure that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions.
Stack image authors MUST ensure that app and launch layers do not change behavior when the run image layers are upgraded to newer versions, unless those behavior changes are intended to fix security vulnerabilities.

Mixin authors MUST ensure that mixins do not affect the [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) of any object code compiled to run on the base stack images without mixins.

During build, platforms MUST use the same set of mixins for the run image as were used in the build image (excluding mixins that have a stage specifier).

## Lifecycle Interface
### Platform API Compatibility

Expand Down

0 comments on commit ddc2164

Please sign in to comment.