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 PrependExtensions(orderBp buildpack.Order, orderExt buildpack.Order) buildpack.Order
• func ReadGroup(path string) (buildpack.Group, error)
• func ReadOrder(path string) (buildpack.Order, buildpack.Order, error)
• func TruncateSha(sha string) string
• type Analyzer
  • func (a *Analyzer) Analyze() (platform.AnalyzedMetadata, error)
• type AnalyzerFactory
  • func NewAnalyzerFactory(platformAPI *api.Version, apiVerifier BuildpackAPIVerifier, ...) *AnalyzerFactory
  • func (f *AnalyzerFactory) NewAnalyzer(additionalTags []string, cacheImageRef string, launchCacheDir string, ...) (*Analyzer, error)
• type BuildEnv
• type Builder
  • func (b *Builder) Build() (*platform.BuildMetadata, error)
• type BuildpackAPIVerifier
• type Cache
• type CacheHandler
• type ConfigHandler
• type DefaultConfigHandler
  • func NewConfigHandler() *DefaultConfigHandler
  • func (h *DefaultConfigHandler) ReadGroup(path string) (buildpackGroup []buildpack.GroupElement, ...)
  • func (h *DefaultConfigHandler) ReadOrder(path string) (buildpack.Order, buildpack.Order, error)
• type DefaultResolver
  • func (r *DefaultResolver) Resolve(done []buildpack.GroupElement, detectRuns *sync.Map) ([]buildpack.GroupElement, []platform.BuildPlanEntry, error)
• type DetectResolver
• type Detector
  • func (d *Detector) Detect() (buildpack.Group, platform.BuildPlan, error)
  • func (d *Detector) DetectOrder(order buildpack.Order) (buildpack.Group, platform.BuildPlan, error)
• type DetectorFactory
  • func NewDetectorFactory(platformAPI *api.Version, apiVerifier BuildpackAPIVerifier, ...) *DetectorFactory
  • func (f *DetectorFactory) NewDetector(appDir, orderPath, platformDir string, logger log.Logger) (*Detector, error)
• type DirStore
• type DockerfileApplier
• type ExportOptions
• type Exporter
  • func (e *Exporter) Cache(layersDir string, cacheStore Cache) error
  • func (e *Exporter) Export(opts ExportOptions) (platform.ExportReport, error)
• type Extender
  • func (e *Extender) ExtendBuild(imageRef string) error
• type ExtenderFactory
  • func NewExtenderFactory(apiVerifier BuildpackAPIVerifier, configHandler ConfigHandler) *ExtenderFactory
  • func (f *ExtenderFactory) NewExtender(appDir string, generatedDir string, groupPath string, layersDir string, ...) (*Extender, error)
• type GenerateResult
• type Generator
  • func (g *Generator) Generate() (GenerateResult, error)
• type GeneratorFactory
  • func NewGeneratorFactory(apiVerifier BuildpackAPIVerifier, dirStore DirStore) *GeneratorFactory
  • func (f *GeneratorFactory) NewGenerator(appDir string, extensions []buildpack.GroupElement, generatedDir string, ...) (*Generator, error)
• type ImageHandler
• type LauncherConfig
• type LayerDir
• type LayerFactory
• 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 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 PrependExtensions

func PrependExtensions(orderBp buildpack.Order, orderExt buildpack.Order) buildpack.Order

func ReadGroup

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

func ReadOrder

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

func TruncateSha

func TruncateSha(sha string) string

Types

type Analyzer

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

	// Platform API < 0.7
	Buildpacks            []buildpack.GroupElement
	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,
	apiVerifier BuildpackAPIVerifier,
	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 log.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
	BuildExecutor buildpack.BuildExecutor
	DirStore      DirStore
	Group         buildpack.Group
	Logger        log.Logger
	Out, Err      io.Writer
	Plan          platform.BuildPlan
	Platform      Platform
}

func (*Builder) Build

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

type BuildpackAPIVerifier

type BuildpackAPIVerifier interface {
	VerifyBuildpackAPI(kind, name, requested string, logger log.Logger) 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) (buildpackGroup []buildpack.GroupElement, extensionsGroup []buildpack.GroupElement, err error)
	ReadOrder(path string) (buildpack.Order, buildpack.Order, error)
}

type DefaultConfigHandler

