pack

package module
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2018 License: Apache-2.0 Imports: 37 Imported by: 0

README

pack - Buildpack CLI Travis Build Status Windows Build status

pack makes it easy for

  • application developers to use buildpacks to convert code into runnable images
  • buildpack authors to develop and package buildpacks for distribution

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

# ... Detect, analyze and build output

Successfully built 2452b4b1fce1
Successfully tagged my-app:my-tag

In this case, the default builder is used, and an appropriate buildpack is automatically selected from the builder based on the app source code. To understand more about what builders are and how to create or use them, see the Working with builders using create-builder section.

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

$ pack build private-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

# ...
*** DETECTING WITH MANUALLY-PROVIDED GROUP:
2018/10/29 18:31:05 Group: Name Of Some Buildpack: pass
# ...

Successfully built 2452b4b1fce1
Successfully tagged my-app:my-tag

The message DETECTING WITH MANUALLY-PROVIDED GROUP indicates that the buildpack was chosen by the user, rather than by the automated detection process.

The --buildpack parameter can be

  • a path to a directory
  • a path to a .tgz file
  • a URL to a .tgz file, or
  • the ID of a buildpack located in a builder
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 builder.toml file 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"

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

2018/10/29 15:35:47 Pulling builder base image packs/build
2018/10/29 15:36:06 Successfully created builder image: my-builder:my-tag

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

The above example uses the default stack, whose build image is packs/build. The --stack parameter can be used to specify a different stack (currently, the only built-in stack is io.buildpacks.stacks.bionic). For more information about managing stacks and their associations with build and run images, see the Managing stacks section.

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 buildpacks that will be executed, in the order that they appear in builder.toml, against app source code. 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 those dependencies as layers in the resulting image. This image's base will be the build image associated with a given stack.

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 associated with a build image and a run image. Stacks in pack's configuration can be managed using the following commands:

$ pack add-stack <stack-name> --build-image <build-image-name> --run-image <run-image-name1,run-image-name2,...>

$ pack update-stack <stack-name> --build-image <build-image-name> --run-image <run-image-name1,run-image-name2,...>

$ pack delete-stack <stack-name>

$ pack set-default-stack <stack-name>

Technically, a stack can be associated with multiple run images, as a variant is needed for each registry to which an app image might be published when using --publish.

Example: Adding a stack

In this example, a new stack called org.example.my-stack is added and associated with build image my-stack/build and run image my-stack/run.

$ pack add-stack org.example.my-stack --build-image my-stack/build --run-image my-stack/run
Example: Updating a stack

In this example, an existing stack called org.example.my-stack is updated with a new build image my-stack/build:v2 and a new run image my-stack/run:v2.

$ pack add-stack org.example.my-stack --build-image my-stack/build:v2 --run-image my-stack/run:v2
Example: Deleting a stack

In this example, the existing stack org.example.my-stack is deleted from pack's configuration.

$ pack delete-stack org.example.my-stack
Example: Setting the default stack

In this example, the default stack, used by create-builder, is set to org.example.my-stack.

$ pack set-default-stack org.example.my-stack
Listing stacks

To inspect available stacks and their names (denoted by id), run:

$ cat ~/.pack/config.toml

...

[[stacks]]
  id = "io.buildpacks.stacks.bionic"
  build-images = ["packs/build"]
  run-images = ["packs/run"]

[[stacks]]
  id = "org.example.my-stack"
  build-images = ["my-stack/build"]
  run-images = ["my-stack/run"]

...

Note that this method of inspecting available stacks will soon be replaced by a new command. The format of config.toml is subject to change at any time.

Resources

Development

To run the tests, simply run:

$ go test

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Build 

func Build(appDir, buildImage, runImage, repoName string, publish bool) error

func Run added in v0.0.5 

func Run(appDir, buildImage, runImage, port string, makeStopCh func() <-chan struct{}) error

Types

type BuildConfig added in v0.0.4 

type BuildConfig struct {
	AppDir     string
	Builder    string
	RunImage   string
	EnvFile    map[string]string
	RepoName   string
	Publish    bool
	NoPull     bool
	Buildpacks []string
	// Above are copied from BuildFlags are set by init
	Cli    Docker
	Stdout io.Writer
	Stderr io.Writer
	Log    *log.Logger
	FS     FS
	Config *config.Config
	Images Images
	// Above are copied from BuildFactory
	WorkspaceVolume string
	CacheVolume     string
}

