platform

package
v0.20.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 10, 2024 License: Apache-2.0 Imports: 22 Imported by: 12

Documentation

Index

Constants

View Source 
const (
	EnvPlatformAPI     = "CNB_PLATFORM_API"
	DefaultPlatformAPI = ""
)
  • Platform Inputs to the Lifecycle and their Default Values

Platform Inputs to the Lifecycle and their Default Values

The CNB Platform Interface Specification, also known as the Platform API, defines the contract between a platform and the lifecycle. Multiple Platform API versions are supported by the lifecycle; for the list of supported versions, see [apiVersion.Platform]. This gives platform operators the flexibility to upgrade to newer lifecycle versions without breaking existing platform implementations, as long as the Platform API version in use is still supported by the CNB project. To view the Platform Interface Specification, see https://github.com/buildpacks/spec/blob/main/platform.md for the latest supported version, or https://github.com/buildpacks/spec/blob/platform/<version>/platform.md for a specific version. The Platform API version can be configured on a per-build basis through the environment; if no version is specified, the default version is used.

View Source 
const (
	EnvLogLevel     = "CNB_LOG_LEVEL"
	DefaultLogLevel = "info"

	EnvNoColor = "CNB_NO_COLOR"

	// EnvDeprecationMode is the desired behavior when deprecated APIs (either Platform or Buildpack) are requested.
	EnvDeprecationMode = "CNB_DEPRECATION_MODE" // defaults to ModeQuiet

	// EnvExperimentalMode is the desired behavior when experimental features (such as builds with image extensions) are requested.
	EnvExperimentalMode     = "CNB_EXPERIMENTAL_MODE"
	DefaultExperimentalMode = ModeError

	ModeQuiet = "quiet"
	ModeWarn  = "warn"
	ModeError = "error"

	// EnvExtendKind is the kind of base image to extend (build or run) when running the extender.
	EnvExtendKind     = "CNB_EXTEND_KIND"
	DefaultExtendKind = "build"
)
View Source 
const (
	EnvLayoutDir = "CNB_LAYOUT_DIR"
	EnvUseLayout = "CNB_USE_LAYOUT"
)

The lifecycle can be configured to read the input images like `run-image` or `previous-image` in OCI layout format instead of from a registry or daemon. Also, it can export the final application image on disk in the same format. The following environment variables must be set to configure the behavior of the lifecycle when exporting to OCI layout format.

View Source 
const (
	EnvStackID = "CNB_STACK_ID"
	EnvUID     = "CNB_USER_ID"
	EnvGID     = "CNB_GROUP_ID"
)

A build-time base image contains the OS-level dependencies needed for the build - i.e., dependencies needed for buildpack execution. The following environment variables must be set in the image config for build-time base images. `CNB_USER_ID` and `CNB_GROUP_ID` must match the UID and GID of the user specified in the image config `USER` field.

View Source 
const (
	EnvBuildConfigDir = "CNB_BUILD_CONFIG_DIR"
	EnvBuildpacksDir  = "CNB_BUILDPACKS_DIR"
	EnvExtensionsDir  = "CNB_EXTENSIONS_DIR"

	// EnvOrderPath is the location of the order file, which is used for detection. It contains a list of one or more buildpack groups
	// to be tested against application source code, so that the appropriate group for a given build can be determined.
	EnvOrderPath     = "CNB_ORDER_PATH"
	DefaultOrderFile = "order.toml"

	// EnvRunPath is the location of the run file, which contains information about the runtime base image.
	EnvRunPath = "CNB_RUN_PATH"
	// EnvStackPath is the location of the (deprecated) stack file, which contains information about the runtime base image.
	EnvStackPath = "CNB_STACK_PATH"
)

A "builder" image contains a build-time base image, buildpacks, a lifecycle, and configuration. The following are directories and files that are present in a builder image, and are inputs to the lifecycle.

View Source 
const (
	EnvAppDir      = "CNB_APP_DIR"
	EnvLayersDir   = "CNB_LAYERS_DIR"
	EnvPlatformDir = "CNB_PLATFORM_DIR"
)

