pack

README

pack - Buildpack CLI

pack makes it easy for...

• App Developers to use buildpacks to convert code into runnable images.
• Buildpack Authors to develop and package buildpacks for distribution.
• Operators to package buildpacks for distribution and maintain applications.

Usage

Getting Started

Get started by running through our tutorial: An App’s Brief Journey from Source to Image

Contributing

• CONTRIBUTING - Information on how to contribute, including the pull request process.
• DEVELOPMENT - Further detail to help you during the development process.
• RELEASE - Further details about our release process.

Documentation

Check out the command line documentation here

Specifications

pack is a CLI implementation of the Platform Interface Specification for Cloud Native Buildpacks.

To learn more about the details, check out the specs repository.

Documentation

Overview

Package pack is the reference implementation of a Cloud Native Buildpacks platform. Its purpose is to simplify the transformation of application source code, into a runnable OCI images.

Prerequisites

In order to use most pack functionality, you will need to have Docker installed. For easy installation instructions see: https://docs.docker.com/desktop/.

References

This package provides functionality to create and manipulate all artifacts outlined in the Cloud Native Buildpacks specification. An introduction to these artifacts and their usage can be found at https://buildpacks.io/docs/.

The formal specification of the pack platform provides can be found at: https://github.com/buildpacks/spec.

Example (Build)

This example shows the basic usage of the package: Create a client, call a configuration object, call the client's Build function.

package main

import (
	"context"
	"fmt"
	"math/rand"

	"github.com/buildpacks/pack"
)

func main() {
	//create a context object
	context := context.Background()

	//initialize a pack client
	client, err := pack.NewClient()
	if err != nil {
		panic(err)
	}

	// replace this with the location of a sample application
	// For a list of prepared samples see the 'apps' folder at
	// https://github.com/buildpacks/samples.
	appPath := "local/path/to/application/root"

	// randomly select a builder to use from among the following
	builderList := []string{
		"gcr.io/buildpacks/builder:v1",
		"heroku/buildpacks:20",
		"gcr.io/paketo-buildpacks/builder:base",
	}

	randomIndex := rand.Intn(len(builderList))
	randomBuilder := builderList[randomIndex]

	// initialize our options
	buildOpts := pack.BuildOptions{
		Image:        "pack-lib-test-image:0.0.1",
		Builder:      randomBuilder,
		AppPath:      appPath,
		TrustBuilder: true,
	}

	fmt.Println("building application image")

	// build an image
	err = client.Build(context, buildOpts)
	if err != nil {
		panic(err)
	}

	fmt.Println("build completed")
}

Index

• Constants
• Variables
• type BuildOptions
• type BuilderInfo
• type BuilderInspectionConfig
• type BuilderInspectionModifier
  • func WithDetectionOrderDepth(depth int) BuilderInspectionModifier
• type BuildpackInfo
• type BuildpackInfoKey
• type Client
  • func NewClient(opts ...ClientOption) (*Client, error)
  • func (c *Client) Build(ctx context.Context, opts BuildOptions) error
  • func (c *Client) CreateBuilder(ctx context.Context, opts CreateBuilderOptions) error
  • func (c *Client) InspectBuilder(name string, daemon bool, modifiers ...BuilderInspectionModifier) (*BuilderInfo, error)
  • func (c *Client) InspectBuildpack(opts InspectBuildpackOptions) (*BuildpackInfo, error)
  • func (c *Client) InspectImage(name string, daemon bool) (*ImageInfo, error)
  • func (c *Client) NewBuildpack(ctx context.Context, opts NewBuildpackOptions) error
  • func (c *Client) PackageBuildpack(ctx context.Context, opts PackageBuildpackOptions) error
  • func (c *Client) PullBuildpack(ctx context.Context, opts PullBuildpackOptions) error
  • func (c *Client) Rebase(ctx context.Context, opts RebaseOptions) error
  • func (c *Client) RegisterBuildpack(ctx context.Context, opts RegisterBuildpackOptions) error
  • func (c *Client) YankBuildpack(opts YankBuildpackOptions) error
