Skip to content

Latest commit

 

History

History
128 lines (93 loc) · 5.33 KB

0003-stack-descriptor.md

File metadata and controls

128 lines (93 loc) · 5.33 KB
Raw

Stack Descriptor and Tooling

Summary

The stack-building codebase, 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:

id = "<stack id>"                # required
homepage = "<homepage uri>"      # optional
maintainer = "<maintainer name>" # optional

platforms = ["linux/amd64", "linux/arm64", "<other-platform>"] # optional; default = ["linux/amd64"]; choices defined in https://docs.docker.com/desktop/multi-arch/

[metadata]
  example-key = "<example-value>"

[build]
  dockerfile = "<path to dockerfile>" # required
  description = "<image description>" # optional

  uid = 1001                   # required
  gid = 1000                   # required
  shell = "<user login shell>" # optional; default = "/sbin/nologin"

  [build.args] # optional
    example-arg = "<example-value>"

[run]
  dockerfile = "<path to dockerfile>" # required
  description = "<image description>" # optional

  uid = 1002                   # required
  gid = 1000                   # required
  shell = "<user login shell>" # optional; default = "/sbin/nologin"

  [run.args] # optional
    example-arg = "<example-value>"

[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. 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 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.