client

package
v0.29.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2023 License: Apache-2.0 Imports: 57 Imported by: 10

Documentation

Overview

Package client provides all the functionally provided by pack as a library through a go api.

Prerequisites

In order to use most functionality, you will need an OCI runtime such as Docker or podman installed.

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.

Index

Constants

View Source 
const (
	Local = iota
	Remote
)
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"

	// CNBExtension is the file extension for a cloud native buildpack tar archive
	CNBExtension = ".cnb"
)
View Source 
const DockerAPIVersion = "1.38"

Variables

View Source 
var IsSuggestedBuilderFunc = func(b string) bool {
	for _, suggestedBuilder := range builder.SuggestedBuilders {
		if b == suggestedBuilder.Image {
			return true
		}
	}
	return false
}

Functions

This section is empty.

Types

type BlobDownloader 

type BlobDownloader 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)
}

BlobDownloader is an interface for collecting both remote and local assets as blobs.

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

	// Used to configure various cache available options
	Cache cache.CacheOpts

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

	// Launch a terminal UI to depict the build process
	Interactive 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 image.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 projectTypes.Descriptor

	// List of buildpack images or archives to add to a builder.
	// these buildpacks will be prepended to the builder's order
	PreBuildpacks []string

	// List of buildpack images or archives to add to a builder.
	// these buildpacks will be appended to the builder's order
	PostBuildpacks []string

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

	// User's group id used to build the image
	GroupID int

	// A previous image to set to a particular tag reference, digest reference, or (when performing a daemon build) image ID;
	PreviousImage string

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

	// Directory to output any SBOM artifacts
	SBOMDestinationDir string

	// Directory to output the report.toml metadata artifact
	ReportDestinationDir string

	// Desired create time in the output image config
	CreationTime *time.Time
}

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.ModuleInfo

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

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

	// All extensions included within the builder.
	Extensions []dist.ModuleInfo

	// Detailed ordering of extensions.
	OrderExtensions pubbldr.DetectionOrder
}

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

type BuilderInspectionConfig 

type BuilderInspectionConfig struct {
	OrderDetectionDepth int
}

type BuilderInspectionModifier 

type BuilderInspectionModifier func(config *BuilderInspectionConfig)

func WithDetectionOrderDepth 

func WithDetectionOrderDepth(depth int) BuilderInspectionModifier

type BuildpackDownloader 

type BuildpackDownloader interface {
	// Download parses a buildpack URI and downloads the buildpack and any dependencies buildpacks from the appropriate source
	Download(ctx context.Context, buildpackURI string, opts buildpack.DownloadOptions) (buildpack.BuildModule, []buildpack.BuildModule, error)
}

BuildpackDownloader is an interface for downloading and extracting buildpacks from various sources

type BuildpackInfo 

type BuildpackInfo struct {
	BuildpackMetadata buildpack.Metadata
	Buildpacks        []dist.ModuleInfo
	Order             dist.Order
	BuildpackLayers   dist.ModuleLayers
	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 ...Option) (*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) DownloadSBOM added in v0.24.0 

func (c *Client) DownloadSBOM(name string, options DownloadSBOMOptions) error

DownloadSBOM pulls SBOM layer from an image. It reads the SBOM metadata of an image then pulls the corresponding diffId, if it exists

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) InspectExtension added in v0.29.0 

func (c *Client) InspectExtension(opts InspectExtensionOptions) (*ExtensionInfo, 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) Version 

func (c *Client) Version() string

Version returns the version of the client

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 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 image.PullPolicy
}

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

type DockerClient added in v0.29.0 

type DockerClient interface {
	ImageInspectWithRaw(ctx context.Context, image string) (types.ImageInspect, []byte, error)
	ImageTag(ctx context.Context, image, ref string) error
	ImageLoad(ctx context.Context, input io.Reader, quiet bool) (types.ImageLoadResponse, error)
	ImageSave(ctx context.Context, images []string) (io.ReadCloser, error)
	ImageRemove(ctx context.Context, image string, options types.ImageRemoveOptions) ([]types.ImageDeleteResponseItem, error)
	ImagePull(ctx context.Context, ref string, options types.ImagePullOptions) (io.ReadCloser, error)
	Info(ctx context.Context) (types.Info, error)
	VolumeRemove(ctx context.Context, volumeID string, force bool) error
	ContainerCreate(ctx context.Context, config *containertypes.Config, hostConfig *containertypes.HostConfig, networkingConfig *networktypes.NetworkingConfig, platform *specs.Platform, containerName string) (containertypes.ContainerCreateCreatedBody, error)
	CopyFromContainer(ctx context.Context, container, srcPath string) (io.ReadCloser, types.ContainerPathStat, error)
	ContainerInspect(ctx context.Context, container string) (types.ContainerJSON, error)
	ContainerRemove(ctx context.Context, container string, options types.ContainerRemoveOptions) error
	CopyToContainer(ctx context.Context, container, path string, content io.Reader, options types.CopyToContainerOptions) error
	ContainerWait(ctx context.Context, container string, condition containertypes.WaitCondition) (<-chan containertypes.ContainerWaitOKBody, <-chan error)
	ContainerAttach(ctx context.Context, container string, options types.ContainerAttachOptions) (types.HijackedResponse, error)
	ContainerStart(ctx context.Context, container string, options types.ContainerStartOptions) error
}

DockerClient is the subset of CommonAPIClient which required by this package

type DownloadSBOMOptions added in v0.24.0 

type DownloadSBOMOptions struct {
	Daemon         bool
	DestinationDir string
}

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

type ExtensionInfo struct {
	Extension dist.ModuleInfo
	Location  buildpack.LocatorType
}

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

ImageFetcher is an interface representing the ability to fetch local and remote 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.GroupElement

	// List of extensions that passed detection, ran their generate
	// phases and made a contribution to this image.
	Extensions []buildpack.GroupElement

	// 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 InspectExtensionOptions added in v0.29.0 

type InspectExtensionOptions struct {
	ExtensionName string
	Daemon        bool
}

type IsTrustedBuilder 

type IsTrustedBuilder func(string) bool

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 Option 

type Option func(c *Client)

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

func WithBuildpackDownloader 

func WithBuildpackDownloader(d BuildpackDownloader) Option

WithBuildpackDownloader supply your own BuildpackDownloader. A BuildpackDownloader is used to gather buildpacks from both remote urls, or local sources.

func WithCacheDir deprecated 

func WithCacheDir(path string) Option

Deprecated: use WithDownloader instead.

WithCacheDir supply your own cache directory.

func WithDockerClient 

func WithDockerClient(docker DockerClient) Option

WithDockerClient supply your own docker client.

func WithDownloader 

func WithDownloader(d BlobDownloader) Option

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) Option

WithExperimental sets whether experimental features should be enabled.

func WithFetcher 

func WithFetcher(f ImageFetcher) Option

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

func WithImageFactory 

func WithImageFactory(f ImageFactory) Option

WithImageFactory supply your own image factory.

func WithKeychain 

func WithKeychain(keychain authn.Keychain) Option

WithKeychain sets keychain of credentials to image registries

func WithLogger 

func WithLogger(l logging.Logger) Option

WithLogger supply your own logger.

func WithRegistryMirrors 

func WithRegistryMirrors(registryMirrors map[string]string) Option

WithRegistryMirrors sets mirrors to pull images from.

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 image.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 image.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

	// If provided, directory to which report.toml will be copied
	ReportDestinationDir 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.

Source Files

View all Source files

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.