• type ClientOption
  • func WithCacheDir(path string) ClientOption
  • func WithDockerClient(docker dockerClient.CommonAPIClient) ClientOption
  • func WithDownloader(d Downloader) ClientOption
  • func WithExperimental(experimental bool) ClientOption
  • func WithFetcher(f ImageFetcher) ClientOption
  • func WithImageFactory(f ImageFactory) ClientOption
  • func WithLogger(l logging.Logger) ClientOption
• type ContainerConfig
• type CreateBuilderOptions
• type Downloader
• type ExperimentError
  • func NewExperimentError(msg string) ExperimentError
  • func (ee ExperimentError) Error() string
• type ImageFactory
• type ImageFetcher
• type ImageInfo
• type ImgWrapper
  • func (iw ImgWrapper) Label(name string) (string, error)
• type InspectBuildpackOptions
• type LifecycleExecutor
• type NewBuildpackOptions
• type PackageBuildpackOptions
• type ProcessDetails
• type ProxyConfig
• type PullBuildpackOptions
• type RebaseOptions
• type RegisterBuildpackOptions
• type SoftError
  • func NewSoftError() SoftError
  • func (se SoftError) Error() string
• type YankBuildpackOptions

Examples

• Package (Build)

Constants

const (
	// Packaging indicator that format of inputs/outputs will be an OCI image on the registry.
	FormatImage = "image"

	// Packaging indicator that format of output will be a file on the host filesystem.
	FormatFile = "file"

	// CNBExtension is the file extension for a cloud native buildpack tar archive
	CNBExtension = ".cnb"
)

Variables

var (
	// Version is the version of `pack`. It is injected at compile time.
	Version = "0.0.0"
)

Types

type BuildOptions

type BuildOptions struct {
	// The base directory to use to resolve relative assets
	RelativeBaseDir string

	// required. Name of output image.
	Image string

	// required. Builder image name.
	Builder string

	// Name of the buildpack registry. Used to
	// add buildpacks to a build.
	Registry string

	// AppPath is the path to application bits.
	// If unset it defaults to current working directory.
	AppPath string

	// Specify the run image the Image will be
	// built atop.
	RunImage string

	// Address of docker daemon exposed to build container
	// e.g. tcp://example.com:1234, unix:///run/user/1000/podman/podman.sock
	DockerHost string

	// Used to determine a run-image mirror if Run Image is empty.
	// Used in combination with Builder metadata to determine to the the 'best' mirror.
	// 'best' is defined as:
	//  - if Publish is true, the best mirror matches registry we are publishing to.
	//  - if Publish is false, the best mirror matches a registry specified in Image.
	//  - otherwise if both of the above did not match, use mirror specified in
	//    the builder metadata
	AdditionalMirrors map[string][]string

	// User provided environment variables to the buildpacks.
	// Buildpacks may both read and overwrite these values.
	Env map[string]string

	// Option only valid if Publish is true
	// Create an additional image that contains cache=true layers and push it to the registry.
	CacheImage string

	// Option passed directly to the lifecycle.
	// If true, publishes Image directly to a registry.
	// Assumes Image contains a valid registry with credentials
	// provided by the docker client.
	Publish bool

	// Clear the build cache from previous builds.
	ClearCache bool

	// TrustBuilder when true optimizes builds by running
	// all lifecycle phases in a single container.
	// This places registry credentials on the builder's build image.
	// Only trust builders from reputable sources.
	TrustBuilder bool

	// List of buildpack images or archives to add to a builder.
	// These buildpacks may overwrite those on the builder if they
	// share both an ID and Version with a buildpack on the builder.
	Buildpacks []string

	// Additional image tags to push to, each will contain contents identical to Image
	AdditionalTags []string

	// Configure the proxy environment variables,
	// These variables will only be set in the build image
	// and will not be used if proxy env vars are already set.
	ProxyConfig *ProxyConfig

	// Configure network and volume mounts for the build containers.
	ContainerConfig ContainerConfig

	// Process type that will be used when setting container start command.
	DefaultProcessType string

	// Strategy for updating local images before a build.
	PullPolicy config.PullPolicy

	// ProjectDescriptorBaseDir is the base directory to find relative resources referenced by the ProjectDescriptor
	ProjectDescriptorBaseDir string

	// ProjectDescriptor describes the project and any configuration specific to the project
	ProjectDescriptor project.Descriptor

	// The lifecycle image that will be used for the analysis, restore and export phases
	// when using an untrusted builder.
	LifecycleImage string

	// The location at which to mount the AppDir in the build image.
	Workspace string
}

