Skip to content

Latest commit

 

History

History
100 lines (71 loc) · 4.65 KB

0000-prepare-phase.md

File metadata and controls

100 lines (71 loc) · 4.65 KB
Raw

Meta

Summary

This is a proposal for a new Lifecycle phase, called "prepare", that would run before all other phases.

Definitions

  • stack descriptor - an enhanced version of the stack.toml
  • project descriptor - the project.toml extension specification

Motivation

Parity with Pack: A Lifecycle Prepare phase should make it easier for Platform Implementers to achieve parity with features of Pack. Today, features like project.toml are only supported by Pack, and a new platform would need to write its own parser.

The prepare phase would support the following features and capabilities:

What it is

A new Lifecycle phase and associated binary should be available to Platform Implementers, and should be executed by Pack. The prepare phase will run before all other phases, and prepare the execution environment for a buildpack build. This phase will have access to secrets and credentials used to access registries and other services.

Responsibilities

  • Parsing the project descriptor and performance various operations based on its contents, include:
    • downloading buildpacks
    • creating ephemeral buildpacks
    • applying include and exclude rules
    • modifying environment variables

Inputs

  • Log level
  • Run-image
  • Stack ID
  • Project descriptor (optional)
  • App source code

Output

  • Exit status
  • Info-level logs to stdout
  • Error-level logs to stderr
  • Stack descriptor
  • Analysis metadata
  • Buildpacks (derived from inline buildpacks in project descriptor, or buildpacks in project descriptor that are not present in the builder)
  • Order definition (derived from buildpacks configuration in project descriptor)
  • Lifecycle configuration (derived from configuration in project descriptor)
  • Mutated app source code (applying include and exclude rules in project descriptor)

How it Works

The prepare phase would be implemented as the /cnb/lifecycle/preparer binary. A platform MAY execute this phases either by invoking the /cnb/lifecycle/preparer binary or by executing /cnb/lifecycle/creator.

The preparer binary will have access to the Keychain, and MUST NOT execute arbitrary code provided by either the buildpack user or buildpack author.

The logic in pack that parses a project.toml would be copied or moved into the preparer.

The app source code (which may be provided to the prepare either as a directory, volume, or tarball) would be mutated (either by copying it to a new location, or making changes directory against it). The preparer may delete files to apply the include and exclude rules from project.toml.

Drawbacks

  • Yet another lifecycle phase

Alternatives

  • Reverse the order of analyze and detect phases
  • Split analyze into two parts (one to write analyzed.toml and one to analyze layers). The first (analyzed.toml) would be moved before the detect phase, and the second part (analyzing layers) would be merged into the restore phase.

Prior Art

Unresolved Questions

  • Do we still need analyzer, or can the remaining parts of analyze phase be rolled into restore phase?
  • Does pack still need to parse project.toml, or is there value in reading it early on (before lifecycle runs)?
  • Should we create a shared library for project.toml parsing?

Spec. Changes

See buildpacks/spec PR #176