llblib

package module
v0.0.0-...-97e4c78 Latest Latest
Warning

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

 Go to latest Published: Mar 21, 2024 License: Apache-2.0 Imports: 53 Imported by: 0

README

Go Reference

llblib - Client library for moby/buildkit

This library facilitates using the Buildkit LLB client interfaces to dynamically create build graphs with Buildkit.

For usage please see the examples.

Documentation

Overview

Package llblib provides utilities to facilitate common usage patterns and helper functions when interacting with buildkit as a client.

Index

Constants

This section is empty.

Variables

View Source 
var CopyDirContentsOnly = copyOptionFunc(func(ci *llb.CopyInfo) {
	ci.CopyDirContentsOnly = true
})

CopyDirContentsOnly is an llb.CopyOption to indicate that the contents of the src directory should be copied, rather than the directory itself.

Functions

func AddCacheMounts 

func AddCacheMounts(paths []string, id string, mode llb.CacheMountSharingMode) llb.RunOption

AddCacheMounts is a helper function that calls llb.AddMount with the llb.AsPersistentCacheDir option with the provided mode. The mount ID will be the id argument + the path being added.

func AddEnvs 

func AddEnvs(envs map[string]string) llb.StateOption

AddEnvs is a helper function over `llb.AddEnv` where the provided map will be added to the returned llb.StateOption. The env vars are applied in key sort order to allow for a consistent state for caching.

func Digest 

func Digest(st llb.State) (digest.Digest, error)

Digest returns the digest for the state.

func DockerConf 

func DockerConf(dockerDir string) string

DockerConf returns the path to the user's Docker config.json.

func DockerDir 

func DockerDir(ctx context.Context) string

DockerDir returns the path to the user's Docker config dir. Reads DOCKER_CONFIG, and HOME env vars.

func DockerHost 

func DockerHost(ctx context.Context) (string, error)

DockerHost returns the value of the DOCKER_HOST env var, or the default.

func Dockerfile 

func Dockerfile(dockerfile []byte, buildContext llb.State, opts ...DockerfileOption) llb.State

Dockerfile will parse the provided dockerfile and construct an llb.State represented by the provided dockerfile instructions.

func ErrUnimplemented 

func ErrUnimplemented(err error) bool

ErrUnimplemented will return true if the provided error is a GRPC error and the GRPC status code matches `codes.Unimplemented`.

func File 

func File(a *llb.FileAction, opts ...llb.ConstraintsOpt) llb.StateOption

File implements an llb.StateOption where the provided llb.FileAction is applied to the llb.State.

func Frontend 

func Frontend(source string, opts ...FrontendOption) llb.State

Frontend will create an llb.State that is created via a frontend Request. One common frontend is the `docker/dockerfile` frontend that is used by `docker buildx` commands. The `source` argument is the image ref that is run as the frontend. A Frontend request is the same as using the `#syntax` directive in a Dockerfile. For example: 

image := llblib.Frontend("docker/dockerfile",
	llblib.FrontendInput("context", context),
	llblib.FrontendInput("dockerfile", dockerfile),
)

func Getenv 

func Getenv(ctx context.Context, key string) (value string)

Getenv will fetch an env var stored on the context or default to calling os.Getenv

func IgnoreCache 

func IgnoreCache() llb.RunOption

IgnoreCache can be used to invalidate existing cache for the Run operation forcing the Run operation to be executed again. This allows the result state to be reused within the session. This is different from `llb.IgnoreCache` in that `llb.IgnoreCache` will prevent any cache from being written from the state, so the Run operation will be executed multiple times within a session if the session evaluates the same vertex multiple times.

func IncludePatterns 

func IncludePatterns(p []string) llb.CopyOption

IncludePatterns provides a llb.CopyOption that sets the provided patterns on the llb.Copy instruction.

func LoadImageResolver 

func LoadImageResolver(ctx context.Context) llb.ImageMetaResolver

LoadImageResolver returns a llb.ImageMetaResolver stored on the context, or will return `nil` if no resolver is found.

func LoadProgress 

func LoadProgress(ctx context.Context) progress.Progress

LoadProgress returns a progress stored on the context, or a no-op progress.

func LookupEnv 

func LookupEnv(ctx context.Context, key string) (value string, ok bool)