BuildOptions defines configuration settings for a Build.

type BuilderInfo

type BuilderInfo struct {
	// Human readable, description of a builder.
	Description string

	// Stack name used by the builder.
	Stack string

	// List of Stack mixins, this information is provided by Stack variable.
	Mixins []string

	// RunImage provided by the builder.
	RunImage string

	// List of all run image mirrors a builder will use to provide
	// the RunImage.
	RunImageMirrors []string

	// All buildpacks included within the builder.
	Buildpacks []dist.BuildpackInfo

	// Detailed ordering of buildpacks and nested buildpacks where depth is specified.
	Order pubbldr.DetectionOrder

	// Listing of all buildpack layers in a builder.
	// All elements in the Buildpacks variable are represented in this
	// object.
	BuildpackLayers dist.BuildpackLayers

	// Lifecycle provides the following API versioning information for a builder:
	// - Lifecycle Version used in this builder,
	// - Platform API,
	// - Buildpack API.
	Lifecycle builder.LifecycleDescriptor

	// Name and Version information from tooling used
	// to produce this builder.
	CreatedBy builder.CreatorMetadata
}

BuilderInfo is a collection of metadata describing a builder created using pack.

type BuilderInspectionConfig

type BuilderInspectionConfig struct {
	OrderDetectionDepth int
}

type BuilderInspectionModifier

type BuilderInspectionModifier func(config *BuilderInspectionConfig)

func WithDetectionOrderDepth

func WithDetectionOrderDepth(depth int) BuilderInspectionModifier

type BuildpackInfo

type BuildpackInfo struct {
	BuildpackMetadata buildpackage.Metadata
	Buildpacks        []dist.BuildpackInfo
	Order             dist.Order
	BuildpackLayers   dist.BuildpackLayers
	Location          buildpack.LocatorType
}

type BuildpackInfoKey

type BuildpackInfoKey struct {
	ID      string
	Version string
}

BuildpackInfoKey contains all information needed to determine buildpack equivalence.

type Client

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

Client is an orchestration object, it contains all parameters needed to build an app image using Cloud Native Buildpacks. All settings on this object should be changed through ClientOption functions.

func NewClient

func NewClient(opts ...ClientOption) (*Client, error)

NewClient allocates and returns a Client configured with the specified options.

func (*Client) Build

func (c *Client) Build(ctx context.Context, opts BuildOptions) error

Build configures settings for the build container(s) and lifecycle. It then invokes the lifecycle to build an app image. If any configuration is deemed invalid, or if any lifecycle phases fail, an error will be returned and no image produced.

func (*Client) CreateBuilder

func (c *Client) CreateBuilder(ctx context.Context, opts CreateBuilderOptions) error

CreateBuilder creates and saves a builder image to a registry with the provided options. If any configuration is invalid, it will error and exit without creating any images.

func (*Client) InspectBuilder

func (c *Client) InspectBuilder(name string, daemon bool, modifiers ...BuilderInspectionModifier) (*BuilderInfo, error)

