0075-move-analyze-phase.md

Meta

• Name: Move analyze phase
• Start Date: 2021-01-13
• Author(s): @jkutner @jabrown85
• Status: Implemented
• RFC Pull Request: rfcs#135
• CNB Pull Request: buildpacks/spec#172
• CNB Issue: buildpacks/spec#194, buildpacks/lifecycle#530, buildpacks/pack#1078, buildpacks/docs#302
• Supersedes: N/A

Summary

This is a proposal to re-order and adjust Lifecycle phases. Specifically, moving "analyze" before "detect".

Motivation

Doing this would support the following features and capabilities:

• Stack buildpacks, which require a phase to read run-image mixins validation prior to detection
• Validating registry access for all images that are used can happen prior to detector or builder phases, providing faster failures for end users.

What it is

The analyze phase will now run before the detect phase. The analyze phase will have access to secrets and credentials used to access registries and other services, as it does today. Analyze will no longer require a group.toml. It will do this by splitting off some of the responsibilites into the restore phase.

New Responsibilities in analzyer

• Stack validation, to ensure that a new run-image is compatible with the previous app image
• Retrieve identifier (imageID or digest), stack ID, and mixins, which will be used by subsequent phases
• Validation of registry credentials, to avoid a long build that fails during export phase

Inputs

• Log level
• Run-image
• Stack ID
• stack.toml
• Previous Image
• Cache Image
• Destination tag(s)
• Cache Dir
• gid
• uid
• Path to output analyzed.toml
• Layers Directory
• Daemon

Output

• Exit status
• Info-level logs to stdout
• Error-level logs to stderr
• Analysis metadata analyzed.toml, including run-image information.

How it Works

A platform MUST execute the analyze phase either by invoking the /cnb/lifecycle/analyzer binary or by executing /cnb/lifecycle/creator.

The analyzer 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 the analyzer phase that reads image metadata and outputs an analyzed.toml would be remain.

The logic in the analyzer phase that analyzes layers would be moved to the restorer. restorer already takes in group.toml as a flag.

Drawbacks

• Platform maintainers will need to update the order of their container execution and also update flags for analyzer, detector, and restorer.

Alternatives

• Introduce Prepare Phase (this same rfc, previous version)

Prior Art

• Tekton prepare step

Unresolved Questions

• How should analyzed.toml be changed to include run-image information (mixins)

Spec. Changes

See buildpacks/spec PR #172