pack

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2019 License: Apache-2.0 Imports: 29 Imported by: 0

README

pack - Buildpack CLI Travis Build Status

pack makes it easy for

  • Application developers to use Cloud Native Buildpacks to convert code into runnable images
  • Buildpack authors to develop and package buildpacks for distribution

⚔️ It's dangerous to go alone! Read this. 🛠️

Ready to embark on your adventure with pack but not sure where to start? Try out our tutorial, An App's Brief Journey from Source to Image.

Otherwise, read the rest of this document for detailed explanations and examples of pack's most important commands.

Contents

Building app images using build

pack build enables app developers to create runnable app images from source code using buildpacks.

$ pack build <image-name>
Example: Building using the default builder image

In the following example, an app image is created from Node.js application source code.

$ cd path/to/node/app
$ pack build my-app:my-tag

In this case, the default builder (essentially, an image containing buildpacks) is used, and an appropriate buildpack is automatically selected from the builder based on the app source code.

You can change the default builder using the set-default-builder command.

Alternately, you can ignore the default and use a specific builder with the build command's --builder flag.

To publish the produced image to an image registry, include the --publish flag:

$ pack build registry.example.com/my-app:my-tag --publish
Example: Building using a specified buildpack

In the following example, an app image is created from Node.js application source code, using a buildpack chosen by the user.

$ cd path/to/node/app
$ pack build my-app:my-tag --buildpack path/to/some/buildpack

The --buildpack parameter can be

  • a path to a directory, or
  • the ID of a buildpack located in a builder

Multiple buildpacks can be specified, in order, by:

  • supplying --buildpack multiple times, or
  • supplying a comma-separated list to --buildpack (without spaces)
Building explained

build diagram

To create an app image, build executes one or more buildpacks against the app's source code. Each buildpack inspects the source code and provides relevant dependencies. An image is then generated from the app's source code and these dependencies.

Buildpacks are compatible with one or more stacks. A stack designates a build image and a run image. During the build process, a stack's build image becomes the environment in which buildpacks are executed, and its run image becomes the base for the final app image. For more information on working with stacks, see the Managing stacks section.

Buildpacks can be bundled together with a specific stack's build image, resulting in a builder image (note the "er" ending). Builders provide the most convenient way to distribute buildpacks for a given stack. For more information on working with builders, see the Working with builders using create-builder section.

Updating app images using rebase

The pack rebase command allows app developers to rapidly update an app image when its stack's run image has changed. By using image layer rebasing, this command avoids the need to fully rebuild the app.

$ pack rebase <image-name>
Example: Rebasing an app image

Consider an app image my-app:my-tag that was originally built using the default builder. That builder's stack has a run image called pack/run. Running the following will update the base of my-app:my-tag with the latest version of pack/run.

$ pack rebase my-app:my-tag

Like build, rebase has a --publish flag that can be used to publish the updated app image to a registry.

Rebasing explained

rebase diagram

At its core, image rebasing is a simple process. By inspecting an app image, rebase can determine whether or not a newer version of the app's base image exists (either locally or in a registry). If so, rebase updates the app image's layer metadata to reference the newer base image version.

Working with builders using create-builder

pack create-builder enables buildpack authors and platform operators to bundle a collection of buildpacks into a single image for distribution and use with a specified stack.

$ pack create-builder <image-name> --builder-config <path-to-builder-toml>
Example: Creating a builder from buildpacks

In this example, a builder image is created from buildpacks org.example.buildpack-1 and org.example.buildpack-2. A TOML file (typically named builder.toml) provides necessary configuration to the command.

[[buildpacks]]
  id = "org.example.buildpack-1"
  uri = "relative/path/to/buildpack-1" # URIs without schemes are read as paths relative to builder.toml

[[buildpacks]]
  id = "org.example.buildpack-2"
  uri = "https://example.org/buildpacks/buildpack-2.tgz"

[[groups]]
  [[groups.buildpacks]]
    id = "org.example.buildpack-1"
    version = "0.0.1"
  
  [[groups.buildpacks]]
    id = "org.example.buildpack-2"
    version = "0.0.1"

[stack]
  id = "com.example.stack"
  build-image = "example/build"
  run-image = "example/run"

For more information on stacks, see the Managing stacks section.

Running create-builder while supplying this configuration file will produce the builder image.

$ pack create-builder my-builder:my-tag --builder-config path/to/builder.toml

Like build, create-builder has a --publish flag that can be used to publish the generated builder image to a registry.

The builder can then be used in build by running:

$ pack build my-app:my-tag --builder my-builder:my-tag --buildpack org.example.buildpack-1
Builders explained

create-builder diagram

A builder is an image containing a collection of buildpack groups that will be executed against app source code, in the order that they appear in builder.toml. This image's base will be the build image associated with a given stack.

A buildpack's primary role is to inspect the source code, determine any dependencies that will be required to compile and/or run the app, and provide runtime dependencies as layers in the final app image.