LookupEnv will fetch a env var stored on the context or default to calling os.LookupEnv

func NewClient 

func NewClient(ctx context.Context, addr string, opts ...client.ClientOpt) (*client.Client, error)

NewClient will return a new buildkit client. It will verify the client connection by calling the client.Info function when available, otherwise will call client.ListWorkers. If the provided addr is empty, we attempt to use the buildkit service running in your local docker daemon.

To use the latest buildkit you can run buildkit via docker or run your own service deployment. To run via docker first start the container: 

docker run -d --name buildkitd --privileged moby/buildkit:latest

Then use this `addr` value: `docker-container://buildkitd`

func ResolvedImage 

func ResolvedImage(ref string, opts ...llb.ImageOption) llb.State

ResolvedImage returns an llb.State where the image will be resolved with the image configuration applied to the state. The resolved image digest will also be applied to the state to ensure this state is always consistent during the solve execution. Note that `WithImageResolver` should be used on the context provided to the buildkit solve requests, otherwise an un-resolved llb.Image will be used.

func ToYAML 

func ToYAML(ctx context.Context, states ...llb.State) (*yaml.Node, error)

ToYAML will serialize the llb.States to a yaml sequence node where each node in the sequence represents the corresponding states passed in.

func WithEnv 

func WithEnv(ctx context.Context, key, value string) context.Context

WithEnv is used to set env vars on a context.

func WithImageResolver 

func WithImageResolver(ctx context.Context, r llb.ImageMetaResolver) context.Context

WithImageResolver returns a context with the provided llb.ImageMetaResovler stored.

func WithProgress 

func WithProgress(ctx context.Context, p progress.Progress) context.Context

WithProgress returns a context with the provided Progress stored.

func WithSession 

func WithSession(ctx context.Context, s Session) context.Context

WithSession returns a context with the provided session stored.

Types

type Chmod 

type Chmod os.FileMode

Chmod is a wrapper over os.FileMode to implement various llb options.

func WithChmod 

func WithChmod(mode os.FileMode) Chmod

WithChmod creates a Chmod option with the provided os.FileMode.

func (Chmod) SetCopyOption 

func (c Chmod) SetCopyOption(ci *llb.CopyInfo)

SetCopyOption implements the llb.CopyOption interface.

func (Chmod) SetSSHOption 

func (c Chmod) SetSSHOption(si *llb.SSHInfo)

SetSSHOption implements the llb.SSHOption and ForwardOption interfaces.

func (Chmod) SetSecretOption 

func (c Chmod) SetSecretOption(si *llb.SecretInfo)

SetSecretOption implements the llb.SecretOption interface.

type ContainerOption 

type ContainerOption interface {
	SetContainerOptions(*ContainerOptions)
}

ContainerOption allows configuring an ad-hoc container.

func DropBuildError 

func DropBuildError(b bool) ContainerOption

DropBuildError will cause OnError handlers to suppress the original error that triggered the OnError event.

func WithInput 

func WithInput(in io.Reader) ContainerOption

WithInput will set stdin in the container to the provided reader.

func WithOutput 

func WithOutput(out, err io.Writer) ContainerOption

WithOutput will set the stdout and stderr in the container to the provided writers.

func WithRun 

func WithRun(opts ...llb.RunOption) ContainerOption

WithRun will apply the provide llb.RunOption to the container process. This can be used to set the command to be run and mounts etc. 

llblib.WithRun(
	llb.AddMount("/", llb.Image("busybox", llb.LinuxArm64)),
	llb.Args([]string{"/bin/sh"}),
)

func WithSetup 

func WithSetup(s func(ctx context.Context) error) ContainerOption

WithSetup can be used to start callbacks after the container process has started.

func WithTTY 

func WithTTY(in FdReader, outW, errW io.Writer) ContainerOption

WithTTY will run the container with the provided in/out/err connected to the tty in the container. Resize events will automatically be propagated.

func WithTeardown 

func WithTeardown(t func() error) ContainerOption

WithTeardown can be used to cleanup resources after the container process has exited.

type ContainerOptions 

