From ddc216401edc2d730cbf3a41da7c0fa395a20624 Mon Sep 17 00:00:00 2001 From: Emily Casey Date: Fri, 16 Oct 2020 10:18:41 -0400 Subject: [PATCH] Clarify stack concepts 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 https://github.com/buildpacks/spec/pull/87#discussion_r450534541. Signed-off-by: Emily Casey --- platform.md | 44 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/platform.md b/platform.md index 161778e6..7482958c 100644 --- a/platform.md +++ b/platform.md @@ -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) @@ -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. @@ -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 @@ -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