The following are directory locations that are inputs to the `detect` and `build` phases. They are passed through to buildpacks and/or extensions by the lifecycle, and will each typically be a separate volume mount.

View Source 
const (
	// EnvAnalyzedPath is the location of the analyzed file, an output of the `analyze` phase.
	// It contains digest references to OCI images and metadata that are needed for the build.
	// It is an input to (and may be modified by) later lifecycle phases.
	EnvAnalyzedPath     = "CNB_ANALYZED_PATH"
	DefaultAnalyzedFile = "analyzed.toml"

	// EnvGroupPath is the location of the group file, an output of the `detect` phase.
	// It contains the group of buildpacks that detected.
	EnvGroupPath     = "CNB_GROUP_PATH"
	DefaultGroupFile = "group.toml"

	// EnvPlanPath is the location of the plan file, an output of the `detect` phase.
	// It contains information about dependencies that are needed for the build.
	EnvPlanPath     = "CNB_PLAN_PATH"
	DefaultPlanFile = "plan.toml"

	// EnvGeneratedDir is the location of the directory where the lifecycle should copy any Dockerfiles
	// output by image extensions during the `generate` phase.
	EnvGeneratedDir     = "CNB_GENERATED_DIR"
	DefaultGeneratedDir = "generated"

	// EnvExtendedDir is the location of the directory where the lifecycle should copy any image layers
	// created from applying generated Dockerfiles to a build- or run-time base image.
	EnvExtendedDir     = "CNB_EXTENDED_DIR"
	DefaultExtendedDir = "extended"

	// EnvReportPath is the location of the report file, an output of the `export` phase.
	// It contains information about the output application image.
	EnvReportPath     = "CNB_REPORT_PATH"
	DefaultReportFile = "report.toml"
)

The following instruct the lifecycle where to write files and data during the build.

View Source 
const (
	// EnvCacheDir is the location of the cache directory. Only one of cache directory or cache image may be used.
	// The cache is used to store buildpack-generated layers that are needed at build-time for future builds.
	EnvCacheDir = "CNB_CACHE_DIR"

	// EnvCacheImage is a reference to the cache image in an OCI registry. Only one of cache directory or cache image may be used.
	// The cache is used to store buildpack-generated layers that are needed at build-time for future builds.
	// Cache images in a daemon are disallowed (for performance reasons).
	EnvCacheImage = "CNB_CACHE_IMAGE"

	// EnvLaunchCacheDir is the location of the launch cache directory.
	// The launch cache is used when exporting to a daemon to store buildpack-generated layers, in order to speed up data retrieval for future builds.
	EnvLaunchCacheDir = "CNB_LAUNCH_CACHE_DIR"

	// EnvSkipLayers when true will instruct the lifecycle to ignore layers from a previously built image.
	EnvSkipLayers = "CNB_SKIP_LAYERS"

	// EnvSkipRestore is used when running the creator, and is equivalent to passing EnvSkipLayers to both the analyzer and
	// the restorer in the 5-phase invocation.
	EnvSkipRestore = "CNB_SKIP_RESTORE"

	// EnvKanikoCacheTTL is the amount of time to persist layers cached by kaniko during the `extend` phase.
	EnvKanikoCacheTTL = "CNB_KANIKO_CACHE_TTL"

	// EnvParallelExport is a flag used to instruct the lifecycle to export of application image and cache image in parallel, if true.
	EnvParallelExport = "CNB_PARALLEL_EXPORT"
)

The following are configuration options with respect to caching.

View Source 
const (
	// EnvPreviousImage is a reference to a previously built image; if not provided, it defaults to the output image reference.
	// It allows the lifecycle to re-use image layers that are unchanged from the previous build, avoiding the re-uploading
	// of data to the registry or daemon.
	EnvPreviousImage = "CNB_PREVIOUS_IMAGE"

	// EnvRunImage is a reference to the runtime base image. It is used to construct the output application image.
	EnvRunImage = "CNB_RUN_IMAGE"

	// EnvBuildImage is a reference to the build-time base image. It is needed when image extensions are used to extend the build-time base image.
	EnvBuildImage = "CNB_BUILD_IMAGE"
)

The following are images used by the lifecycle during the build.

