Documentation ¶
Overview ¶
Package llblib provides utilities to facilitate common usage patterns and helper functions when interacting with buildkit as a client.
Index ¶
- Variables
- func AddCacheMounts(paths []string, id string, mode llb.CacheMountSharingMode) llb.RunOption
- func AddEnvs(envs map[string]string) llb.StateOption
- func Digest(st llb.State) (digest.Digest, error)
- func DockerConf(dockerDir string) string
- func DockerDir(ctx context.Context) string
- func DockerHost(ctx context.Context) (string, error)
- func Dockerfile(dockerfile []byte, buildContext llb.State, opts ...DockerfileOption) llb.State
- func ErrUnimplemented(err error) bool
- func File(a *llb.FileAction, opts ...llb.ConstraintsOpt) llb.StateOption
- func Frontend(source string, opts ...FrontendOption) llb.State
- func Getenv(ctx context.Context, key string) (value string)
- func IgnoreCache() llb.RunOption
- func IncludePatterns(p []string) llb.CopyOption
- func LoadImageResolver(ctx context.Context) llb.ImageMetaResolver
- func LoadProgress(ctx context.Context) progress.Progress
- func LookupEnv(ctx context.Context, key string) (value string, ok bool)
- func NewClient(ctx context.Context, addr string, opts ...client.ClientOpt) (*client.Client, error)
- func ResolvedImage(ref string, opts ...llb.ImageOption) llb.State
- func ToYAML(ctx context.Context, states ...llb.State) (*yaml.Node, error)
- func WithEnv(ctx context.Context, key, value string) context.Context
- func WithImageResolver(ctx context.Context, r llb.ImageMetaResolver) context.Context
- func WithProgress(ctx context.Context, p progress.Progress) context.Context
- func WithSession(ctx context.Context, s Session) context.Context
- type Chmod
- type ContainerOption
- func DropBuildError(b bool) ContainerOption
- func WithInput(in io.Reader) ContainerOption
- func WithOutput(out, err io.Writer) ContainerOption
- func WithRun(opts ...llb.RunOption) ContainerOption
- func WithSetup(s func(ctx context.Context) error) ContainerOption
- func WithTTY(in FdReader, outW, errW io.Writer) ContainerOption
- func WithTeardown(t func() error) ContainerOption
- type ContainerOptions
- type DockerfileOption
- type DockerfileOpts
- type FdReader
- type ForwardOption
- type FrontendOption
- type MountPropagator
- type NullOption
- func (NullOption) SetConstraintsOption(*llb.Constraints)
- func (NullOption) SetCopyOption(*llb.CopyInfo)
- func (NullOption) SetDockerfileOption(*DockerfileOpts)
- func (NullOption) SetFrontendOption(*frontendOptions)
- func (NullOption) SetGitOption(*llb.GitInfo)
- func (NullOption) SetHTTPOption(*llb.HTTPInfo)
- func (NullOption) SetImageOption(*llb.ImageInfo)
- func (NullOption) SetLocalOption(*llb.LocalInfo)
- func (NullOption) SetMkdirOption(*llb.MkdirInfo)
- func (NullOption) SetMkfileOption(*llb.MkfileInfo)
- func (NullOption) SetOCILayoutOption(*llb.OCILayoutInfo)
- func (NullOption) SetRequestOption(*Request)
- func (NullOption) SetRmOption(*llb.RmInfo)
- func (NullOption) SetRunOption(*llb.ExecInfo)
- func (NullOption) SetSSHOption(*llb.SSHInfo)
- func (NullOption) SetSecretOption(*llb.SecretInfo)
- func (NullOption) SetSolverOption(*solver)
- func (NullOption) SetTmpfsOption(*llb.TmpfsInfo)
- func (NullOption) State(s llb.State) llb.State
- type Request
- type RequestOption
- type RunOptions
- type Session
- type Solver
- type SolverOption
- type WithInsecure
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 DockerConf ¶
DockerConf returns the path to the user's Docker config.json.
func DockerDir ¶
DockerDir returns the path to the user's Docker config dir. Reads DOCKER_CONFIG, and HOME env vars.
func DockerHost ¶
DockerHost returns the value of the DOCKER_HOST env var, or the default.
func Dockerfile ¶
Dockerfile will parse the provided dockerfile and construct an llb.State represented by the provided dockerfile instructions.
func ErrUnimplemented ¶
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 IgnoreCache ¶
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 ¶
LoadProgress returns a progress stored on the context, or a no-op progress.
func LookupEnv ¶
LookupEnv will fetch a env var stored on the context or default to calling os.LookupEnv
func NewClient ¶
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 ¶
ToYAML will serialize the llb.States to a yaml sequence node where each node in the sequence represents the corresponding states passed in.
func WithImageResolver ¶
WithImageResolver returns a context with the provided llb.ImageMetaResovler stored.
func WithProgress ¶
WithProgress returns a context with the provided Progress stored.
Types ¶
type Chmod ¶
Chmod is a wrapper over os.FileMode to implement various llb options.
func (Chmod) SetCopyOption ¶
SetCopyOption implements the llb.CopyOption interface.
func (Chmod) SetSSHOption ¶
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 ForwardOption ¶
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)
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 WithLabel ¶
func WithLabel(l string) RequestOption
WithLabel can be used to set the label used for the progress display of the request.
type RunOptions ¶
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 ¶
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`.
type WithInsecure ¶
type WithInsecure struct{}
WithInsecure will modify the request to ensure the solve request has the `Insecure` entitlement provided.
func (WithInsecure) SetContainerOptions ¶
func (WithInsecure) SetContainerOptions(co *ContainerOptions)
SetContainerOptions implements ContainerOption
func (WithInsecure) SetRequestOption ¶
func (WithInsecure) SetRequestOption(r *Request)
SetRequestOption implements RequestOption
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. |