It's important to note that the buildpacks in a builder are not actually executed until build is run.

Managing stacks

As mentioned previously, a stack is a named association of a build image and a run image. Stacks are managed through a builder's TOML file:

[[buildpacks]]
  # ...

[[groups]]
  # ...

[stack]
  id = "com.example.stack"
  build-image = "example/build"
  run-image = "example/run"
  run-image-mirrors = ["gcr.io/example/run", "registry.example.com/example/run"]

By providing the required [stack] section, a builder author can configure a stack's ID, build image, and run image (including any mirrors).

Run image mirrors

Run image mirrors provide alternate locations for run images, for use during build (or rebase). When running build with a builder containing run image mirrors, pack will select a run image whose registry location matches that of the specified app image (if no registry host is specified in the image name, DockerHub is assumed). This is useful when publishing the resulting app image (via the --publish flag or via docker push), as the app's base image (i.e. run image) will be located on the same registry as the app image itself, reducing the amount of data transfer required to push the app image.

In the following example, assuming a builder configured with the example TOML above, the selected run image will be registry.example.com/example/run.

$ pack build registry.example.com/example/app

while naming the app without a registry specified, example/app, will cause example/run to be selected as the app's run image.

$ pack build example/app

For local development, it's often helpful to override the run image mirrors in a builder. For this, the set-run-image-mirrors command can be used. This command does not modify the builder, and instead configures the user's local machine.

To see what run images are configured for a builder, the inspect-builder command can be used. inspect-builder will output built-in and locally-configured run images for a given builder, among other useful information. The order of the run images in the output denotes the order in which they will be matched during build.

Resources

Development

Building

To build pack, run:

go build ./cmd/pack

This project uses go modules

Testing

To run unit and integration tests:

$ go test

To run acceptance tests:

$ go test -tags=acceptance ./acceptance/...

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Build 

func Build(ctx context.Context, outWriter, errWriter io.Writer, appDir, builderImage, runImage, repoName string, publish, clearCache bool) error

func RepositoryName added in v0.1.0 

func RepositoryName(logger *logging.Logger, buildFlags *BuildFlags) (string, error)

func Run added in v0.0.5 

func Run(ctx context.Context, outWriter, errWriter io.Writer, appDir, buildImage, runImage string, ports []string) error

Types

type BuildConfig added in v0.0.4 

type BuildConfig struct {
	Builder    string
	RunImage   string
	RepoName   string
	Publish    bool
	ClearCache bool
	// Above are copied from BuildFlags are set by init
	Cli    Docker
	Logger *logging.Logger
	Config *config.Config
	// Above are copied from BuildFactory
	Cache           Cache
	LifecycleConfig build.LifecycleConfig
}

func (*BuildConfig) Run added in v0.0.4 

func (b *BuildConfig) Run(ctx context.Context) error

type BuildFactory added in v0.0.4 

type BuildFactory struct {
	Cli     Docker
	Logger  *logging.Logger
	Config  *config.Config
	Cache   Cache
	Fetcher Fetcher
}

func DefaultBuildFactory added in v0.0.4 

func DefaultBuildFactory(logger *logging.Logger, cache Cache, dockerClient Docker, fetcher Fetcher) (*BuildFactory, error)

func (*BuildFactory) BuildConfigFromFlags added in v0.0.4 

func (bf *BuildFactory) BuildConfigFromFlags(ctx context.Context, f *BuildFlags) (*BuildConfig, error)

func (*BuildFactory) RunConfigFromFlags added in v0.0.5 

func (bf *BuildFactory) RunConfigFromFlags(ctx context.Context, f *RunFlags) (*RunConfig, error)

type BuildFlags added in v0.0.2 

type BuildFlags struct {
	AppDir     string
	Builder    string
	RunImage   string
	Env        []string
	EnvFile    string
	RepoName   string
	Publish    bool
	NoPull     bool
	ClearCache bool
	Buildpacks []string
}

type BuildRunner added in v0.1.0 

type BuildRunner interface {
	Run(context.Context) error
}

This interface same as BuildConfig

type BuilderConfig added in v0.0.3 

type BuilderConfig struct {
	Buildpacks      []buildpack.Buildpack
	Groups          []lifecycle.BuildpackGroup
	Repo            lcimg.Image
	BuilderDir      string // original location of builder.toml, used for interpreting relative paths in buildpack URIs
	RunImage        string
	RunImageMirrors []string
}

type BuilderFactory added in v0.0.2 

type BuilderFactory struct {
	Logger  *logging.Logger
	Config  *config.Config
	Fetcher Fetcher
}

func (*BuilderFactory) BuilderConfigFromFlags added in v0.0.4 

func (f *BuilderFactory) BuilderConfigFromFlags(ctx context.Context, flags CreateBuilderFlags) (BuilderConfig, error)

func (*BuilderFactory) Create added in v0.0.2 

func (f *BuilderFactory) Create(config BuilderConfig) error

type BuilderInfo added in v0.1.0 

