lifecycle

README

Lifecycle

A reference implementation of the Cloud Native Buildpacks specification.

Supported APIs

Lifecycle Version	Platform APIs	Buildpack APIs
0.17.x*	0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.10, 0.11, 0.12	0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.10
0.16.x	0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.10, 0.11	0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9
0.15.x	0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.10	0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9
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 SBOMExtensions() []string
• func TruncateSha(sha string) string
• type Analyzer
  • func (a *Analyzer) Analyze() (files.Analyzed, 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() (*files.BuildMetadata, error)
• type BuildpackAPIVerifier
• type Cache
• type CacheHandler
• type ConfigHandler
• type DefaultConfigHandler
  • func NewConfigHandler() *DefaultConfigHandler
  • func (h *DefaultConfigHandler) ReadAnalyzed(path string, logr log.Logger) (files.Analyzed, error)
  • func (h *DefaultConfigHandler) ReadGroup(path string) (buildpackGroup []buildpack.GroupElement, ...)
  • func (h *DefaultConfigHandler) ReadOrder(path string) (buildpack.Order, buildpack.Order, error)
  • func (h *DefaultConfigHandler) ReadRun(runPath string, logger log.Logger) (files.Run, error)
• type DefaultDetectResolver
  • func NewDefaultDetectResolver(logger log.Logger) *DefaultDetectResolver
  • func (r *DefaultDetectResolver) Resolve(done []buildpack.GroupElement, detectRuns *sync.Map) ([]buildpack.GroupElement, []files.BuildPlanEntry, error)
• type DetectResolver
• type Detector
  • func (d *Detector) Detect() (buildpack.Group, files.Plan, error)
  • func (d *Detector) DetectOrder(order buildpack.Order) (buildpack.Group, files.Plan, error)
• type DetectorFactory
  • func NewDetectorFactory(platformAPI *api.Version, apiVerifier BuildpackAPIVerifier, ...) *DetectorFactory
  • func (f *DetectorFactory) NewDetector(analyzedMD files.Analyzed, ...) (*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) (files.Report, error)
• type Extender
  • func (e *Extender) Extend(kind string, logger log.Logger) error
• type ExtenderFactory
  • func NewExtenderFactory(apiVerifier BuildpackAPIVerifier, configHandler ConfigHandler) *ExtenderFactory
  • func (f *ExtenderFactory) NewExtender(analyzedPath string, appDir string, extendedDir string, generatedDir string, ...) (*Extender, error)
• type GenerateResult
• type Generator
  • func (g *Generator) Generate() (GenerateResult, error)
• type GeneratorFactory
  • func NewGeneratorFactory(apiVerifier BuildpackAPIVerifier, configHandler ConfigHandler, ...) *GeneratorFactory
  • func (f *GeneratorFactory) NewGenerator(analyzedPath string, appDir string, buildConfigDir string, ...) (*Generator, error)
• type LauncherConfig
• type LayerDir
• type LayerFactory
• type MultiError
  • func (me *MultiError) Error() string
• type Platform
• type RebaseReport
• type Rebaser
  • func (r *Rebaser) Rebase(workingImage imgutil.Image, newBaseImage imgutil.Image, outputImageRef string, ...) (RebaseReport, error)
• type RegistryHandler
• type Restorer
  • func (r *Restorer) Restore(cache Cache) error

Constants

const (
	CodeDetectPass = 0
	CodeDetectFail = 100
)

const RebasableLabel = "io.buildpacks.rebasable"

Variables

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

var Config = &DefaultConfigHandler{}

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 SBOMExtensions

func SBOMExtensions() []string

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
	PlatformAPI   *api.Version

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

func (*Analyzer) Analyze

func (a *Analyzer) Analyze() (files.Analyzed, 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 image.Handler,
	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
	WithOverrides(platformDir string, baseConfigDir string) ([]string, error)
	List() []string
}

type Builder

type Builder struct {
	AppDir         string
	BuildConfigDir string
	LayersDir      string
	PlatformDir    string
	BuildExecutor  buildpack.BuildExecutor
	DirStore       DirStore
	Group          buildpack.Group
	Logger         log.Logger
	Out, Err       io.Writer
	Plan           files.Plan
	PlatformAPI    *api.Version
	AnalyzeMD      files.Analyzed
}

func (*Builder) Build

func (b *Builder) Build() (*files.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 {
	ReadAnalyzed(path string, logr log.Logger) (files.Analyzed, error)
	ReadGroup(path string) (buildpackGroup []buildpack.GroupElement, extensionsGroup []buildpack.GroupElement, err error)
	ReadOrder(path string) (buildpack.Order, buildpack.Order, error)
	ReadRun(runPath string, logger log.Logger) (files.Run, error)
}

type DefaultConfigHandler

type DefaultConfigHandler struct{}

func NewConfigHandler

func NewConfigHandler() *DefaultConfigHandler

func (*DefaultConfigHandler) ReadAnalyzed

func (h *DefaultConfigHandler) ReadAnalyzed(path string, logr log.Logger) (files.Analyzed, error)

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)

func (*DefaultConfigHandler) ReadRun

func (h *DefaultConfigHandler) ReadRun(runPath string, logger log.Logger) (files.Run, error)

type DefaultDetectResolver

type DefaultDetectResolver struct {
	Logger log.Logger
}

func NewDefaultDetectResolver

func NewDefaultDetectResolver(logger log.Logger) *DefaultDetectResolver

func (*DefaultDetectResolver) Resolve

func (r *DefaultDetectResolver) Resolve(done []buildpack.GroupElement, detectRuns *sync.Map) ([]buildpack.GroupElement, []files.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, []files.BuildPlanEntry, error)
}