func (*BuildConfig) Analyze added in v0.0.4 

func (b *BuildConfig) Analyze() error

func (*BuildConfig) Build added in v0.0.4 

func (b *BuildConfig) Build() error

func (*BuildConfig) Detect added in v0.0.4 

func (b *BuildConfig) Detect() (*lifecycle.BuildpackGroup, error)

func (*BuildConfig) Export added in v0.0.4 

func (b *BuildConfig) Export(group *lifecycle.BuildpackGroup) error

func (*BuildConfig) Run added in v0.0.4 

func (b *BuildConfig) Run() error

type BuildFactory added in v0.0.4 

type BuildFactory struct {
	Cli    Docker
	Stdout io.Writer
	Stderr io.Writer
	Log    *log.Logger
	FS     FS
	Config *config.Config
	Images Images
}

func DefaultBuildFactory added in v0.0.4 

func DefaultBuildFactory() (*BuildFactory, error)

func (*BuildFactory) BuildConfigFromFlags added in v0.0.4 

func (bf *BuildFactory) BuildConfigFromFlags(f *BuildFlags) (*BuildConfig, error)

func (*BuildFactory) RunConfigFromFlags added in v0.0.5 

func (bf *BuildFactory) RunConfigFromFlags(f *RunFlags) (*RunConfig, error)

type BuildFlags added in v0.0.2 

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

type BuilderConfig added in v0.0.3 

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

type BuilderFactory added in v0.0.2 

type BuilderFactory struct {
	Log          *log.Logger
	FS           FS
	Config       *config.Config
	ImageFactory ImageFactory
}

func (*BuilderFactory) BuilderConfigFromFlags added in v0.0.4 

func (f *BuilderFactory) BuilderConfigFromFlags(flags CreateBuilderFlags) (BuilderConfig, error)

func (*BuilderFactory) Create added in v0.0.2 

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

type BuilderTOML added in v0.0.5 

type BuilderTOML struct {
	Buildpacks []Buildpack                `toml:"buildpacks"`
	Groups     []lifecycle.BuildpackGroup `toml:"groups"`
}

type Buildpack added in v0.0.2 

type Buildpack struct {
	ID      string `toml:"id"`
	URI     string `toml:"uri"`
	Latest  bool   `toml:"latest"`
	Dir     string
	Version string
}

type BuildpackData added in v0.0.5 

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

type CreateBuilderFlags added in v0.0.2 

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

type Docker added in v0.0.4 

type Docker interface {
	PullImage(ref string) error
	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
	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)
}

type FS added in v0.0.3 

type FS interface {
	CreateTarFile(tarFile, srcDir, tarDir string, uid, gid int) error
	CreateTarReader(srcDir, tarDir string, uid, gid int) (io.Reader, chan error)
	Untar(r io.Reader, dest string) error
	CreateSingleFileTar(path, txt string) (io.Reader, error)
}

type ImageFactory added in v0.0.6 

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

type Images added in v0.0.4 

type Images interface {
	ReadImage(repoName string, useDaemon bool) (v1.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 {
	Log          *log.Logger
	Config       *config.Config
	ImageFactory ImageFactory
}

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(flags RebaseFlags) (RebaseConfig, error)

type RebaseFlags added in v0.0.5 

type RebaseFlags struct {
	RepoName string
	Publish  bool
	NoPull   bool
}

type RunConfig added in v0.0.5 

type RunConfig struct {
	Port  string
	Build Task
	// All below are from BuildConfig
	RepoName string
	Cli      Docker
	Stdout   io.Writer
	Stderr   io.Writer
	Log      *log.Logger
}

func (*RunConfig) Run added in v0.0.5 

func (r *RunConfig) Run(makeStopCh func() <-chan struct{}) error

type RunFlags added in v0.0.5 

type RunFlags struct {
	BuildFlags BuildFlags
	Port       string
}

type Task added in v0.0.5 

type Task interface {
	Run() 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
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.