lifecycle

README

Lifecycle

A reference implementation of the Cloud Native Buildpacks specification.

Supported APIs

Lifecycle Version	Platform APIs	Buildpack APIs
0.14.x	0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9	0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8
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:

• analyzer - Reads metadata from the previous image and ensures registry access.
• detector - Chooses buildpacks (via /bin/detect) and produces a build plan.
• restorer - Restores layer metadata from the previous image and from the cache, and 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 TruncateSha(sha string) string
• type Analyzer
  • func (a *Analyzer) Analyze() (platform.AnalyzedMetadata, error)
• type AnalyzerFactory
  • func NewAnalyzerFactory(platformAPI *api.Version, cacheHandler CacheHandler, ...) *AnalyzerFactory
  • func (f *AnalyzerFactory) NewAnalyzer(additionalTags []string, cacheImageRef string, launchCacheDir string, ...) (*Analyzer, 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 CacheHandler
• type ConfigHandler
• 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 ImageHandler
• 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 RegistryHandler
• 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 TruncateSha

func TruncateSha(sha string) string

Types

type Analyzer

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

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

func (*Analyzer) Analyze

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

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

type AnalyzerFactory

type AnalyzerFactory struct {
	// contains filtered or unexported fields
}

func NewAnalyzerFactory

func NewAnalyzerFactory(platformAPI *api.Version, cacheHandler CacheHandler, configHandler ConfigHandler, imageHandler ImageHandler, registryHandler RegistryHandler) *AnalyzerFactory

func (*AnalyzerFactory) NewAnalyzer

func (f *AnalyzerFactory) NewAnalyzer(
	additionalTags []string,
	cacheImageRef string,
	launchCacheDir string,
	layersDir string,
	legacyCacheDir string,
	legacyGroup buildpack.Group,
	legacyGroupPath string,
	outputImageRef string,
	previousImageRef string,
	runImageRef string,
	skipLayers bool,
	logger Logger,
) (*Analyzer, error)

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 CacheHandler

type CacheHandler interface {
	InitCache(imageRef, dir string) (Cache, error)
}

type ConfigHandler

type ConfigHandler interface {
	ReadGroup(path string) ([]buildpack.GroupBuildpack, 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 ImageHandler

type ImageHandler interface {
	InitImage(imageRef string) (imgutil.Image, error)
	Docker() bool
}

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 RegistryHandler

type RegistryHandler interface {
	EnsureReadAccess(imageRefs ...string) error
	EnsureWriteAccess(imageRefs ...string) 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.