View Source 
const (
	// EnvProcessType is the default process for the application image, the entrypoint in the output image config.
	EnvProcessType = "CNB_PROCESS_TYPE"

	// EnvProjectMetadataPath is the location of the project metadata file. It contains information about the source repository
	// that is added as metadata to the application image.
	EnvProjectMetadataPath     = "CNB_PROJECT_METADATA_PATH"
	DefaultProjectMetadataFile = "project-metadata.toml"
)

The following are configuration options for the output application image.

View Source 
const (
	FeatureDockerfiles = "Dockerfiles"
	LayoutFormat       = "export to OCI layout format"
)
View Source 
const (
	BuildMetadataLabel     = "io.buildpacks.build.metadata"
	LifecycleMetadataLabel = "io.buildpacks.lifecycle.metadata"
	MixinsLabel            = "io.buildpacks.stack.mixins"
	ProjectMetadataLabel   = "io.buildpacks.project.metadata"
	RebasableLabel         = "io.buildpacks.rebasable"
	StackIDLabel           = "io.buildpacks.stack.id"
)
View Source 
const (
	// TargetLabel is the label containing the target ID.
	TargetLabel = "io.buildpacks.base.id"
	// OSDistroNameLabel is the label containing the OS distribution name.
	OSDistroNameLabel = "io.buildpacks.base.distro.name"
	// OSDistroVersionLabel is the label containing the OS distribution version.
	OSDistroVersionLabel = "io.buildpacks.base.distro.version"
)
View Source 
const (
	CodeForFailed = 1
)
View Source 
const (
	// EnvForceRebase is used to force the rebaser to rebase the app image even if the operation is unsafe.
	EnvForceRebase = "CNB_FORCE_REBASE"
)

The following are configuration options for rebaser.

View Source 
const EnvInsecureRegistries = "CNB_INSECURE_REGISTRIES"

EnvInsecureRegistries configures the lifecycle to export the application to a remote "insecure" registry.

View Source 
const EnvUseDaemon = "CNB_USE_DAEMON"

EnvUseDaemon configures the lifecycle to export the application image to a daemon satisfying the Docker socket interface (e.g., docker, podman). If not provided, the default behavior is to export to an OCI registry. When exporting to a daemon, the socket must be available in the build environment and the lifecycle must be run as root. When exporting to an OCI registry, registry credentials must be provided either on-disk (e.g., `~/.docker/config.json`), via a credential helper, or via the `CNB_REGISTRY_AUTH` environment variable. See auth.DefaultKeychain for further information.

View Source 
const PlaceholderLayers = "<layers>"

Variables

View Source 
var (
	DefaultBuildConfigDir = filepath.Join(path.RootDir, "cnb", "build-config")
	DefaultBuildpacksDir  = filepath.Join(path.RootDir, "cnb", "buildpacks")
	DefaultExtensionsDir  = filepath.Join(path.RootDir, "cnb", "extensions")

	// CNBOrderPath is the default order path if the order file does not exist in the layers directory.
	CNBOrderPath = filepath.Join(path.RootDir, "cnb", "order.toml")

	// DefaultRunPath is the default run path.
	DefaultRunPath = filepath.Join(path.RootDir, "cnb", "run.toml")
	// DefaultStackPath is the default stack path.
	DefaultStackPath = filepath.Join(path.RootDir, "cnb", "stack.toml")
)
View Source 
var (
	DefaultAppDir      = filepath.Join(path.RootDir, "workspace")
	DefaultLayersDir   = filepath.Join(path.RootDir, "layers")
	DefaultPlatformDir = filepath.Join(path.RootDir, "platform")
)

The following are the default locations of input directories if not specified.