InspectBuilder reads label metadata of a local or remote builder image. It initializes a BuilderInfo object with this metadata, and returns it. This method will error if the name image cannot be found both locally and remotely, or if the found image does not contain the proper labels.

func (*Client) InspectBuildpack

func (c *Client) InspectBuildpack(opts InspectBuildpackOptions) (*BuildpackInfo, error)

func (*Client) InspectImage

func (c *Client) InspectImage(name string, daemon bool) (*ImageInfo, error)

InspectImage reads the Label metadata of an image. It initializes a ImageInfo object using this metadata, and returns it. If daemon is true, first the local registry will be searched for the image. Otherwise it assumes the image is remote.

func (*Client) NewBuildpack

func (c *Client) NewBuildpack(ctx context.Context, opts NewBuildpackOptions) error

func (*Client) PackageBuildpack

func (c *Client) PackageBuildpack(ctx context.Context, opts PackageBuildpackOptions) error

PackageBuildpack packages buildpack(s) into either an image or file.

func (*Client) PullBuildpack

func (c *Client) PullBuildpack(ctx context.Context, opts PullBuildpackOptions) error

PullBuildpack pulls given buildpack to be stored locally

func (*Client) Rebase

func (c *Client) Rebase(ctx context.Context, opts RebaseOptions) error

Rebase updates the run image layers in an app image. This operation mutates the image specified in opts.

func (*Client) RegisterBuildpack

func (c *Client) RegisterBuildpack(ctx context.Context, opts RegisterBuildpackOptions) error

RegisterBuildpack updates the Buildpack Registry with to include a new buildpack specified in the opts argument

func (*Client) YankBuildpack

func (c *Client) YankBuildpack(opts YankBuildpackOptions) error

YankBuildpack marks a buildpack on the Buildpack Registry as 'yanked'. This forbids future builds from using it.

type ClientOption

type ClientOption func(c *Client)

ClientOption is a type of function that mutate settings on the client. Values in these functions are set through currying.

func WithCacheDir

func WithCacheDir(path string) ClientOption

Deprecated: use WithDownloader instead.

WithCacheDir supply your own cache directory.

func WithDockerClient

func WithDockerClient(docker dockerClient.CommonAPIClient) ClientOption

WithDockerClient supply your own docker client.

func WithDownloader

func WithDownloader(d Downloader) ClientOption

WithDownloader supply your own downloader. A Downloader is used to gather buildpacks from both remote urls, or local sources.

func WithExperimental

func WithExperimental(experimental bool) ClientOption

WithExperimental sets whether experimental features should be enabled.

func WithFetcher

func WithFetcher(f ImageFetcher) ClientOption

WithFetcher supply your own Fetcher. A Fetcher retrieves both local and remote images to make them available.

func WithImageFactory

func WithImageFactory(f ImageFactory) ClientOption

WithImageFactory supply your own image factory.

func WithLogger

func WithLogger(l logging.Logger) ClientOption

WithLogger supply your own logger.

type ContainerConfig

type ContainerConfig struct {
	// Configure network settings of the build containers.
	// The value of Network is handed directly to the docker client.
	// For valid values of this field see:
	// https://docs.docker.com/network/#network-drivers
	Network string

	// Volumes are accessible during both detect build phases
	// should have the form: /path/in/host:/path/in/container.
	// For more about volume mounts, and their permissions see:
	// https://docs.docker.com/storage/volumes/
	//
	// It is strongly recommended you do not override any of the
	// paths with volume mounts at the following locations:
	// - /cnb
	// - /layers
	// - anything below /cnb/**
	Volumes []string
}

ContainerConfig is additional configuration of the docker container that all build steps occur within.

type CreateBuilderOptions

