lifecycle

README

Lifecycle

A reference implementation of the Cloud Native Buildpacks specification.

Supported APIs

Lifecycle Version	Platform APIs	Buildpack APIs
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

Commands

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.

Development

To test, build, and package binaries into an archive, simply run:

$ make all

This will create an archive at out/lifecycle-<LIFECYCLE_VERSION>+linux.x86-64.tgz.

LIFECYCLE_VERSION defaults to the value returned by git describe --tags if not on a release branch (for more information about the release process, see RELEASE. It can be changed by prepending LIFECYCLE_VERSION=<some version> to the make command. For example:

$ LIFECYCLE_VERSION=1.2.3 make all

Steps can also be run individually as shown below.

Test

Formats, vets, and tests the code.

$ make test

Build

Builds binaries to out/linux/lifecycle/.

$ make build

To clean the out/ directory, run make clean.

Package

Creates an archive at out/lifecycle-<LIFECYCLE_VERSION>+linux.x86-64.tgz, using the contents of the out/linux/lifecycle/ directory, for the given (or default) LIFECYCLE_VERSION.

$ make package

Documentation

Index

• Constants
• Variables
• 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(image imgutil.Image, cache Cache) (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) (*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 Logger
• type MultiError
  • func (me *MultiError) Error() string
• 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 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 {
	Buildpacks []buildpack.GroupBuildpack
	LayersDir  string
	Logger     Logger
	SkipLayers bool
}

func (*Analyzer) Analyze

func (a *Analyzer) Analyze(image imgutil.Image, cache Cache) (platform.AnalyzedMetadata, error)

Analyze restores metadata for launch and cache layers into the layers directory. If a usable cache is not provided, Analyze will not restore any cache=true layer metadata.

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
	PlatformAPI    *api.Version
	Env            BuildEnv
	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) (buildpack.BuildResult, error)
	ConfigFile() *buildpack.Descriptor
	Detect(config *buildpack.DetectConfig) 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
	Resolver Resolver
	Runs     *sync.Map
	Store    BuildpackStore
}

func NewDetector

func NewDetector(config buildpack.DetectConfig, buildpacksDir string) (*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 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 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
	Buildpacks []buildpack.GroupBuildpack
	Logger     Logger
}

func (*Restorer) Restore

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

Restore attempts to restore layer data for cache=true layers, removing the layer when unsuccessful. If a usable cache is not provided, Restore will remove all cache=true layer metadata.