type DefaultConfigHandler struct{}

func NewConfigHandler

func NewConfigHandler() *DefaultConfigHandler

func (*DefaultConfigHandler) ReadGroup

func (h *DefaultConfigHandler) ReadGroup(path string) (buildpackGroup []buildpack.GroupElement, extensionsGroup []buildpack.GroupElement, err error)

func (*DefaultConfigHandler) ReadOrder

func (h *DefaultConfigHandler) ReadOrder(path string) (buildpack.Order, buildpack.Order, error)

type DefaultResolver

type DefaultResolver struct {
	Logger log.Logger
}

func (*DefaultResolver) Resolve

func (r *DefaultResolver) Resolve(done []buildpack.GroupElement, detectRuns *sync.Map) ([]buildpack.GroupElement, []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 DetectResolver

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

type Detector

type Detector struct {
	AppDir        string
	DirStore      DirStore
	Executor      buildpack.DetectExecutor
	HasExtensions bool
	Logger        log.Logger
	Order         buildpack.Order
	PlatformDir   string
	Resolver      DetectResolver
	Runs          *sync.Map
}

func (*Detector) Detect

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

func (*Detector) DetectOrder

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

type DetectorFactory

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

func NewDetectorFactory

func NewDetectorFactory(
	platformAPI *api.Version,
	apiVerifier BuildpackAPIVerifier,
	configHandler ConfigHandler,
	dirStore DirStore,
) *DetectorFactory

func (*DetectorFactory) NewDetector

func (f *DetectorFactory) NewDetector(appDir, orderPath, platformDir string, logger log.Logger) (*Detector, error)

type DirStore

type DirStore interface {
	Lookup(kind, id, version string) (buildpack.Descriptor, error)
	LookupBp(id, version string) (*buildpack.BpDescriptor, error)
	LookupExt(id, version string) (*buildpack.ExtDescriptor, error)
}

type DockerfileApplier

type DockerfileApplier interface {
	Apply(workspace string, baseImageRef string, dockerfiles []extend.Dockerfile, options extend.Options) 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.GroupElement
	LayerFactory LayerFactory
	Logger       log.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 Extender

type Extender struct {
	AppDir            string
	GeneratedDir      string
	GroupPath         string
	LayersDir         string
	PlatformDir       string
	CacheTTL          time.Duration
	DockerfileApplier DockerfileApplier
	Extensions        []buildpack.GroupElement
	Logger            log.Logger
}

func (*Extender) ExtendBuild

func (e *Extender) ExtendBuild(imageRef string) error

type ExtenderFactory

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

func NewExtenderFactory

func NewExtenderFactory(apiVerifier BuildpackAPIVerifier, configHandler ConfigHandler) *ExtenderFactory

func (*ExtenderFactory) NewExtender

func (f *ExtenderFactory) NewExtender(
	appDir string,
	generatedDir string,
	groupPath string,
	layersDir string,
	platformDir string,
	cacheTTL time.Duration,
	dockerfileApplier DockerfileApplier,
	logger log.Logger,
) (*Extender, error)

type GenerateResult

type GenerateResult struct {
	RunImage string
	Plan     platform.BuildPlan
	UsePlan  bool
}

type Generator

type Generator struct {
	AppDir       string
	GeneratedDir string // e.g., <layers>/generated
	PlatformDir  string
	DirStore     DirStore
	Executor     buildpack.GenerateExecutor
	Extensions   []buildpack.GroupElement
	Logger       log.Logger
	Out, Err     io.Writer
	Plan         platform.BuildPlan
}

func (*Generator) Generate

func (g *Generator) Generate() (GenerateResult, error)

type GeneratorFactory

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

func NewGeneratorFactory

func NewGeneratorFactory(
	apiVerifier BuildpackAPIVerifier,
	dirStore DirStore,
) *GeneratorFactory

func (*GeneratorFactory) NewGenerator

func (f *GeneratorFactory) NewGenerator(
	appDir string,
	extensions []buildpack.GroupElement,
	generatedDir string,
	plan platform.BuildPlan,
	platformDir string,
	stdout, stderr io.Writer,
	logger log.Logger,
) (*Generator, 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 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      log.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 Restorer

type Restorer struct {
	LayersDir string
	Logger    log.Logger

	Buildpacks            []buildpack.GroupElement
	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.