From 58f3f23331ada609b22aa2c93c8e97d8a00fb6d3 Mon Sep 17 00:00:00 2001 From: Ryan Moran Date: Mon, 4 Apr 2022 11:26:06 -0400 Subject: [PATCH] Adds stack descriptor RFC --- text/stacks/0003-stack-descriptor.md | 128 +++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 text/stacks/0003-stack-descriptor.md diff --git a/text/stacks/0003-stack-descriptor.md b/text/stacks/0003-stack-descriptor.md new file mode 100644 index 00000000..dd1a3156 --- /dev/null +++ b/text/stacks/0003-stack-descriptor.md @@ -0,0 +1,128 @@ +# Stack Descriptor and Tooling + +## Summary + +The stack-building codebase, +[`create-stack`](https://github.com/paketo-buildpacks/stacks/tree/main/create-stack) +should be moved into the `jam` tooling CLI, and allow users to configure their +stack build via a common configuration file. + +## Motivation + +Today, `create-stack` is highly coupled to the `bionic` stacks we currently +support. This makes it difficult to support alternative stacks and platforms or +to allow the codebase to be reused by external parties for developing their own +stack. + +## Detailed Explanation + +The `create-stack` codebase will be refactored to allow users to build stacks +using a configuration file with the following format: + +```toml +id = "" # required +homepage = "" # optional +maintainer = "" # optional + +platforms = ["linux/amd64", "linux/arm64", ""] # optional; default = ["linux/amd64"]; choices defined in https://docs.docker.com/desktop/multi-arch/ + +[metadata] + example-key = "" + +[build] + dockerfile = "" # required + description = "" # optional + + uid = 1001 # required + gid = 1000 # required + shell = "" # optional; default = "/sbin/nologin" + + [build.args] # optional + example-arg = "" + +[run] + dockerfile = "" # required + description = "" # optional + + uid = 1002 # required + gid = 1000 # required + shell = "" # optional; default = "/sbin/nologin" + + [run.args] # optional + example-arg = "" + +[deprecated] + legacy-sbom = true # optional; default = false; enables https://github.com/paketo-buildpacks/rfcs/blob/main/text/stacks/0001-stack-package-metadata.md + mixins = true # optional; default = false; enables the inclusion of the `io.buildpacks.stack.mixins` label +``` + +### Stack Spec Requirements + +The Cloud-Native Buildpacks Platform Specification outlines a number of +environment variables and labels that must or should be attached to a stack +image. These values will be populated as outlined below: + +#### Environment Variables + +* `CNB_STACK_ID`: from the `id` field in the Stack Descriptor +* `CNB_USER_ID`: from the `build.uid` field in the Stack Descriptor +* `CNB_GROUP_ID`: from the `build.gid` field in the Stack Descriptor + +#### Labels + +* `io.buildpacks.stack.id`: from the `id` field in the Stack Descriptor +* `io.buildpacks.stack.mixins`: set to an empty JSON array (`[]`) +* `io.buildpacks.stack.maintainer`: from the `maintainer` field in the Stack Descriptor +* `io.buildpacks.stack.homepage`: from the `homepage` field in the Stack Descriptor +* `io.buildpacks.stack.distro.name`: from the `ID` field in the `/etc/os-release` field from the image generated from the Dockerfile located at the `{build,run}.dockerfile` paths in the Stack Descriptor +* `io.buildpacks.stack.distro.version`: from the `VERSION_ID` field in the `/etc/os-release` field from the image generated from the Dockerfile located at the `{build,run}.dockerfile` paths in the Stack Descriptor +* `io.buildpacks.stack.released`: dynamically generated by the `create-stack` command, not configurable +* `io.buildpacks.stack.description`: from the `{build,run}.description` fields in the Stack Descriptor +* `io.buildpacks.stack.metadata`: from the `metadata` field in the Stack Descriptor, defaults to `{}` + +### Toolchain + +A refactored version of the existing `create-stack` codebase will be merged +into the `jam` CLI under a `create-stack` command. Once complete, a user should +be able to build a stack with a given descriptor file, `stack.toml`, using the +following command: + +`jam create-stack --config stack.toml --build-output build.oci --run-output run.oci` + +#### Output Format + +The toolchain will produce as its output a set of OCI-archive files. These +files will conform to the existing specification for an [OCI image +layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). +Additionally, these images will be structured to form a multi-architecture +index. + +Internally to the toolchain, this will be achieved by building each stack phase +image for the given list of platforms. For example, if the Stack Descriptor +specifies `platforms = ["linux/amd64", "linux/arm64"]`, the toolchain will +build 4 concrete images with the following permutations: `build on +linux/amd64`, `run on linux/amd64`, `build on linux/arm64`, and `run on +linux/arm64`. These 4 images will then be grouped into 2 image index archives: +`build.oci` and `run.oci`. + +## Rationale and Alternatives + +We could abandon the `create-stack` codebase entirely and expect that anyone +developing stacks just build a `Dockerfile` following the +[directions](https://buildpacks.io/docs/operator-guide/create-a-stack/) +outlined in the buildpacks documentation. + +## Implementation + +The `create-stack` command will be refactored to support this new configuration +file format and the features it allows. The codebase will then be moved into +the `jam` codebase as a command within that tool. This aligns more with how the +project maintains its tooling and allows us to keep tooling consolidated under +the tooling subteam. + +The stacks team will be granted CODEOWNERS status for this addition to the +codebase. + +## Prior Art + +The buildpacks spec defines several descriptor files in TOML format.