type CreateBuilderOptions struct {
	// The base directory to use to resolve relative assets
	RelativeBaseDir string

	// Name of the builder.
	BuilderName string

	// Configuration that defines the functionality a builder provides.
	Config pubbldr.Config

	// Skip building image locally, directly publish to a registry.
	// Requires BuilderName to be a valid registry location.
	Publish bool

	// Buildpack registry name. Defines where all registry buildpacks will be pulled from.
	Registry string

	// Strategy for updating images before a build.
	PullPolicy config.PullPolicy
}

CreateBuilderOptions is a configuration object used to change the behavior of CreateBuilder.

type Downloader

type Downloader interface {
	// Download collects both local and remote assets and provides a blob object
	// used to read asset contents.
	Download(ctx context.Context, pathOrURI string) (blob.Blob, error)
}

Downloader is an interface for collecting both remote and local assets.

type ExperimentError

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

ExperimentError denotes that an experimental feature was trying to be used without experimental features enabled.

func NewExperimentError

func NewExperimentError(msg string) ExperimentError

func (ExperimentError) Error

func (ee ExperimentError) Error() string

type ImageFactory

type ImageFactory interface {
	// NewImage initializes an image object with required settings so that it
	// can be written either locally or to a registry.
	NewImage(repoName string, local bool, imageOS string) (imgutil.Image, error)
}

ImageFactory is an interface representing the ability to create a new OCI image.

type ImageFetcher

type ImageFetcher interface {
	// Fetch fetches an image by resolving it both remotely and locally depending on provided parameters.
	// The pull behavior is dictated by the pullPolicy, which can have the following behavior
	//   - PullNever: try to use the daemon to return a `local.Image`.
	//   - PullIfNotPResent: try look to use the daemon to return a `local.Image`, if none is found  fetch a remote image.
	//   - PullAlways: it will only try to fetch a remote image.
	//
	// These PullPolicies that these interact with the daemon argument.
	// PullIfNotPresent and daemon = false, gives us the same behavior as PullAlways.
	// There is a single invalid configuration, PullNever and daemon = false, this will always fail.
	Fetch(ctx context.Context, name string, daemon bool, pullPolicy pubcfg.PullPolicy) (imgutil.Image, error)
}

ImageFetcher is an interface representing the ability to fetch local and images.

type ImageInfo

type ImageInfo struct {
	// Stack Identifier used when building this image
	StackID string

	// List of buildpacks that passed detection, ran their build
	// phases and made a contribution to this image.
	Buildpacks []buildpack.GroupBuildpack

	// Base includes two references to the run image,
	// - the Run Image ID,
	// - the hash of the last layer in the app image that belongs to the run image.
	// A way to visualize this is given an image with n layers:
	//
	// last layer in run image
	//          v
	// [1, ..., k, k+1, ..., n]
	//              ^
	//   first layer added by buildpacks
	//
	// the first 1 to k layers all belong to the run image,
	// the last k+1 to n layers are added by buildpacks.
	// the sum of all of these is our app image.
	Base platform.RunImageMetadata

	// BOM or Bill of materials, contains dependency and
	// version information provided by each buildpack.
	BOM []buildpack.BOMEntry

	// Stack includes the run image name, and a list of image mirrors,
	// where the run image is hosted.
	Stack platform.StackMetadata

	// Processes lists all processes contributed by buildpacks.
	Processes ProcessDetails
}

ImageInfo is a collection of metadata describing an app image built using Cloud Native Buildpacks.

type ImgWrapper

type ImgWrapper struct {
	v1.ImageConfig
}

func (ImgWrapper) Label

func (iw ImgWrapper) Label(name string) (string, error)

type InspectBuildpackOptions

type InspectBuildpackOptions struct {
	BuildpackName string
	Daemon        bool
	Registry      string
}

type LifecycleExecutor

type LifecycleExecutor interface {
	// Execute is responsible for invoking each of these binaries
	// with the desired configuration.
	Execute(ctx context.Context, opts build.LifecycleOptions) error
}