type Detector

type Detector struct {
	AppDir         string
	BuildConfigDir string
	DirStore       DirStore
	Executor       buildpack.DetectExecutor
	HasExtensions  bool
	Logger         log.LoggerHandlerWithLevel
	Order          buildpack.Order
	PlatformDir    string
	Resolver       DetectResolver
	Runs           *sync.Map
	AnalyzeMD      files.Analyzed
	PlatformAPI    *api.Version
	// contains filtered or unexported fields
}

func (*Detector) Detect

func (d *Detector) Detect() (buildpack.Group, files.Plan, error)

func (*Detector) DetectOrder

func (d *Detector) DetectOrder(order buildpack.Order) (buildpack.Group, files.Plan, 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(analyzedMD files.Analyzed, appDir, buildConfigDir, orderPath, platformDir string, logger log.LoggerHandlerWithLevel) (*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 {
	ImageFor(reference string) (v1.Image, error)
	Apply(dockerfile extend.Dockerfile, toBaseImage v1.Image, withBuildOptions extend.Options, logger log.Logger) (v1.Image, error)
	Cleanup() error
}

type ExportOptions

type ExportOptions struct {
	// WorkingImage is the image to save.
	WorkingImage imgutil.Image
	// AdditionalNames are additional tags to save to, besides WorkingImage.Name().
	AdditionalNames []string
	// ExtendedDir is the location of extension-provided layers.
	ExtendedDir string
	// AppDir is the source directory.
	AppDir string
	// LayersDir is the location of buildpack-provided layers.
	LayersDir string
	// OrigMetadata was read from the previous image during the `analyze` phase, and is used to determine if a previously-uploaded layer can be re-used.
	OrigMetadata files.LayersMetadata
	// LauncherConfig is the launcher config.
	LauncherConfig LauncherConfig
	// DefaultProcessType is the user-provided default process type.
	DefaultProcessType string
	// RunImageRef is the run image reference for the layer metadata label.
	RunImageRef string
	// RunImageForExport is run image metadata for the layer metadata label for Platform API >= 0.12.
	RunImageForExport files.RunImageForExport
	// Project is project metadata for the project metadata label.
	Project files.ProjectMetadata
}

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) (files.Report, error)

type Extender

type Extender struct {
	AppDir       string // explicitly ignored by the Dockerfile applier, also the Dockefile build context
	ExtendedDir  string // output directory for extended image layers
	GeneratedDir string // input Dockerfiles are found here
	ImageRef     string // the image to extend
	LayersDir    string // explicitly ignored by the Dockerfile applier
	PlatformDir  string // explicitly ignored by the Dockerfile applier

	CacheTTL          time.Duration            // a platform input
	DockerfileApplier DockerfileApplier        // uses kaniko, BuildKit, or other to apply the provided Dockerfile to the provided image
	Extensions        []buildpack.GroupElement // extensions are ordered from group.toml
}

func (*Extender) Extend

func (e *Extender) Extend(kind string, logger log.Logger) 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(
	analyzedPath string,
	appDir string,
	extendedDir string,
	generatedDir string,
	groupPath string,
	layersDir string,
	platformDir string,
	cacheTTL time.Duration,
	dockerfileApplier DockerfileApplier,
	kind string,
	logger log.Logger,
) (*Extender, error)

type GenerateResult

type GenerateResult struct {
	AnalyzedMD files.Analyzed
	Plan       files.Plan
	UsePlan    bool
}

type Generator

type Generator struct {
	AppDir         string
	BuildConfigDir string
	GeneratedDir   string // e.g., <layers>/generated
	PlatformAPI    *api.Version
	PlatformDir    string
	AnalyzedMD     files.Analyzed
	DirStore       DirStore
	Executor       buildpack.GenerateExecutor
	Extensions     []buildpack.GroupElement
	Logger         log.Logger
	Out, Err       io.Writer
	Plan           files.Plan
	RunMetadata    files.Run
}

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,
	configHandler ConfigHandler,
	dirStore DirStore,
) *GeneratorFactory

func (*GeneratorFactory) NewGenerator

func (f *GeneratorFactory) NewGenerator(
	analyzedPath string,
	appDir string,
	buildConfigDir string,
	extensions []buildpack.GroupElement,
	generatedDir string,
	plan files.Plan,
	platformAPI *api.Version,
	platformDir string,
	runPath string,
	stdout, stderr io.Writer,
	logger log.Logger,
) (*Generator, error)

type LauncherConfig

type LauncherConfig struct {
	Path     string
	SBOMDir  string
	Metadata files.LauncherMetadata
}

type LayerDir

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

type LayerFactory

type LayerFactory interface {
	DirLayer(id string, dir string, createdBy 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 files.ImageReport `toml:"image"`
}

type Rebaser

type Rebaser struct {
	Logger      log.Logger
	PlatformAPI *api.Version
	Force       bool
}

func (*Rebaser) Rebase

func (r *Rebaser) Rebase(workingImage imgutil.Image, newBaseImage imgutil.Image, outputImageRef string, 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        files.LayersMetadata   // Platform API >= 0.7
	PlatformAPI           *api.Version
	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.