Skip to content

Commit

Permalink
Make changes requested in review
Browse files Browse the repository at this point in the history 
Signed-off-by: dwillist <dthornton@vmware.com>
  • Loading branch information
@dwillist
dwillist committed Aug 14, 2020
1 parent 9faa2b8 commit a3600a8
Show file tree
Hide file tree
Showing 11 changed files with 127 additions and 89 deletions.
84 changes: 50 additions & 34 deletions build.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ import (
)

const (
// the lifecycle image that will be used for the analysis and export phases
// when using an untrusted builder
// The lifecycle image that will be used for the analysis, restore and export phases
// when using an untrusted builder.
lifecycleImageRepo = "buildpacksio/lifecycle"
minLifecycleVersionSupportingCreator = "0.7.4"
prevLifecycleVersionSupportingImage = "0.6.1"
Expand All @@ -51,15 +51,20 @@ const (
// Cache Restoration: /cnb/lifecycle/restorer
// Build: /cnb/lifecycle/builder
// Export: /cnb/lifecycle/exporter
//
// or invoke the single creator binary:
//
// Creator: /cnb/lifecycle/creator
//
type Lifecycle interface {
// Execute is responsible for invoking each of these binaries,
// Execute is responsible for invoking each of these binaries
// with the desired configuration.
Execute(ctx context.Context, opts build.LifecycleOptions) error
}

// BuildOptions defines configuration settings for a Build.
type BuildOptions struct {
// required. Name of output image
// required. Name of output image.
Image string

// required. Builder image name.
Expand All @@ -69,33 +74,39 @@ type BuildOptions struct {
// add buildpacks to a build.
Registry string

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

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

// If Run Image is empty, it is set to the the 'best' mirror using Builder metadata and AdditionalMirrors.
// where 'best' is defined as:
// - if the builder or Additional mirrors has a registry that matches the registry in
// Image, it is 'best'
// - otherwise if there are no matches, use the builder metadata
// 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.
// User provided environment variables to the buildpacks.
// Buildpacks may both read and overwrite these values.
Env map[string]string

// option passed to lifecycle,
// publishes Image directly to a remote registry.
// 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

// TrustBuild when true optimizes builds by running
// all lifecycle phases in a single container,
// this places registry credentials on the builder's build image.
// 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

Expand All @@ -106,25 +117,24 @@ type BuildOptions struct {

// 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.
// and will not be used if proxy env vars are already set.
ProxyConfig *ProxyConfig

// Configure network and volume mounts for the build containers
// 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
// If true include file, otherwise exclude.
FileFilter func(string) bool

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

// ProxyConfig specifies proxy setting to be set as environment variables in a container
// ProxyConfig specifies proxy setting to be set as environment variables in a container.
type ProxyConfig struct {
HTTPProxy string // Used to set HTTP_PROXY env var.
HTTPSProxy string // Used to set HTTPS_PROXY env var.
Expand All @@ -134,23 +144,29 @@ type ProxyConfig struct {
// Additional configuration of the docker container that all build steps
// occur within.
type ContainerConfig struct {
// Configure network settings of the build container
// this string value is handed directly to the docker client,
// for valid values of this field see:
// 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 that mounted and accessible during detect & build phases
// should have the form: /path/in/host:/path/in/container
// for more about volume mounts, and their permissions see
// 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
}

// Build configures the 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 of the lifecycle phases fail,
// it will return an 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 (c *Client) Build(ctx context.Context, opts BuildOptions) error {
imageRef, err := c.parseTagReference(opts.Image)
if err != nil {
Expand Down
22 changes: 12 additions & 10 deletions client.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ type ImageFetcher interface {

//go:generate mockgen -package testmocks -destination testmocks/mock_downloader.go github.com/buildpacks/pack Downloader

// Downloader is an interface for collecting both remote and local assets
// Downloader is an interface for collecting both remote and local assets.
type Downloader interface {
// Download collects both local and remote assets and provides a blob object
// used to read asset contents.
Expand All @@ -43,13 +43,14 @@ type Downloader interface {

// ImageFactory is an interface representing the ability to create a new OCI image.
type ImageFactory interface {
// NewImage initialize of an image object with required settings so that it
// can be written to either a local or remote registry.
// 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)
}

// 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.
type Client struct {
logger logging.Logger
imageFetcher ImageFetcher
Expand All @@ -60,7 +61,8 @@ type Client struct {
experimental bool
}

// ClientOption is a type of function that mutate settings on the client
// ClientOption is a type of function that mutate settings on the client.
// Values in these functions are set through currying.
type ClientOption func(c *Client)

// WithLogger supply your own logger.
Expand All @@ -77,25 +79,25 @@ func WithImageFactory(f ImageFactory) ClientOption {
}
}

// WithFetcher supply your own fetcher.
// A Fetcher retrieves both local and remote images to make them available
// WithFetcher supply your own Fetcher.
// A Fetcher retrieves both local and remote images to make them available.
func WithFetcher(f ImageFetcher) ClientOption {
return func(c *Client) {
c.imageFetcher = f
}
}

// WithDownloader supply your own downloader.
// A Downloader is used to gather buildpacks from both remote urls, or local sources
// A Downloader is used to gather buildpacks from both remote urls, or local sources.
func WithDownloader(d Downloader) ClientOption {
return func(c *Client) {
c.downloader = d
}
}

// WithCacheDir supply your own cache directory.
//
// Deprecated: use WithDownloader instead.
//
// WithCacheDir supply your own cache directory.
func WithCacheDir(path string) ClientOption {
return func(c *Client) {
c.downloader = blob.NewDownloader(c.logger, path)
Expand All @@ -109,7 +111,7 @@ func WithDockerClient(docker dockerClient.CommonAPIClient) ClientOption {
}
}

// WithExperimental sets whether experimental features should be enabled
// WithExperimental sets whether experimental features should be enabled.
func WithExperimental(experimental bool) ClientOption {
return func(c *Client) {
c.experimental = experimental
Expand Down
14 changes: 8 additions & 6 deletions create_builder.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,26 +20,28 @@ import (
"github.com/buildpacks/pack/internal/style"
)

// CreateBuilderOptions are options passed to CreateBuilder
// CreateBuilderOptions is a configuration object used to change the behavior of
// CreateBuilder.
type CreateBuilderOptions struct {
// Name of the builder
// Name of the builder.
BuilderName string

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

// Push resulting builder image up to Registry/BuilderName
// Skip building image locally, directly publish to a registry.
// Requires BuilderName to be a valid registry location.
Publish bool

// registry to save the final builder image to.
// Buildpack registry location. Defines where all registry buildpacks will be pulled from.
Registry string

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

// CreateBuilder creates and saves a builder image to a registry with the provided options.
// If configuration is invalid, will error and exit without writing any images.
// If any configuration is invalid, it will error and exit without creating any images.
func (c *Client) CreateBuilder(ctx context.Context, opts CreateBuilderOptions) error {
if err := c.validateConfig(ctx, opts); err != nil {
return err
Expand Down
2 changes: 1 addition & 1 deletion doc.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ of application source code, into a runnable OCI images.
Prerequisites
In order to use most pack functionality you will need to have Docker installed.
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
Expand Down
10 changes: 5 additions & 5 deletions doc_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import (
)

// This example shows the basic usage of the package: Create a client,
// Create a configuration object, Call the client's Build function.
// call a configuration object, call the client's Build function.
func Example_build() {
//create a context object
context := context.Background()
Expand All @@ -20,9 +20,9 @@ func Example_build() {
panic(err)
}

// please 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
// 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
Expand All @@ -45,7 +45,7 @@ func Example_build() {

fmt.Println("building application image")

// preform an image build
// build an image
err = client.Build(context, buildOpts)
if err != nil {
panic(err)
Expand Down
34 changes: 20 additions & 14 deletions inspect_builder.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,21 @@ import (
"github.com/buildpacks/pack/internal/style"
)

// BuilderInfo is a collection of metadata describing an builder created using pack.
// BuilderInfo is a collection of metadata describing a builder created using pack.
type BuilderInfo struct {
// Description of builder
// Human readable, description of a builder.
Description string

// stack name use by the builder
// Stack name used by the builder.
Stack string

// list of mixins provided by the Stack
// 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
// List of all run image mirrors a builder will use to provide
// the RunImage.
RunImageMirrors []string

Expand All @@ -36,27 +37,32 @@ type BuilderInfo struct {
// Top level ordering of buildpacks.
Order dist.Order

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

// metadata about the lifecycle Version this builder uses
// as well which platform API, and buildpack API this builder
// implements
// 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 the tooling used
// to create this builder.
// Name and Version information from tooling used
// to produce this builder.
CreatedBy builder.CreatorMetadata
}

// BuildpackInfoKey contains all needed information to determine if
// two buildpacks are equivalent.
// BuildpackInfoKey contains all information needed to determine
// buildpack equivalence.
type BuildpackInfoKey struct {
ID string
Version string
}

// InspectBuilder reads label metadata of a local builder image. Initializes a BuilderInfo
// object with this metadata, and returns it.
// 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 (c *Client) InspectBuilder(name string, daemon bool) (*BuilderInfo, error) {
img, err := c.imageFetcher.Fetch(context.Background(), name, daemon, config.PullNever)
if err != nil {
Expand Down
Loading

0 comments on commit a3600a8

Please sign in to comment.