lifecycle

README

Lifecycle

A reference implementation of the Cloud Native Buildpacks specification.

Supported APIs

Lifecycle Version	Platform APIs	Buildpack APIs
0.13.x	0.3, 0.4, 0.5, 0.6, 0.7, 0.8	0.2, 0.3, 0.4, 0.5, 0.6, 0.7
0.12.x	0.3, 0.4, 0.5, 0.6, 0.7	0.2, 0.3, 0.4, 0.5, 0.6
0.11.x	0.3, 0.4, 0.5, 0.6	0.2, 0.3, 0.4, 0.5, 0.6
0.10.x	0.3, 0.4, 0.5	0.2, 0.3, 0.4, 0.5
0.9.x	0.3, 0.4	0.2, 0.3, 0.4
0.8.x	0.3	0.2
0.7.x	0.2	0.2
0.6.x	0.2	0.2

* denotes unreleased version

Usage

Build

Either:

• detector - Chooses buildpacks (via /bin/detect) and produces a build plan.
• analyzer - Restores layer metadata from the previous image and from the cache.
• restorer - Restores cached layers.
• builder - Executes buildpacks (via /bin/build).
• exporter - Creates an image and caches layers.

Or:

• creator - Runs the five phases listed above in order.

Run

• launcher - Invokes a chosen process.

Rebase

• rebaser - Creates an image from a previous image with updated base layers.

Contributing

• CONTRIBUTING - Information on how to contribute and grow your understanding of the lifecycle.
• DEVELOPMENT - Further detail to help you during the development process.
• RELEASE - Further details about our release process.

Documentation

Index

• Constants
• Variables
• func ReadGroup(path string) (buildpack.Group, error)
• func ReadOrder(path string) (buildpack.Order, error)
• func TruncateSha(sha string) string
• func WriteTOML(path string, data interface{}) error
• type Analyzer
  • func (a *Analyzer) Analyze() (platform.AnalyzedMetadata, error)
• type BuildEnv
• type Builder
  • func (b *Builder) Build() (*platform.BuildMetadata, error)
  • func (b *Builder) BuildConfig() (buildpack.BuildConfig, error)
• type Buildpack
• type BuildpackStore
• type Cache
• type DefaultResolver
  • func (r *DefaultResolver) Resolve(done []buildpack.GroupBuildpack, detectRuns *sync.Map) ([]buildpack.GroupBuildpack, []platform.BuildPlanEntry, error)
• type Detector
  • func NewDetector(config buildpack.DetectConfig, buildpacksDir string, platform Platform) (*Detector, error)
  • func (d *Detector) Detect(order buildpack.Order) (buildpack.Group, platform.BuildPlan, error)
  • func (d *Detector) DetectOrder(order buildpack.Order) (buildpack.Group, platform.BuildPlan, error)
• type ExportOptions
• type Exporter
  • func (e *Exporter) Cache(layersDir string, cacheStore Cache) error
  • func (e *Exporter) Export(opts ExportOptions) (platform.ExportReport, error)
• type LauncherConfig
• type LayerDir
• type LayerFactory
• type Logger
• type MultiError
  • func (me *MultiError) Error() string
• type Platform
• type RebaseReport
• type Rebaser
  • func (r *Rebaser) Rebase(appImage imgutil.Image, newBaseImage imgutil.Image, additionalNames []string) (RebaseReport, error)
• type Resolver
• type Restorer
  • func (r *Restorer) Restore(cache Cache) error

Constants

const (
	CodeDetectPass = 0
	CodeDetectFail = 100
)

Variables

var (
	ErrFailedDetection = errors.New("no buildpacks participating")
	ErrBuildpack       = errors.New("buildpack(s) failed with err")
)

Functions

func ReadGroup

func ReadGroup(path string) (buildpack.Group, error)

func ReadOrder

func ReadOrder(path string) (buildpack.Order, error)

func TruncateSha

func TruncateSha(sha string) string

func WriteTOML

func WriteTOML(path string, data interface{}) error

Types

type Analyzer

type Analyzer struct {
	PreviousImage imgutil.Image
	RunImage      imgutil.Image
	Logger        Logger
	Platform      Platform
	SBOMRestorer  layer.SBOMRestorer

	// Platform API < 0.7
	Buildpacks            []buildpack.GroupBuildpack
	Cache                 Cache
	LayerMetadataRestorer layer.MetadataRestorer
}

func (*Analyzer) Analyze

func (a *Analyzer) Analyze() (platform.AnalyzedMetadata, error)

Analyze fetches the layers metadata from the previous image and writes analyzed.toml.

type BuildEnv

type BuildEnv interface {
	AddRootDir(baseDir string) error
	AddEnvDir(envDir string, defaultAction env.ActionType) error
	WithPlatform(platformDir string) ([]string, error)
	List() []string
}

type Builder

type Builder struct {
	AppDir         string
	LayersDir      string
	PlatformDir    string
	Platform       Platform
	Group          buildpack.Group
	Plan           platform.BuildPlan
	Out, Err       io.Writer
	Logger         Logger
	BuildpackStore BuildpackStore
}

func (*Builder) Build

func (b *Builder) Build() (*platform.BuildMetadata, error)

