Skip to content
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.

Sign up for GitHub

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

RFC: Remove Stacks & Mixins #172

Merged
merged 19 commits into from
Oct 7, 2021
Merged

RFC: Remove Stacks & Mixins #172

Changes from 4 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
d16f1a9
Add RFC: Remove Stacks & Mixins
sclevine Jun 30, 2021
1b55b44
RFC: Remove Stack & Mixins: Add platform table example
sclevine Jul 1, 2021
5e7d9ff
Add alternatives
sclevine Jul 1, 2021
df7d715
Add unanswered question
sclevine Jul 1, 2021
02cb22a
RFC: Remove stacks & mixins: respond to feedback
sclevine Jul 15, 2021
f888612
RFC: Remove Stacks & Mixins: remove packages
sclevine Jul 22, 2021
ce16a04
RFC: Remove Stacks & Mixins: address outstanding feedback
sclevine Aug 10, 2021
b876676
RFC: Remove Stacks & Mixins: Add default value for target list
sclevine Aug 16, 2021
891104e
RFC: Remove Stacks & Mixins: determine OS for default target
sclevine Aug 16, 2021
e2587fb
RFC: Stacks & Mixins: rebaser
sclevine Aug 25, 2021
0dd5899
RFC: Stacks & Mixins: soften SBoM wording
sclevine Aug 25, 2021
b1f606c
Reword intro
sclevine Sep 8, 2021
4299b4b
Fix typos in intro
sclevine Sep 8, 2021
ef6d531
Clarify values for windows
sclevine Sep 8, 2021
ff4c94a
Explain `CNB_TARGET_ID`
sclevine Sep 8, 2021
3fe2b89
Add unresolved question about packages
sclevine Sep 8, 2021
e24bcad
Add examples
sclevine Sep 8, 2021
85545b5
Fix examples
sclevine Sep 8, 2021
ad051c4
RFC: Remove Stacks & Mixins: Add question re: targets
sclevine Sep 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 112 additions & 0 deletions text/0000-remove-stacks-mixins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Meta
[meta]: #meta
- Name: Remove Stacks & Mixins
- Start Date: 2021-06-30
- Author(s): sclevine
- RFC Pull Request: (leave blank)
- CNB Pull Request: (leave blank)
- CNB Issue: (leave blank)
- Supersedes: [RFC0069](https://github.com/buildpacks/rfcs/blob/main/text/0069-stack-buildpacks.md), [RFC#167](https://github.com/buildpacks/rfcs/pull/167), many others

# Summary
[summary]: #summary

*NOTE: This proposal is part of a larger initiative to reduce complexity originally outlined in https://github.com/buildpacks/rfcs/pull/167*

This RFC proposes that we remove the "stack" and "mixin" concepts from the project and replace them with existing constructs in the container image ecosystem such as base images, Dockerfiles, and OS packages.
sclevine marked this conversation as resolved.
Show resolved Hide resolved

# Motivation
[motivation]: #motivation

The "stack" and "mixin" concepts add unnecessary complexity to the project and make it difficult for new users and contributors to understand how buildpacks work. Compatibility guarantees that are strongly enforced by the stack contract could be replaced with metadata validations and warnings.

# What it is
[what-it-is]: #what-it-is

Summary of changes:
- Replace mixins with a [CycloneDX](https://cyclonedx.org)-formatted list of packages.
- Replace stack metadata (including stack IDs) with canonical OS metadata.
jromero marked this conversation as resolved.
Show resolved Hide resolved

# How it Works
[how-it-works]: #how-it-works

## Base Image Metadata
sclevine marked this conversation as resolved.
Show resolved Hide resolved

Instead of a stack ID, runtime and build-time base images are labeled with the following canonicalized metadata:
jromero marked this conversation as resolved.
Show resolved Hide resolved
jromero marked this conversation as resolved.
Show resolved Hide resolved
- OS (e.g., "linux", `$GOOS`)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these strings able to be anything? Could I, if I wanted to, create a JesseOS OS string to tightly control the buildpacks that have explicitly updated to work on my build/run images?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OS and Architecture would be restricted to GOOS and GOARCH values. Distribution and Version could technically be anything, but should match /etc/os-release for Linux distros.

- Architecture (e.g., "x86_64", `$GOARCH`)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Off-topic: Is there any plan/idea for buildpacks to support building multi-platform images, such that a single image manifest can describe an image for linux/arm64 and linux/arm64 and windows/amd64, etc.? Or is the intention that someone wanting to build a multi-platform image should use buildpacks to produce multiple platform-specific images, then stitch them together with something like docker manifest create ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No current RFC, but I definitely agree that we should eventually support exporting multi-platform manifest indexes.

The BuildKit frontend might help us with this, via buildx: buildpacks/pack#768

For non-local builds, we could extend the current exporter to accept a set of layers for each OS/ARCH combination.

In either case, we'd probably want to pass standardized env vars (e.g., $CNB_TARGET_ARCH) to the builder and buildpacks to support cross-compilation.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any plan/idea for buildpacks to support building multi-platform images

This is hard to do well given that (some exceptions wrt docker-for-mac notwithstanding) the build takes place in a docker container and a given daemon only supports a single os/arch.

You could theoretically have a buildpacks execute on one target while producing launch layers that are valid for a different target but this puts a lot of responsibility on the buildpack author and comes with a lot of gotchas. e.g

  • a single layer is unlikely to be valid as both a build and launch layers
  • ecosystem tools that buildpacks delegate to will make assumptions based on the build environment

imho this is unlikely to end well

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could theoretically have a buildpacks execute on one target while producing launch layers that are valid for a different target

I'm not opposed to this. Cross-compilation seems like a reasonable feature request to me. We would probably want to pass "target" metadata (e.g., from a run image label) to the buildpacks. When multiple run images are provided, buildpacks could produce multiple versions of the same layer for different architectures.

- Distribution (optional) (e.g., "ubuntu", `$ID`)
- Version (optional) (e.g., "18.04", `$VERSION_ID`)

For Linux-based images, each field should be canonicalized against values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`).
hone marked this conversation as resolved.
Show resolved Hide resolved
sclevine marked this conversation as resolved.
Show resolved Hide resolved

The `stacks` list in `buildpack.toml` is replaced by a `platforms` list, where each entry corresponds to a different buildpack image that is exported into a [manifest index](https://github.com/opencontainers/image-spec/blob/master/image-index.md). Each entry may contain multiple valid values for Distribution and/or Version, but only a single OS and Architecture. Each entry may also contain a list of package names (as PURL URLs without versions or qualifiers) that specify detect-time and build-time (but not runtime) OS package dependencies. Packages may be specified for all Versions of a distribution, or for a specific Version. Buildpacks may express **runtime** OS package dependencies during detection (see "Runtime Base Image Requirements" below).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As the goal of buildpacks is to build an image from an app's project where several build/detect/ (1 to many) steps are done using a Build image and next launched using a Runtime or stack or runtimeStack image, then I think that it is important to continue to use a wording that everyone will understand.

This is the reason why I would like to suggest to keep the stack (or maybe to rename it to: runStack, runtimeStack, ...) word instead of using platform.

Why: to improve the readability of a builder definition with a wording which is more inline with what finally we would like to describe (or what we want to do during a build or when we will launch the image built)

Example of such new definition could be

  # buildPacks could be renamed to buildSteps ;-)
  buildPacks:
  # List of build steps executed by the Lifecycle creator during: detect, build, ... steps
    - id: dev.snowdrop.jdk
      packUri: 'docker://quay.io/snowdrop/pack-jdk:11'
      buildPackImage: 'quay.io/snowdrop/buildpack-jdk:1.0'
    - id: dev.snowdrop.maven
      packUri: 'docker://quay.io/snowdrop/pack-maven:3.5'
      buildPackImage: 'quay.io/snowdrop/buildpack-maven:1.0'
    - id: dev.snowdrop.gradle
      packUri: 'docker://quay.io/snowdrop/pack-gradle:7.1'
      buildImage: 'quay.io/snowdrop/buildpack-gradle:1.0'
      optional: yes
      packages:
        - pkg:rpm/rhel/[email protected]
  # List of run stacks image supporting the build image      
  runStacks:
    - id: dev.snowdrop.stack.jdk16
      default: yes
      os: rhel
      version: 8
      arch: x86_64
      runtimeImage: 'quay.io/snowdrop/stack-run:jdk16'
      packages:
        - pkg:rpm/rhel/openjdk11
    - id: dev.snowdrop.stack.jdk11
      os: ubuntu
      version: 
      arch: x86_64
      runtimeImage: 'quay.io/snowdrop/stack-run:jdk11'

See gist created: https://gist.github.com/cmoulliard/04999929df0b758b5edbdf19dfc85f45

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I understand the proposed example. Some questions:

  • Where does the build-time base image come from for the JDK and Maven buildpacks?
  • Is a different build-time base image selected when the runtime base image OS changes?
  • Are the buildpack IDs optional?
  • How does the packages list work?
  • Are you proposing that we re-define stack to only refer to the runtime base image?

Would be great to dig into this during the weekly WG meeting.

I'm not attached to platforms for the table name, but I would like to remove unnecessary, project-specific terms to make the project more accessible.


App image builds fail if the build image and selected run image have mismatched metadata. We may introduce flags or additional labels to skip this validation (e.g., for cross-compilation or minimal runtime base images). An image without a specified Distribution is compatible with images specifying any Distribution. An image specifying a Distribution without a Version is compatible with images specifying any Versions of that Distribution.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

App image builds fail if the build image and selected run image have mismatched metadata

Haven't thought this through all the way but would it make sense to this in the build plan as well. E.g. a buildpack could specify in buildpack.toml that it needs to run on a particular distribution but could express at detect time that the resulting layers could run on any-linux (distroless images).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An image without a specified Distribution is compatible with images specifying any Distribution. An image specifying a Distribution without a Version is compatible with images specifying any Versions of that Distribution.

Is this what would replace wildcard stack support, i.e. stack="*".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

E.g. a buildpack could specify in buildpack.toml that it needs to run on a particular distribution but could express at detect time that the resulting layers could run on any-linux (distroless images).

I'm not sure this needs to be dynamic. I wonder if this could be part of the multi-platform interface? See: #172 (comment)

Is this what would replace wildcard stack support, i.e. stack="*".

The requirement is just describing the contract between the build and run images. Wildcard stack support is achieved by leaving off Distribution and Version entirely. (There is no wildcard support for OS/Architecture.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just updating this thread in case someone comes along in two more years, but anyway it turned out while implementing we did make an explicit extension for "*" OS/Architecture.


When an app image is rebased, `pack rebase` will fail if the new run image and previous run image have mismatched metadata. This check may be skipped for Distribution and Version by passing a new `--force` flag to `pack rebase`.
sclevine marked this conversation as resolved.
Show resolved Hide resolved

#### Example: buildpack.toml `platforms` table
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ekcasey as requested. Looks very noisy, but I think it meets the requirements.

Copy link
Contributor

@dmikusa dmikusa Jul 1, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you explain the sample, please? If I have this example in my buildpack's buildpack.toml, what does that mean for the buildpack & compatibility with images? What sort of compatibility guarantees do I get?


```toml
hone marked this conversation as resolved.
Show resolved Hide resolved
[[platforms]]
os = "linux"
arch = "x86_64"
[[platforms.distros]]
name = "ubuntu"
[[platforms.distros.versions]]
version = "18.04"
packages = ["pkg:deb/ubuntu/curl"]
[[platforms.distros.versions]]
version = "20.04"
packages = ["pkg:deb/ubuntu/curl2"]

[[platforms]]
os = "linux"
arch = "x86_64"
ekcasey marked this conversation as resolved.
Show resolved Hide resolved
[[platforms.distros]]
name = "ubuntu"
packages = ["pkg:deb/ubuntu/curl"]
[[platforms.distros.versions]]
version = "14.04"
[[platforms.distros.versions]]
version = "16.04"
```

## Mixins

The mixins label on each base image is replaced by a layer in each base image containing a single file consisting of a [CycloneDX](https://cyclonedx.org)-formatted list of packages. Each package entry has a [PURL](https://github.com/package-url/purl-spec)-formatted ID that uniquely identifies the package.
sclevine marked this conversation as resolved.
Show resolved Hide resolved

### Validations

Buildpack base image metadata and packages specified in `buildpack.toml`'s `platforms` list are validated against the runtime and build-time base images.

Runtime and build-time base image packages are no longer validated against each other.

When an app image is rebased, `pack rebase` will fail if packages are removed from the new runtime base image. This check may be skipped by passing a new `--force` flag to `pack rebase`.

## Runtime Base Image Requirements

Buildpacks may specify a list of package names (as PURL URLs without versions or qualifiers) in a `packages` table in the build plan. The build will fail if these packages are not present in the runtime base image.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Example please :)


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to address the migration path in this RFC

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed, let me know if you think I covered the relevant migration scenarios

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for adding this! Would we also continue to allow [[stacks]] in buildpack.toml, and ignore it at some point?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely, I can add that as well

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These labels will be deprecated (but allowed) for the forseeable future.

@jkutner This makes me think [[stacks]] and those labels would go away at the same time.

# Drawbacks
[drawbacks]: #drawbacks

- Involves breaking changes.

# Alternatives
[alternatives]: #alternatives

- Keep stacks.
sclevine marked this conversation as resolved.
Show resolved Hide resolved
- Make the above changes but keep some existing terminology: stacks, build-image, run-image.
jromero marked this conversation as resolved.
Show resolved Hide resolved
- Continue to allow for static definition of runtime package requirements in `buildpack.toml`.

# Unresolved Questions
sclevine marked this conversation as resolved.
Show resolved Hide resolved
[unresolved-questions]: #unresolved-questions

- Should packages be determined during the detect or build phase? Opinion: detect phase, so that (in a later RFC), a runtime base image's app-specified Dockerfiles may by applied in parallel to the buildpack build process.
- How will migration work? Can we make new base images compatible with older buildpacks? Can we make newer buildpacks compatible with older stacks?
# Spec. Changes (OPTIONAL)
[spec-changes]: #spec-changes

This RFC requires extensive changes to all specifications.