View Source 
var (
	// DefaultLauncherPath is the default location of the launcher executable during the build.
	// The launcher is exported in the output application image and is used to start application processes at runtime.
	DefaultLauncherPath        = filepath.Join(path.RootDir, "cnb", "lifecycle", "launcher"+path.ExecExt)
	DefaultBuildpacksioSBOMDir = filepath.Join(path.RootDir, "cnb", "lifecycle")
)
View Source 
var (
	// ErrOutputImageRequired user facing error message
	ErrOutputImageRequired = "image argument is required"
	// ErrRunImageRequiredWhenNoRunMD user facing error message
	ErrRunImageRequiredWhenNoRunMD = "-run-image is required when there is no run metadata available"
	// ErrSupplyOnlyOneRunImage user facing error message
	ErrSupplyOnlyOneRunImage = "supply only one of -run-image or (deprecated) -image"
	// ErrRunImageUnsupported user facing error message
	ErrRunImageUnsupported = "-run-image is unsupported"
	// ErrImageUnsupported user facing error message
	ErrImageUnsupported = "-image is unsupported"
	// MsgIgnoringLaunchCache user facing error message
	MsgIgnoringLaunchCache = "Ignoring -launch-cache, only intended for use with -daemon"
)
View Source 
var DefaultKanikoCacheTTL = 14 * (24 * time.Hour)

DefaultKanikoCacheTTL is the default kaniko cache TTL (2 weeks).

View Source 
var ExperimentalMode = envOrDefault(EnvExperimentalMode, DefaultExperimentalMode)

Functions

func BestRunImageMirrorFor added in v0.17.0 

func BestRunImageMirrorFor(targetRegistry string, runImageMD files.RunImageForExport, checkReadAccess CheckReadAccess) (string, error)

func CheckCache added in v0.16.0 

func CheckCache(i *LifecycleInputs, logger log.Logger) error

func CheckLaunchCache added in v0.16.0 

func CheckLaunchCache(i *LifecycleInputs, logger log.Logger) error

func CheckParallelExport added in v0.19.0 

func CheckParallelExport(i *LifecycleInputs, logger log.Logger) error

CheckParallelExport will warn when parallel export is enabled without a cache.

func EnvVarsFor added in v0.17.0 

func EnvVarsFor(d fsutil.Detector, tm files.TargetMetadata, logger log.Logger) []string

EnvVarsFor fulfills the prophecy set forth in https://github.com/buildpacks/rfcs/blob/b8abe33f2bdc58792acf0bd094dc4ce3c8a54dbb/text/0096-remove-stacks-mixins.md?plain=1#L97 by returning an array of "VARIABLE=value" strings suitable for inclusion in your environment or complete breakfast.

func FillAnalyzeImages added in v0.16.0 

func FillAnalyzeImages(i *LifecycleInputs, logger log.Logger) error

func FillCreateImages added in v0.16.0 

func FillCreateImages(i *LifecycleInputs, logger log.Logger) error

func FillExportRunImage added in v0.16.0 

func FillExportRunImage(i *LifecycleInputs, logger log.Logger) error

func GetRunImageForExport added in v0.17.0 

func GetRunImageForExport(inputs LifecycleInputs) (files.RunImageForExport, error)

GetRunImageForExport takes platform inputs and returns run image information for populating the io.buildpacks.lifecycle.metadata on the exported app image. The run image information is read from: - stack.toml for older platforms - run.toml for newer platforms, where the run image information returned is

  • the first set of image & mirrors that contains the platform-provided run image, or
  • the platform-provided run image if extensions were used and the image was not found in run.toml, or
  • the first set of image & mirrors in run.toml