func (*Builder) BuildConfig

func (b *Builder) BuildConfig() (buildpack.BuildConfig, error)

type Buildpack

type Buildpack interface {
	Build(bpPlan buildpack.Plan, config buildpack.BuildConfig, bpEnv buildpack.BuildEnv) (buildpack.BuildResult, error)
	ConfigFile() *buildpack.Descriptor
	Detect(config *buildpack.DetectConfig, bpEnv buildpack.BuildEnv) buildpack.DetectRun
}

type BuildpackStore

type BuildpackStore interface {
	Lookup(bpID, bpVersion string) (buildpack.Buildpack, error)
}

type Cache

type Cache interface {
	Exists() bool
	Name() string
	SetMetadata(metadata platform.CacheMetadata) error
	RetrieveMetadata() (platform.CacheMetadata, error)
	AddLayerFile(tarPath string, sha string) error
	ReuseLayer(sha string) error
	RetrieveLayer(sha string) (io.ReadCloser, error)
	Commit() error
}

type DefaultResolver

type DefaultResolver struct {
	Logger Logger
}

func (*DefaultResolver) Resolve

func (r *DefaultResolver) Resolve(done []buildpack.GroupBuildpack, detectRuns *sync.Map) ([]buildpack.GroupBuildpack, []platform.BuildPlanEntry, error)

Resolve aggregates the detect output for a group of buildpacks and tries to resolve a build plan for the group. If any required buildpack in the group failed detection or a build plan cannot be resolved, it returns an error.

type Detector

type Detector struct {
	buildpack.DetectConfig
	Platform Platform
	Resolver Resolver
	Runs     *sync.Map
	Store    BuildpackStore
}

func NewDetector

func NewDetector(config buildpack.DetectConfig, buildpacksDir string, platform Platform) (*Detector, error)

func (*Detector) Detect

func (d *Detector) Detect(order buildpack.Order) (buildpack.Group, platform.BuildPlan, error)

func (*Detector) DetectOrder

func (d *Detector) DetectOrder(order buildpack.Order) (buildpack.Group, platform.BuildPlan, error)

type ExportOptions

type ExportOptions struct {
	LayersDir          string
	AppDir             string
	WorkingImage       imgutil.Image
	RunImageRef        string
	OrigMetadata       platform.LayersMetadata
	AdditionalNames    []string
	LauncherConfig     LauncherConfig
	Stack              platform.StackMetadata
	Project            platform.ProjectMetadata
	DefaultProcessType string
}

type Exporter

type Exporter struct {
	Buildpacks   []buildpack.GroupBuildpack
	LayerFactory LayerFactory
	Logger       Logger
	PlatformAPI  *api.Version
}

func (*Exporter) Cache

func (e *Exporter) Cache(layersDir string, cacheStore Cache) error

func (*Exporter) Export

func (e *Exporter) Export(opts ExportOptions) (platform.ExportReport, error)

type LauncherConfig

type LauncherConfig struct {
	Path     string
	Metadata platform.LauncherMetadata
}

type LayerDir

type LayerDir interface {
	Identifier() string
	Path() string
}

type LayerFactory

type LayerFactory interface {
	DirLayer(id string, dir string) (layers.Layer, error)
	LauncherLayer(path string) (layers.Layer, error)
	ProcessTypesLayer(metadata launch.Metadata) (layers.Layer, error)
	SliceLayers(dir string, slices []layers.Slice) ([]layers.Layer, error)
}

type Logger

type Logger interface {
	Debug(msg string)
	Debugf(fmt string, v ...interface{})

	Info(msg string)
	Infof(fmt string, v ...interface{})

	Warn(msg string)
	Warnf(fmt string, v ...interface{})

	Error(msg string)
	Errorf(fmt string, v ...interface{})
}

type MultiError

type MultiError struct {
	Errors []error
}

func (*MultiError) Error

func (me *MultiError) Error() string

type Platform

type Platform interface {
	API() *api.Version
}

type RebaseReport

type RebaseReport struct {
	Image platform.ImageReport `toml:"image"`
}

type Rebaser

type Rebaser struct {
	Logger      Logger
	PlatformAPI *api.Version
}

func (*Rebaser) Rebase

func (r *Rebaser) Rebase(appImage imgutil.Image, newBaseImage imgutil.Image, additionalNames []string) (RebaseReport, error)

type Resolver

type Resolver interface {
	Resolve(done []buildpack.GroupBuildpack, detectRuns *sync.Map) ([]buildpack.GroupBuildpack, []platform.BuildPlanEntry, error)
}

type Restorer

type Restorer struct {
	LayersDir string
	Logger    Logger

	Buildpacks            []buildpack.GroupBuildpack
	LayerMetadataRestorer layer.MetadataRestorer  // Platform API >= 0.7
	LayersMetadata        platform.LayersMetadata // Platform API >= 0.7
	Platform              Platform
	SBOMRestorer          layer.SBOMRestorer
}

func (*Restorer) Restore

func (r *Restorer) Restore(cache Cache) error

Restore restores metadata for launch and cache layers into the layers directory and attempts to restore layer data for cache=true layers, removing the layer when unsuccessful. If a usable cache is not provided, Restore will not restore any cache=true layer metadata.