type ContainerOptions struct {
	// NewContainerRequest describes the state of the container to be created.
	gateway.NewContainerRequest
	// StartRequest describes the process to be run (pid 1) in the container.
	gateway.StartRequest
	// Resize is used to send tty resize events
	Resize <-chan gateway.WinSize
	// Signal is used to send signals to the pid 1 process
	Signal <-chan syscall.Signal
	// Setup are callbacks that will be executed after the pid 1 process has
	// started.
	Setup []func(context.Context) error
	// Teardown are callbacks that are executed after the pid 1 has exited
	Teardown []func() error
	// contains filtered or unexported fields
}

ContainerOptions are options used to create ad-hoc containers in buildkit.

type DockerfileOption 

type DockerfileOption interface {
	SetDockerfileOption(*dockerfileOpts)
}

DockerfileOption can be used to modify a Dockerfile request.

func WithBuildArg 

func WithBuildArg(k, v string) DockerfileOption

WithBuildArg can be used to set build args for the Dockerfile build.

func WithBuildContext 

func WithBuildContext(name string, st llb.State) DockerfileOption

WithBuildContext will set an additional build context for the Dockerfile build.

func WithTarget 

func WithTarget(t string) DockerfileOption

WithTarget will set the target for the Dockerfile build.

func WithTargetPlatform 

func WithTargetPlatform(p *specsv1.Platform) DockerfileOption

WithTargetPlatform will set the platform for the Dockerfile build.

type DockerfileOpts 

type DockerfileOpts = dockerfile2llb.ConvertOpt

DockerfileOpts alias dockerfile2llb.ConvertOpt

type FdReader 

type FdReader interface {
	io.Reader
	Fd() uintptr
}

FdReader is an io.Reader that has a Fd file descriptor.

type ForwardOption 

type ForwardOption = llb.SSHOption

ForwardOption is the same as the llb.SSHOption, but renamed since it can be used without SSH for generic forwarding of tcp and unix sockets.

type FrontendOption 

type FrontendOption interface {
	SetFrontendOption(*frontendOptions)
}

FrontendOption can be used to modify a Frontend request.

func FrontendInput 

func FrontendInput(name string, st llb.State) FrontendOption

FrontendInput will attach the provided llb.State with the given name to the Frontend request.

func FrontendOpt 

func FrontendOpt(name, value string) FrontendOption

FrontendOpt will add the name/value pair to the Opts for the Frontend request.

func WithCustomName 

func WithCustomName(name string) FrontendOption

WithCustomName allows using the provided text for the progress display when solving the Frontend request.

type MountPropagator 

type MountPropagator interface {
	// Add will append a RunOption to the list of propagated options.
	Add(...llb.RunOption)
	// ApplyMount will apply the provide llb.StateOptions to the mount at
	// `mountpoint`.  If there is no mount present matching `mountpoint` then a
	// new llb.Scratch will be created and the llb.StateOptions will be applied
	// to that state.
	ApplyMount(mountpoint string, opts ...llb.StateOption)
	// ApplyRoot will apply the provided llb.StateOptions to the root mount.
	ApplyRoot(...llb.StateOption)
	// AsRun is used to extract the current state of all mounts (and associated
	// RunOptions via Add) so that they can be applied to an `llb.Run`
	// operation.
	AsRun() llb.RunOption
	// Copy creates a new MountPropagator with copies of the parents RunOptions
	// and llb.States.  Note that the RunOptions and llb.States themselves are
	// only shallow copied.
	Copy() MountPropagator
	// GetMount returns the llb.State for the modified mount found at
	// `mountpoint`.  If the mountpoint is not found, then llb.Scratch will
	// returned and `ok` will be set to false.
	GetMount(mountpoint string) (state llb.State, ok bool)
	// Run will mutate the state by applying the Run to the root and mountpoints
	// while preserving any changes for future Run statements.
	Run(...llb.RunOption)
	// Root will return the llb.State for the modified root "/" mount.
	Root() llb.State
}

MountPropagator manages a collection of llb.States and run Mounts. As Runs are applies to the MountPropagator the modified state of the root and all attached mounts are propagated such that future Runs will see changes made by prior Runs.

func Persistent 

func Persistent(root llb.State, opts ...llb.RunOption) MountPropagator

Persistent returns a MountPropagator for the provided root llb.State and any mounts found in the llb.RunOptions.

type NullOption 

type NullOption struct{}