The "platform-provided run image" is the run image "image" in analyzed.toml, NOT the run image "reference", as the run image "reference" could be a daemon image ID (which we'd not expect to find in run.toml).

func GetRunImageFromMetadata added in v0.19.0 

func GetRunImageFromMetadata(inputs LifecycleInputs, md files.LayersMetadata) (files.RunImageForExport, error)

GetRunImageFromMetadata extracts the run image from the image metadata

func GetTargetMetadata added in v0.17.0 

func GetTargetMetadata(fromImage imgutil.Image) (*files.TargetMetadata, error)

func GetTargetOSFromFileSystem added in v0.17.0 

func GetTargetOSFromFileSystem(d fsutil.Detector, tm *files.TargetMetadata, logger log.Logger)

GetTargetOSFromFileSystem populates the provided target metadata with information from /etc/os-release if it is available.

func GuardExperimental added in v0.15.0 

func GuardExperimental(requested string, logger log.Logger) error

func ResolveAbsoluteDirPaths added in v0.16.0 

func ResolveAbsoluteDirPaths(i *LifecycleInputs, _ log.Logger) error

func ResolveInputs added in v0.16.0 

func ResolveInputs(phase LifecyclePhase, i *LifecycleInputs, logger log.Logger) error

func TargetSatisfiedForBuild added in v0.17.0 

func TargetSatisfiedForBuild(d fsutil.Detector, base *files.TargetMetadata, module buildpack.TargetMetadata, logger log.Logger) bool

TargetSatisfiedForBuild modifies the provided target information for the base (run) image if distribution information is missing, by reading distribution information from /etc/os-release. OS, arch, and arch variant if not specified by at least one entity (image or module) will be treated as matches. If a module specifies distribution information, the image must also specify matching information.

func TargetSatisfiedForRebase added in v0.17.0 

func TargetSatisfiedForRebase(t files.TargetMetadata, appTargetMetadata files.TargetMetadata) bool

TargetSatisfiedForRebase treats optional fields (ArchVariant and Distribution fields) as wildcards if empty, returns true if all populated fields match

func UpdatePlaceholderPaths added in v0.16.0 

func UpdatePlaceholderPaths(i *LifecycleInputs, _ log.Logger) error

func ValidateImageRefs added in v0.16.0 

func ValidateImageRefs(i *LifecycleInputs, _ log.Logger) error

ValidateImageRefs ensures all provided image references are valid.

func ValidateOutputImageProvided added in v0.16.0 

func ValidateOutputImageProvided(i *LifecycleInputs, _ log.Logger) error

func ValidateRebaseRunImage added in v0.16.0 

func ValidateRebaseRunImage(i *LifecycleInputs, _ log.Logger) error

func ValidateSameRegistry added in v0.16.0 

func ValidateSameRegistry(tags ...string) error

func ValidateTargetsAreSameRegistry added in v0.16.0 

func ValidateTargetsAreSameRegistry(i *LifecycleInputs, _ log.Logger) error

ValidateTargetsAreSameRegistry ensures all output images are on the same registry.

Types

type CacheMetadata 

type CacheMetadata struct {
	BOM        files.LayerMetadata        `json:"sbom"`
	Buildpacks []buildpack.LayersMetadata `json:"buildpacks"`
}

func (*CacheMetadata) MetadataForBuildpack 

func (cm *CacheMetadata) MetadataForBuildpack(id string) buildpack.LayersMetadata

type CheckReadAccess added in v0.17.0 

type CheckReadAccess func(repo string, keychain authn.Keychain) (bool, error)

type DefaultExiter added in v0.13.2 

type DefaultExiter struct{}

func (*DefaultExiter) CodeFor added in v0.13.2 

func (e *DefaultExiter) CodeFor(errType LifecycleExitError) int

type DirStore added in v0.15.0 

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

func NewDirStore added in v0.15.0 

func NewDirStore(buildpacksDir string, extensionsDir string) *DirStore

func (*DirStore) Lookup added in v0.15.0 

func (s *DirStore) Lookup(kind, id, version string) (buildpack.Descriptor, error)

func (*DirStore) LookupBp added in v0.15.0 

func (s *DirStore) LookupBp(id, version string) (*buildpack.BpDescriptor, error)

func (*DirStore) LookupExt added in v0.15.0 

func (s *DirStore) LookupExt(id, version string) (*buildpack.ExtDescriptor, error)

type Exiter added in v0.13.2 

type Exiter interface {
	CodeFor(errType LifecycleExitError) int
}

func NewExiter added in v0.14.1 

func NewExiter(_ string) Exiter

NewExiter configures a new Exiter according to the provided Platform API version.

type LifecycleExitError added in v0.13.2 

type LifecycleExitError int
const (
	FailedDetect             LifecycleExitError = iota // generic detect error
	FailedDetectWithErrors                             // no buildpacks detected
	DetectError                                        // no buildpacks detected and at least one errored
	AnalyzeError                                       // generic analyze error
	RestoreError                                       // generic restore error
	FailedBuildWithErrors                              // buildpack error during /bin/build
	BuildError                                         // generic build error
	ExportError                                        // generic export error
	RebaseError                                        // generic rebase error
	LaunchError                                        // generic launch error
	FailedGenerateWithErrors                           // extension error during /bin/generate
	GenerateError                                      // generic generate error
	ExtendError                                        // generic extend error
)

type LifecycleInputs added in v0.16.0 

type LifecycleInputs struct {
	PlatformAPI           *api.Version
	AnalyzedPath          string
	AppDir                string
	BuildConfigDir        string
	BuildImageRef         string
	BuildpacksDir         string
	CacheDir              string
	CacheImageRef         string
	DefaultProcessType    string
	DeprecatedRunImageRef string
	ExtendKind            string
	ExtendedDir           string
	ExtensionsDir         string
	GeneratedDir          string
	GroupPath             string
	KanikoDir             string
	LaunchCacheDir        string
	LauncherPath          string
	LauncherSBOMDir       string
	LayersDir             string
	LayoutDir             string
	LogLevel              string
	OrderPath             string
	OutputImageRef        string
	PlanPath              string
	PlatformDir           string
	PreviousImageRef      string
	ProjectMetadataPath   string
	ReportPath            string
	RunImageRef           string
	RunPath               string
	StackPath             string
	UID                   int
	GID                   int
	ForceRebase           bool
	NoColor               bool
	ParallelExport        bool
	SkipLayers            bool
	UseDaemon             bool
	UseLayout             bool
	AdditionalTags        str.Slice // str.Slice satisfies the `Value` interface required by the `flag` package
	KanikoCacheTTL        time.Duration
	InsecureRegistries    str.Slice
}

LifecycleInputs holds the values of command-line flags and args i.e., platform inputs to the lifecycle. Fields are the cumulative total of inputs across all lifecycle phases and all supported Platform APIs.

func NewLifecycleInputs added in v0.17.0 

func NewLifecycleInputs(platformAPI *api.Version) *LifecycleInputs

NewLifecycleInputs constructs new lifecycle inputs for the provided Platform API version. Inputs can be specified by the platform (in order of precedence) through:

  • command-line flags
  • environment variables
  • falling back to the default value

NewLifecycleInputs provides, for each input, the value from the environment if specified, falling back to the default. As the final value of the layers directory (if provided via the command-line) is not known, inputs that default to a child of the layers directory are provided with PlaceholderLayers as the layers directory. To be valid, inputs obtained from calling NewLifecycleInputs MUST be updated using UpdatePlaceholderPaths once the final value of the layers directory is known.

func (*LifecycleInputs) AccessChecker added in v0.17.0 

func (i *LifecycleInputs) AccessChecker() CheckReadAccess

func (*LifecycleInputs) DestinationImages added in v0.16.0 

func (i *LifecycleInputs) DestinationImages() []string

func (*LifecycleInputs) Images added in v0.16.0 

func (i *LifecycleInputs) Images() []string

func (*LifecycleInputs) RegistryImages added in v0.16.0 

func (i *LifecycleInputs) RegistryImages() []string

type LifecycleInputsOperation added in v0.16.0 

type LifecycleInputsOperation func(i *LifecycleInputs, logger log.Logger) error

type LifecyclePhase added in v0.16.0 

type LifecyclePhase int
const (
	Analyze LifecyclePhase = iota
	Detect
	Restore
	Extend
	Build
	Export
	Create
	Rebase
)

type Platform 

type Platform struct {
	*LifecycleInputs
	Exiter
}

Platform holds lifecycle inputs and outputs for a given Platform API version and lifecycle phase.

func NewPlatformFor added in v0.16.0 

func NewPlatformFor(platformAPI string) *Platform

NewPlatformFor accepts a Platform API version and a layers directory, and returns a Platform with default lifecycle inputs and an exiter service.

func (*Platform) API 

func (p *Platform) API() *api.Version

func (*Platform) Inputs added in v0.18.0 

func (p *Platform) Inputs() LifecycleInputs

Inputs exposes the platform's inputs to the lifecycle.

Source Files

View all Source files

Directories

Path Synopsis
Package files contains schema and helper methods for working with lifecycle configuration files.
 Package files contains schema and helper methods for working with lifecycle configuration files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.