type BuilderInfo struct {
	Stack                string
	RunImage             string
	RunImageMirrors      []string
	LocalRunImageMirrors []string
	Buildpacks           []BuildpackInfo
	Groups               [][]BuildpackInfo
}

type BuildpackData added in v0.0.5 

type BuildpackData struct {
	BP struct {
		ID      string `toml:"id"`
		Version string `toml:"version"`
	} `toml:"buildpack"`
}

type BuildpackInfo added in v0.1.0 

type BuildpackInfo struct {
	ID      string
	Version string
	Latest  bool
}

type Cache added in v0.1.0 

type Cache interface {
	Clear(context.Context) error
	Image() string
}

type Client added in v0.1.0 

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

func NewClient added in v0.1.0 

func NewClient(config *config.Config, fetcher Fetcher) *Client

func (*Client) InspectBuilder added in v0.1.0 

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

type CreateBuilderFlags added in v0.0.2 

type CreateBuilderFlags struct {
	RepoName        string
	BuilderTomlPath string
	Publish         bool
	NoPull          bool
}

type Docker added in v0.0.4 

type Docker interface {
	RunContainer(ctx context.Context, id string, stdout io.Writer, stderr io.Writer) error
	VolumeRemove(ctx context.Context, volumeID string, force bool) error
	ContainerCreate(ctx context.Context, config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig, containerName string) (container.ContainerCreateCreatedBody, error)
	ContainerRemove(ctx context.Context, containerID string, options types.ContainerRemoveOptions) error
	ContainerList(ctx context.Context, options types.ContainerListOptions) ([]types.Container, error)
	CopyToContainer(ctx context.Context, containerID, dstPath string, content io.Reader, options types.CopyToContainerOptions) error
	CopyFromContainer(ctx context.Context, containerID, srcPath string) (io.ReadCloser, types.ContainerPathStat, error)
	ImageBuild(ctx context.Context, buildContext io.Reader, options types.ImageBuildOptions) (types.ImageBuildResponse, error)
	ImageInspectWithRaw(ctx context.Context, imageID string) (types.ImageInspect, []byte, error)
	ImageRemove(ctx context.Context, imageID string, options types.ImageRemoveOptions) ([]types.ImageDeleteResponseItem, error)
	PullImage(ctx context.Context, imageID string, stdout io.Writer) error
}

type Fetcher added in v0.1.0 

type Fetcher interface {
	FetchUpdatedLocalImage(context.Context, string, io.Writer) (image.Image, error)
	FetchLocalImage(string) (image.Image, error)
	FetchRemoteImage(string) (image.Image, error)
}

type ImageFactory added in v0.0.6 

type ImageFactory interface {
	NewLocal(string) (image.Image, error)
	NewRemote(string) (image.Image, error)
}

type ImageFetcher added in v0.1.0 

type ImageFetcher struct {
	Docker  Docker
	Factory ImageFactory
}

func (*ImageFetcher) FetchLocalImage added in v0.1.0 

func (f *ImageFetcher) FetchLocalImage(imageName string) (image.Image, error)

func (*ImageFetcher) FetchRemoteImage added in v0.1.0 

func (f *ImageFetcher) FetchRemoteImage(imageName string) (image.Image, error)

func (*ImageFetcher) FetchUpdatedLocalImage added in v0.1.0 

func (f *ImageFetcher) FetchUpdatedLocalImage(ctx context.Context, imageName string, stdout io.Writer) (image.Image, error)

type RebaseConfig added in v0.0.5 

type RebaseConfig struct {
	Image        image.Image
	NewBaseImage image.Image
}

type RebaseFactory added in v0.0.5 

type RebaseFactory struct {
	Logger  *logging.Logger
	Config  *config.Config
	Fetcher Fetcher
}

func (*RebaseFactory) Rebase added in v0.0.5 

func (f *RebaseFactory) Rebase(cfg RebaseConfig) error

func (*RebaseFactory) RebaseConfigFromFlags added in v0.0.5 

func (f *RebaseFactory) RebaseConfigFromFlags(ctx context.Context, flags RebaseFlags) (RebaseConfig, error)

type RebaseFlags added in v0.0.5 

type RebaseFlags struct {
	RepoName string
	Publish  bool
	NoPull   bool
	RunImage string
}

type RunConfig added in v0.0.5 

type RunConfig struct {
	Ports []string
	Build BuildRunner
	// All below are from BuildConfig
	RepoName string
	Cli      Docker
	Logger   *logging.Logger
}

func (*RunConfig) Run added in v0.0.5 

func (r *RunConfig) Run(ctx context.Context) error

type RunFlags added in v0.0.5 

type RunFlags struct {
	BuildFlags BuildFlags
	Ports      []string
}

type Task added in v0.0.5 

type Task interface {
	Run(context context.Context) error
}

type WritableStore added in v0.0.5 

type WritableStore interface {
	Write(image v1.Image) error
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
pack command
mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

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.