NullOption implements a generic no-op option for all of the option interfaces.

func (NullOption) SetConstraintsOption 

func (NullOption) SetConstraintsOption(*llb.Constraints)

func (NullOption) SetCopyOption 

func (NullOption) SetCopyOption(*llb.CopyInfo)

func (NullOption) SetDockerfileOption 

func (NullOption) SetDockerfileOption(*DockerfileOpts)

func (NullOption) SetFrontendOption 

func (NullOption) SetFrontendOption(*frontendOptions)

func (NullOption) SetGitOption 

func (NullOption) SetGitOption(*llb.GitInfo)

func (NullOption) SetHTTPOption 

func (NullOption) SetHTTPOption(*llb.HTTPInfo)

func (NullOption) SetImageOption 

func (NullOption) SetImageOption(*llb.ImageInfo)

func (NullOption) SetLocalOption 

func (NullOption) SetLocalOption(*llb.LocalInfo)

func (NullOption) SetMkdirOption 

func (NullOption) SetMkdirOption(*llb.MkdirInfo)

func (NullOption) SetMkfileOption 

func (NullOption) SetMkfileOption(*llb.MkfileInfo)

func (NullOption) SetOCILayoutOption 

func (NullOption) SetOCILayoutOption(*llb.OCILayoutInfo)

func (NullOption) SetRequestOption 

func (NullOption) SetRequestOption(*Request)

func (NullOption) SetRmOption 

func (NullOption) SetRmOption(*llb.RmInfo)

func (NullOption) SetRunOption 

func (NullOption) SetRunOption(*llb.ExecInfo)

func (NullOption) SetSSHOption 

func (NullOption) SetSSHOption(*llb.SSHInfo)

func (NullOption) SetSecretOption 

func (NullOption) SetSecretOption(*llb.SecretInfo)

func (NullOption) SetSolverOption 

func (NullOption) SetSolverOption(*solver)

func (NullOption) SetTmpfsOption 

func (NullOption) SetTmpfsOption(*llb.TmpfsInfo)

func (NullOption) State 

func (NullOption) State(s llb.State) llb.State

State implements llb.StateOption

type Request 

type Request struct {
	// Label can be set to add a prefix to the progress display for this
	// request.
	Label string
	// contains filtered or unexported fields
}

Request defines a buildkit request.

type RequestOption 

type RequestOption interface {
	SetRequestOption(*Request)
}

RequestOption can be used to modify the requests.

func Download 

func Download(localDir string) RequestOption

Download will trigger the buildkit exporter to export the solved state to the directory provided. Only one `Download` option can be provided per request.

func OnError 

func OnError(opts ...ContainerOption) RequestOption

OnError can be used to modify a Request to run a customized container with with the mount context from the failed buildkit request. This can be used for special handling of solves that are not "exportable" from buildkit since buildkit will not export a failed solve request. For example to get a shell in a container with the same modified "dirty" state of the files post 

llblib.OnError(
	llblib.WithTTY(os.Stdin, os.Stdout, os.Stderr),
	llblib.WithRun(llb.Args([]string{"/bin/sh"})),
)

func WithInsecure 

func WithInsecure() RequestOption

WithInsecure will modify the request to ensure the solve request has the `Insecure` entitlement provided.

func WithLabel 

func WithLabel(l string) RequestOption

WithLabel can be used to set the label used for the progress display of the request.

type RunOptions 

type RunOptions []llb.RunOption

RunOptions is a helper to return a list of llb.RunOptions as a single llb.RunOption.

func (RunOptions) SetRunOption 

func (ro RunOptions) SetRunOption(ei *llb.ExecInfo)

SetRunOption implements the llb.RunOption interface for RunOptions

type Session 

type Session interface {
	// Do will attempt execute the provided request
	Do(ctx context.Context, req Request) (*client.SolveResponse, error)
	// ToYAML will serialize the requests to a yaml sequence to assist in
	// debugging or visualizing the solve requests.
	ToYAML(ctx context.Context, reqs ...Request) (*yaml.Node, error)
	// Release will ensure resources are released for the session.
	Release() error
}

Session provides a long running session used to solve requests.

func LoadSession 

func LoadSession(ctx context.Context) Session

LoadSession returns a session stored on the context, or nil.

