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 Copy(src, dst string) error
• func DecodeLabel(image imgutil.Image, label string, v interface{}) error
• 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 DefaultLayerMetadataRestorer
  • func (la *DefaultLayerMetadataRestorer) Restore(buildpacks []buildpack.GroupBuildpack, appMeta platform.LayersMetadata, ...) error
• 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 LayerFactory
• type LayerMetadataRestorer
  • func NewLayerMetadataRestorer(logger Logger, layersDir string, skipLayers bool) LayerMetadataRestorer
• type LayerSHAStore
  • func NewLayerSHAStore(useShaFiles bool) LayerSHAStore
• 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 Copy

func Copy(src, dst string) error

func DecodeLabel

func DecodeLabel(image imgutil.Image, label string, v interface{}) error

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

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

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
	PlatformAPI    *api.Version // TODO: derive from 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 DefaultLayerMetadataRestorer

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

func (*DefaultLayerMetadataRestorer) Restore

func (la *DefaultLayerMetadataRestorer) Restore(buildpacks []buildpack.GroupBuildpack, appMeta platform.LayersMetadata, cacheMeta platform.CacheMetadata, layerSHAStore LayerSHAStore) 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 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 LayerMetadataRestorer

type LayerMetadataRestorer interface {
	Restore(buildpacks []buildpack.GroupBuildpack, appMeta platform.LayersMetadata, cacheMeta platform.CacheMetadata, layerSHAStore LayerSHAStore) error
}

func NewLayerMetadataRestorer

func NewLayerMetadataRestorer(logger Logger, layersDir string, skipLayers bool) LayerMetadataRestorer

type LayerSHAStore

type LayerSHAStore interface {
	// contains filtered or unexported methods
}

func NewLayerSHAStore

func NewLayerSHAStore(useShaFiles bool) LayerSHAStore

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() string
}

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 LayerMetadataRestorer   // Platform API >= 0.7
	LayersMetadata        platform.LayersMetadata // Platform API >= 0.7
	Platform              Platform
}

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.