LifecycleExecutor executes the lifecycle which satisfies the Cloud Native Buildpacks Lifecycle specification. Implementations of the Lifecycle must execute the following phases by calling the phase-specific lifecycle binary in order:

Detection:         /cnb/lifecycle/detector
Analysis:          /cnb/lifecycle/analyzer
Cache Restoration: /cnb/lifecycle/restorer
Build:             /cnb/lifecycle/builder
Export:            /cnb/lifecycle/exporter

or invoke the single creator binary:

Creator:            /cnb/lifecycle/creator

type NewBuildpackOptions

type NewBuildpackOptions struct {
	// api compat version of the output buildpack artifact.
	API string

	// The base directory to generate assets
	Path string

	// The ID of the output buildpack artifact.
	ID string

	// version of the output buildpack artifact.
	Version string

	// The stacks this buildpack will work with
	Stacks []dist.Stack
}

type PackageBuildpackOptions

type PackageBuildpackOptions struct {
	// The base director to resolve relative assest from
	RelativeBaseDir string

	// The name of the output buildpack artifact.
	Name string

	// Type of output format, The options are the either the const FormatImage, or FormatFile.
	Format string

	// Defines the Buildpacks configuration.
	Config pubbldpkg.Config

	// Push resulting builder image up to a registry
	// specified in the Name variable.
	Publish bool

	// Strategy for updating images before packaging.
	PullPolicy config.PullPolicy

	// Name of the buildpack registry. Used to
	// add buildpacks to a package.
	Registry string
}

PackageBuildpackOptions is a configuration object used to define the behavior of PackageBuildpack.

type ProcessDetails

type ProcessDetails struct {
	// An Images default start command.
	DefaultProcess *launch.Process

	// List of all start commands contributed by buildpacks.
	OtherProcesses []launch.Process
}

ProcessDetails is a collection of all start command metadata on an image.

type ProxyConfig

type ProxyConfig struct {
	HTTPProxy  string // Used to set HTTP_PROXY env var.
	HTTPSProxy string // Used to set HTTPS_PROXY env var.
	NoProxy    string // Used to set NO_PROXY env var.
}

ProxyConfig specifies proxy setting to be set as environment variables in a container.

type PullBuildpackOptions

type PullBuildpackOptions struct {
	// URI of the buildpack to retrieve.
	URI string
	// RegistryName to search for buildpacks from.
	RegistryName string
	// RelativeBaseDir to resolve relative assests from.
	RelativeBaseDir string
}

PullBuildpackOptions are options available for PullBuildpack

type RebaseOptions

type RebaseOptions struct {
	// Name of image we wish to rebase.
	RepoName string

	// Flag to publish image to remote registry after rebase completion.
	Publish bool

	// Strategy for pulling images during rebase.
	PullPolicy config.PullPolicy

	// Image to rebase against. This image must have
	// the same StackID as the previous run image.
	RunImage string

	// A mapping from StackID to an array of mirrors.
	// This mapping used only if both RunImage is omitted and Publish is true.
	// AdditionalMirrors gives us inputs to recalculate the 'best' run image
	// based on the registry we are publishing to.
	AdditionalMirrors map[string][]string
}

RebaseOptions is a configuration struct that controls image rebase behavior.

type RegisterBuildpackOptions

type RegisterBuildpackOptions struct {
	ImageName string
	Type      string
	URL       string
	Name      string
}

RegisterBuildpackOptions is a configuration struct that controls the behavior of the RegisterBuildpack function.

type SoftError

type SoftError struct{}

SoftError is an error that is not intended to be displayed.

func NewSoftError

func NewSoftError() SoftError

func (SoftError) Error

func (se SoftError) Error() string

type YankBuildpackOptions

type YankBuildpackOptions struct {
	ID      string
	Version string
	Type    string
	URL     string
	Yank    bool
}

YankBuildpackOptions is a configuration struct that controls the Yanking a buildpack from the Buildpack Registry.