pack

package module
v1.5.5 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2021 License: Apache-2.0 Imports: 43 Imported by: 0

README

pack - Buildpack CLI

Build results Go Report Card codecov GoDoc GitHub license Slack

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/YousefHaggyHeroku/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:18",
		"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")
}

Output:

Index

Examples

Constants

View Source 
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"
)

Variables

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

Functions

func DownloadBuildpack added in v1.0.0 

func DownloadBuildpack(buildpackURI string, registryName string, logger logging.Logger) (dist.Buildpack, []dist.Buildpack, error)

TODO: Specific error message

Types

type BuildOptions added in v0.9.1 

type BuildOptions struct {
	// 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

	// 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 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

	// 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

	// Filter files from the application source.
	// If true include file, otherwise exclude.
	FileFilter func(string) bool

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

BuildOptions defines configuration settings for a Build.

type BuilderInfo added in v0.9.1 

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 added in v0.9.1 

type BuilderInspectionConfig struct {
	OrderDetectionDepth int
}

type BuilderInspectionModifier added in v0.9.1 

type BuilderInspectionModifier func(config *BuilderInspectionConfig)

func WithDetectionOrderDepth added in v0.9.1 

func WithDetectionOrderDepth(depth int) BuilderInspectionModifier

type BuildpackInfo added in v0.9.1 

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

type BuildpackInfoKey added in v0.9.1 

type BuildpackInfoKey struct {
	ID      string
	Version string
}

BuildpackInfoKey contains all information needed to determine buildpack equivalence.

type Client added in v0.9.1 

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 added in v0.9.1 

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

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

func (*Client) Build added in v0.9.1 

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 added in v0.9.1 

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 added in v0.9.1 

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 added in v0.9.1 

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

Must return an BuildpackNotFoundError

func (*Client) InspectImage added in v0.9.1 

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) PackageBuildpack added in v0.9.1 

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

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

func (*Client) Rebase added in v0.9.1 

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 added in v0.9.1 

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 added in v0.9.1 

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 added in v0.9.1 

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 deprecated added in v0.9.1 

func WithCacheDir(path string) ClientOption

Deprecated: use WithDownloader instead.

WithCacheDir supply your own cache directory.

func WithDockerClient added in v0.9.1 

func WithDockerClient(docker dockerClient.CommonAPIClient) ClientOption

WithDockerClient supply your own docker client.

func WithDownloader added in v0.9.1 

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 added in v0.9.1 

func WithExperimental(experimental bool) ClientOption

WithExperimental sets whether experimental features should be enabled.

func WithFetcher added in v0.9.1 

func WithFetcher(f ImageFetcher) ClientOption

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

func WithImageFactory added in v0.9.1 

func WithImageFactory(f ImageFactory) ClientOption

WithImageFactory supply your own image factory.

func WithLogger added in v0.9.1 

func WithLogger(l logging.Logger) ClientOption

WithLogger supply your own logger.

type ContainerConfig added in v0.9.1 

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 added in v0.9.1 

type CreateBuilderOptions struct {
	// 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 added in v0.9.1 

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 added in v0.9.1 

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 added in v0.9.1 

func NewExperimentError(msg string) ExperimentError

func (ExperimentError) Error added in v0.9.1 

func (ee ExperimentError) Error() string

type ImageFactory added in v0.9.1 

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) (imgutil.Image, error)
}

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

type ImageFetcher added in v0.9.1 

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 added in v0.9.1 

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 []lifecycle.Buildpack

	// 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 lifecycle.RunImageMetadata

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

	// Stack includes the run image name, and a list of image mirrors,
	// where the run image is hosted.
	Stack lifecycle.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 added in v0.9.1 

type ImgWrapper struct {
	v1.ImageConfig
}

func (ImgWrapper) Label added in v0.9.1 

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

type InspectBuildpackOptions added in v0.9.1 

type InspectBuildpackOptions struct {
	BuildpackName string
	Daemon        bool
	Registry      string
}

type LifecycleExecutor added in v0.9.1 

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 PackageBuildpackOptions added in v0.9.1 

type PackageBuildpackOptions struct {
	// 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
}

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

type ProcessDetails added in v0.9.1 

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 added in v0.9.1 

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 RebaseOptions added in v0.9.1 

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 added in v0.9.1 

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 added in v0.9.1 

type SoftError struct{}

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

func NewSoftError added in v0.9.1 

func NewSoftError() SoftError

func (SoftError) Error added in v0.9.1 

func (se SoftError) Error() string

type YankBuildpackOptions added in v0.9.1 

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
pack
internal
archive
blob
build
build/fakes
builder
builder/fakes
builder/testmocks
Package testmocks is a generated GoMock package.
 Package testmocks is a generated GoMock package.
builder/writer
buildpackage
cache
commands
commands/fakes
commands/stack
commands/testmocks
Package testmocks is a generated GoMock package.
 Package testmocks is a generated GoMock package.
config
container
dist
dist/testmocks
Package testmocks is a generated GoMock package.
 Package testmocks is a generated GoMock package.
fakes
image
layer
logging
Package logging implements the logger for the pack CLI.
 Package logging implements the logger for the pack CLI.
paths
registry
slices
stack
stringset
style
Package logging defines the minimal interface that loggers must support to be used by pack.
 Package logging defines the minimal interface that loggers must support to be used by pack.
comparehelpers
Package testmocks is a generated GoMock package.
 Package testmocks 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.