type Solver 

type Solver interface {
	// AddSecretFile will add a secret file to the solve request and session.
	AddSecretFile(src, dest string, opts ...llb.SecretOption) llb.RunOption
	// Forward will add a forwarding proxy to the solve request and the session.
	// The `src` must be either formatted like `tcp://[host](:[port])` or
	// `unix://[path]`.  `dest` is the file location for the forwarded unix
	// domain socket in the build container.
	Forward(src, dest string, opts ...ForwardOption) llb.RunOption
	// Local will add a local directory to the solve request and session.
	Local(name string, opts ...llb.LocalOption) llb.State

	// Build creates a solve request that can be executed by the session
	// returned from `NewSession“.  Note that any Requests created after
	// `NewSession` will possibly be invalid, all requests should be generated
	// with `Build` BEFORE calling `NewSession`.
	Build(st llb.State, opts ...RequestOption) Request
	// Container will create a solve requests to run an ad-hoc container on the
	// buildkit service.
	Container(root llb.State, opts ...ContainerOption) Request

	// NewSession will return a session to used to send the solve requests to
	// buildkit.  Note that `Release` MUST be called on the returned `Session`
	// to free resources.
	NewSession(ctx context.Context, cln *client.Client, p progress.Progress) (Session, error)

	// ImageResolver returns an llb.ImageMetaResolver to resolve images.  The
	// resolver will use a common cache for all image lookups done via this
	// solver.
	ImageResolver(cln *client.Client, p progress.Progress) llb.ImageMetaResolver
}

Solver provides functions used to create and execute buildkit solve requests.

func NewSolver 

func NewSolver(opts ...SolverOption) Solver

NewSolver returns a new Solver to create buildkit requests.

type SolverOption 

type SolverOption interface {
	SetSolverOption(*solver)
}

SolverOption can be used to modify how solve requests are generated.

func WithCwd 

func WithCwd(cwd string) SolverOption

WithCwd sets the working directory used when relative paths are provided to the `Solver`.

Source Files

View all Source files

Directories

Path Synopsis
examples
build
Package main demonstrates running a reasonably complex Go build with with persistent caching, and then using llblib.Download to export the results of the build to the local directory.
 Package main demonstrates running a reasonably complex Go build with with persistent caching, and then using llblib.Download to export the results of the build to the local directory.
container
Package main demonstrates running an ad-hoc container on the buildkit service using a combination of various mount sources.
 Package main demonstrates running an ad-hoc container on the buildkit service using a combination of various mount sources.
docker
Package main demonstrates how to use llblib.Dockerfile to solve a Dockerfile This is roughly equivalent to running `docker build .` where the Dockerfile is using `#syntax docker/dockerfile`.
 Package main demonstrates how to use llblib.Dockerfile to solve a Dockerfile This is roughly equivalent to running `docker build .` where the Dockerfile is using `#syntax docker/dockerfile`.
docker-fail
Package main demonstrates using llblib.OnError on get a shell in the modified state of a failed docker build using a request built with llblib.Frontend.
 Package main demonstrates using llblib.OnError on get a shell in the modified state of a failed docker build using a request built with llblib.Frontend.
fail
Package main demonstrates llblib.OnError handling to run a command in the modified state of a failed solve request.
 Package main demonstrates llblib.OnError handling to run a command in the modified state of a failed solve request.
forward
Package main demonstrates using llblib.Forward to allow the buildkit solve to connect to a service running on your local host.
 Package main demonstrates using llblib.Forward to allow the buildkit solve to connect to a service running on your local host.
frontend
Package main demonstrates how to use llblib.Frontend to solve a Dockerfile This is roughly equivalent to running `docker build .` where the Dockerfile is using `#syntax docker/dockerfile`.
 Package main demonstrates how to use llblib.Frontend to solve a Dockerfile This is roughly equivalent to running `docker build .` where the Dockerfile is using `#syntax docker/dockerfile`.
Package progress provides a multiplexed buildkit progress display that can be used across multiple solves.
 Package progress provides a multiplexed buildkit progress display that can be used across multiple solves.
Package sockproxy will provide a tcp forwarding proxy as a buildkit session Attachable.
 Package sockproxy will provide a tcp forwarding proxy as a buildkit session Attachable.

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.