llb package - github.com/moby/buildkit/client/llb - Go Packages (original) (raw)

View Source

const ( GitAuthTokenKey = "GIT_AUTH_TOKEN" )

View Source

var ( LinuxAmd64 = Platform(ocispecs.Platform{OS: "linux", Architecture: "amd64"}) LinuxArmhf = Platform(ocispecs.Platform{OS: "linux", Architecture: "arm", Variant: "v7"}) LinuxArm = LinuxArmhf LinuxArmel = Platform(ocispecs.Platform{OS: "linux", Architecture: "arm", Variant: "v6"}) LinuxArm64 = Platform(ocispecs.Platform{OS: "linux", Architecture: "arm64"}) LinuxS390x = Platform(ocispecs.Platform{OS: "linux", Architecture: "s390x"}) LinuxPpc64 = Platform(ocispecs.Platform{OS: "linux", Architecture: "ppc64"}) LinuxPpc64le = Platform(ocispecs.Platform{OS: "linux", Architecture: "ppc64le"}) Darwin = Platform(ocispecs.Platform{OS: "darwin", Architecture: "amd64"}) Windows = Platform(ocispecs.Platform{OS: "windows", Architecture: "amd64"}) )

View Source

var CDIDeviceOptional = cdiDeviceOptionFunc(func(ci *CDIDeviceInfo) { ci.Optional = true })

View Source

var IgnoreCache = constraintsOptFunc(func(c *Constraints) { c.Metadata.IgnoreCache = true })

View Source

var MarkImageInternal = imageOptionFunc(func(ii *ImageInfo) { ii.RecordType = "internal" })

View Source

var SecretOptional = secretOptionFunc(func(si *SecretInfo) { si.Optional = true })

func ForceNoOutput(m *mount)

type AuthOption interface { GitOption HTTPOption }

AuthOption can be used with either HTTP or Git sources.

func AuthHeaderSecret(secretName string) AuthOption

AuthHeaderSecret returns an AuthOption that defines the name of a secret to use for HTTP based authentication.

type CDIDeviceInfo struct { Name string Optional bool }

type CDIDeviceOption interface { SetCDIDeviceOption(*CDIDeviceInfo) }

type CacheMountSharingMode int

const ( CacheMountShared CacheMountSharingMode = iota CacheMountPrivate CacheMountLocked )

func (co ChmodOpt) SetCopyOption(mi *CopyInfo)

type ChownOpt struct { User *UserOpt Group *UserOpt }

func (co ChownOpt) SetCopyOption(mi *CopyInfo)

func (co ChownOpt) SetMkdirOption(mi *MkdirInfo)

func (co ChownOpt) SetMkfileOption(mi *MkfileInfo)

func (co ChownOpt) SetSymlinkOption(si *SymlinkInfo)

type ChownOption interface { MkdirOption MkfileOption CopyOption SymlinkOption }

func WithUIDGID(uid, gid int) ChownOption

func NewConstraints(co ...ConstraintsOpt) *Constraints

type ConstraintsOpt interface { SetConstraintsOption(*Constraints) RunOption LocalOption HTTPOption ImageOption GitOption OCILayoutOption }

WithCaps exposes supported LLB caps to the marshaler

func WithExportCache() ConstraintsOpt

WithExportCache forces results for this vertex to be exported with the cache

func WithoutDefaultExportCache() ConstraintsOpt

WithoutDefaultExportCache resets the cache export for the vertex to use the default defined by the build configuration.

func WithoutExportCache() ConstraintsOpt

WithoutExportCache sets results for this vertex to be not exported with the cache

type CopyInfo struct { Mode *ChmodOpt FollowSymlinks bool CopyDirContentsOnly bool IncludePatterns []string ExcludePatterns []string AttemptUnpack bool CreateDestPath bool AllowWildcard bool AllowEmptyWildcard bool ChownOpt *ChownOpt CreatedTime *time.Time AlwaysReplaceExistingDestPaths bool }

func (mi *CopyInfo) SetCopyOption(mi2 *CopyInfo)

type CopyInput interface {

}

CopyInput is either llb.State or *FileActionWithState It is used by Copy to to specify the source of the copy operation.

type CopyOption interface { SetCopyOption(*CopyInfo) }

func WithExcludePatterns(patterns []string) CopyOption

func (c CreatedTime) SetCopyOption(mi *CopyInfo)

func (c CreatedTime) SetMkdirOption(mi *MkdirInfo)

func (c CreatedTime) SetMkfileOption(mi *MkfileInfo)

func (c CreatedTime) SetSymlinkOption(si *SymlinkInfo)

Definition is the LLB definition structure with per-vertex metadata entries Corresponds to the Definition structure defined in solver/pb.Definition.

type DefinitionOp struct {

}

DefinitionOp implements llb.Vertex using a marshalled definition.

For example, after marshalling a LLB state and sending over the wire, the LLB state can be reconstructed from the definition.

NewDefinitionOp returns a new operation from a marshalled definition.

func (d *DefinitionOp) Inputs() []Output

func (d *DefinitionOp) Output() Output

func NewDiff(lower, upper State, c Constraints) *DiffOp

func (m *DiffOp) Inputs() (out []Output)

func (m *DiffOp) Output() Output

type DifferInfo struct { Type DiffType Required bool }

func (e *EnvList) AddOrReplace(k, v string) *EnvList

type ExecInfo struct { State State Mounts []MountInfo ReadonlyRootFS bool ProxyEnv *ProxyEnv Secrets []SecretInfo SSH []SSHInfo CDIDevices []CDIDeviceInfo

}

func NewExecOp(base State, proxyEnv *ProxyEnv, readOnly bool, c Constraints) *ExecOp

func (e *ExecOp) AddMount(target string, source Output, opt ...MountOption) Output

func (e *ExecOp) Inputs() (inputs []Output)

func (e *ExecOp) Output() Output

type ExecState struct { State

}

func (e ExecState) AddMount(target string, source State, opt ...MountOption) State

func (e ExecState) Root() State

type FileAction struct {

}

FileAction is used to specify a file operation on a State. It can be used to create a directory, create a file, or remove a file, etc. This is used by State.FileTypically a FileAction is created by calling one of the helper functions such as Mkdir, Copy, Rm, Mkfile

func Copy(input CopyInput, src, dest string, opts ...CopyOption) *FileAction

Copy produces a FileAction which copies a file or directory from the source to the destination. The "input" parameter is the contents to copy from. "src" is the path to copy from within the "input". "dest" is the path to copy to within the destination (the state being operated on). See CopyInput for the valid types of input.

Example:

st := llb.Local(".") llb.Scratch().File(llb.Copy(st, "/foo", "/bar"))

The example copies the local (client) directory "./foo" to a new empty directory at /bar.

Note: Copying directories can have different behavior based on if the destination exists or not. When the destination already exists, the contents of the source directory is copied underneath the destination, including the directory itself. You may need to supply a copy option to copy the dir contents only. You may also need to pass in a CopyOption which creates parent directories if they do not exist.

See CopyOption for more details on what options are available.

Mkdir creates a FileAction which creates a directory at the given path. Example:

llb.Scratch().File(llb.Mkdir("/foo", 0755))

Mkfile creates a FileAction which creates a file at the given path with the provided contents. Example:

llb.Scratch().File(llb.Mkfile("/foo", 0644, []byte("hello world!")))

Rm creates a FileAction which removes a file or directory at the given path. Example:

llb.Scratch().File(Mkfile("/foo", 0644, []byte("not around for long..."))).File(llb.Rm("/foo"))

func Symlink(oldpath, newpath string, opts ...SymlinkOption) *FileAction

Symlink creates a symlink at `newpath` that points to `oldpath`

func (fa *FileAction) Copy(input CopyInput, src, dest string, opt ...CopyOption) *FileAction

func (fa *FileAction) Symlink(oldpath, newpath string, opt ...SymlinkOption) *FileAction

Symlink creates a symlink at `newpath` that points to `oldpath`

func (fa *FileAction) WithState(s State) CopyInput

type FileOp struct { MarshalCache

}

func NewFileOp(s State, action *FileAction, c Constraints) *FileOp

func (f *FileOp) Inputs() []Output

func (f *FileOp) Output() Output

type GitOption interface { SetGitOption(*GitInfo) }

func KeepGitDir() GitOption

type HTTPHeader struct { }

type HTTPOption interface { SetHTTPOption(*HTTPInfo) }

func Chown(uid, gid int) HTTPOption

func Header(header HTTPHeader) HTTPOption

Header returns an HTTPOption that ensures additional request headers will be sent when retrieving the HTTP source.

type ImageInfo struct { RecordType string

}

ImageMetaResolver can resolve image config metadata from a reference

type ImageOption interface { SetImageOption(*ImageInfo) }

func ResolveDigest(v bool) ImageOption

ResolveDigest uses the meta resolver to update the ref of image with full digest before marshaling. This makes image ref immutable and is recommended if you want to make sure meta resolver data matches the image used during the build.

func WithLayerLimit(l int) ImageOption

func WithMetaResolver(mr ImageMetaResolver) ImageOption

WithMetaResolver adds a metadata resolver to an image

type LocalOption interface { SetLocalOption(*LocalInfo) }

func Differ(t DiffType, required bool) LocalOption

func MetadataOnlyTransfer(exceptions []string) LocalOption

type MarshalCache struct {

}

func (mc *MarshalCache) Acquire() *MarshalCacheInstance

type MarshalCacheInstance struct { *MarshalCache }

func (mc *MarshalCacheInstance) Release()

func NewMerge(inputs []State, c Constraints) *MergeOp

func (m *MergeOp) Inputs() []Output

func (m *MergeOp) Output() Output

type MkdirInfo struct { MakeParents bool ChownOpt *ChownOpt CreatedTime *time.Time }

func (mi *MkdirInfo) SetMkdirOption(mi2 *MkdirInfo)

type MkdirOption interface { SetMkdirOption(*MkdirInfo) }

WithParents is an option for Mkdir which creates parent directories if they do not exist.

type MkfileInfo struct { ChownOpt *ChownOpt CreatedTime *time.Time }

func (mi *MkfileInfo) SetMkfileOption(mi2 *MkfileInfo)

type MkfileOption interface { SetMkfileOption(*MkfileInfo) }

type MountContentCache added in v0.13.0

type MountContentCache int

const ( MountContentCacheDefault MountContentCache = iota MountContentCacheOn MountContentCacheOff )

type MountInfo struct { Target string Source Output Opts []MountOption }

type MountOption func(*mount)

func AsPersistentCacheDir(id string, sharing CacheMountSharingMode) MountOption

func Tmpfs(opts ...TmpfsOption) MountOption

type OCILayoutInfo struct {

}

type OCILayoutOption interface { SetOCILayoutOption(*OCILayoutInfo) }

func OCILayerLimit(limit int) OCILayoutOption

type OpMetadata struct { IgnoreCache bool json:"ignore_cache,omitempty" Description map[string]string json:"description,omitempty" ExportCache *pb.ExportCache json:"export_cache,omitempty" Caps map[apicaps.CapID]bool json:"caps,omitempty" ProgressGroup *pb.ProgressGroup json:"progress_group,omitempty" }

OpMetadata has a more friendly interface for pb.OpMetadata.

const ( ResolveModeDefault ResolveMode = iota ResolveModeForcePull ResolveModePreferLocal )

func (r ResolveMode) SetImageOption(ii *ImageInfo)

type RmInfo struct { AllowNotFound bool AllowWildcard bool }

func (mi *RmInfo) SetRmOption(mi2 *RmInfo)

type RmOption interface { SetRmOption(*RmInfo) }

func WithAllowNotFound(b bool) RmOption

func WithAllowWildcard(b bool) RmOption

type RunOption interface { SetRunOption(es *ExecInfo) }

func AddCDIDevice(opts ...CDIDeviceOption) RunOption

func AddMount(dest string, mountState State, opts ...MountOption) RunOption

func AddSSHSocket(opts ...SSHOption) RunOption

AddSecret is a RunOption that adds a secret to the exec.

AddSecretWithDest is a RunOption that adds a secret to the exec with an optional destination.

func ReadonlyRootFS() RunOption

ReadonlyRootFS sets the execs's root filesystem to be read-only.

func ValidExitCodes(codes ...int) RunOption

func With(so ...StateOption) RunOption

func WithProxy(ps ProxyEnv) RunOption

WithProxy is a RunOption that sets the proxy environment variables in the resulting exec. For example `HTTP_PROXY` is a standard environment variable for unix systems that programs may read.

type SSHOption interface { SetSSHOption(*SSHInfo) }

func SSHSocketOpt(target string, uid, gid, mode int) SSHOption

func SSHSocketTarget(target string) SSHOption

type SecretOption interface { SetSecretOption(*SecretInfo) }

SecretAsEnv defines if the secret should be added as an environment variable

SecretAsEnvName defines if the secret should be added as an environment variable with the specified name

func SecretFileOpt(uid, gid, mode int) SecretOption

SecretFileOpt sets the secret's target file uid, gid and permissions.

type SourceLocation struct { SourceMap SourceMap Ranges []pb.Range }

type SourceMap struct { State *State Definition *Definition Filename string

Language [string](/builtin#string)
Data     [][byte](/builtin#byte)

}

SourceMap maps a source file/location to an LLB state/definition. SourceMaps are used to provide information for debugging and helpful error messages to the user. As an example, lets say you have a Dockerfile with the following content:

FROM alpine RUN exit 1

When the "RUN" statement exits with a non-zero exit code buildkit will treat it as an error and is able to provide the user with a helpful error message pointing to exactly the line in the Dockerfile that caused the error.

func (s *SourceOp) Inputs() []Output

func (s *SourceOp) Output() Output

State represents all operations that must be done to produce a given output. States are immutable, and all operations return a new state linked to the previous one. State is the core type of the LLB API and is used to build a graph of operations. The graph is then marshaled into a definition that can be executed by a backend (such as buildkitd).

Operations performed on a State are executed lazily after the entire state graph is marshalled and sent to the backend.

func Diff(lower, upper State, opts ...ConstraintsOpt) State

Diff returns a state that represents the diff of the lower and upper states. The returned State is useful for use with Merge where you can merge the lower state with the diff.

Git returns a state that represents a git repository. Example:

st := llb.Git("https://github.com/moby/buildkit.git", "v0.11.6")

The example fetches the v0.11.6 tag of the buildkit repository. You can also use a commit hash or a branch name.

Other URL formats are supported such as "git@github.com:moby/buildkit.git", "git://...", "ssh://..." Formats that utilize SSH may need to supply credentials as a GitOption. You may need to check the source code for a full list of supported formats.

By default the git repository is cloned with `--depth=1` to reduce the amount of data downloaded. Additionally the ".git" directory is removed after the clone, you can keep ith with the KeepGitDir GitOption.

Image returns a state that represents a docker image in a registry. Example:

st := llb.Image("busybox:latest")

Local returns a state that represents a directory local to the client.

func Merge(inputs []State, opts ...ConstraintsOpt) State

Merge merges multiple states into a single state. This is useful in conjunction with Diff to create set of patches which are independent of each other to a base state without affecting the cache of other merged states. As an example, lets say you have a rootfs with the following directories:

/ /bin /etc /opt /tmp

Now lets say you want to copy a directory /etc/foo from one state and a binary /bin/bar from another state.Copy makes a duplicate of file on top of another directory. Merge creates a directory whose contents is an overlay of 2 states on top of each other.

With "Merge" you can do this:

fooState := Diff(rootfs, fooState) barState := Diff(rootfs, barState)

Then merge the results with:

Merge(rootfs, fooDiff, barDiff)

The resulting state will have both /etc/foo and /bin/bar, but because Merge was used, changing the contents of "fooDiff" does not require copying "barDiff" again.

func NewState(o Output) State

Scratch returns a state that represents an empty filesystem.

func (s State) AddEnv(key, value string) State

AddEnv returns a new State with the provided environment variable set. See AddEnv

AddEnvf is the same as State.AddEnv but with a format string.

AddExtraHost adds a host name to IP mapping to any containers created from this state.

AddUlimit sets the hard/soft for the given ulimit. The ulimit is applied to containers created from this state. Ulimits are Linux specific and only applies to containers created from this state such as via `[State.Run]` Ulimits do not apply to image configs.

Dir returns a new State with the provided working directory set. See Dir

Dirf is the same as State.Dir but with a format string.

Env returns a new State with the provided environment variable set. See [Env]

func (s State) File(a *FileAction, opts ...ConstraintsOpt) State

File performs a file operation on the current state. See FileAction for details on the operations that can be performed.

GetDir returns the current working directory for the state.

GetEnv returns the value of the environment variable with the provided key.

GetHostname returns the hostname set on the state. See Hostname for more details.

GetNetwork returns the network mode for the state.

GetPlatform returns the platform for the state.

GetSecurity returns the security mode for the state.

Hostname sets the hostname for this state. See Hostname for more details.

Marshal marshals the state and all its parents into a Definition.

Network sets the network mode for the state. Network modes are used by State.Run to determine the network mode used when running the container. Network modes are not applied to image configs.

func (s State) Output() Output

Output returns the output of the state.

Platform sets the platform for the state. Platforms are used to determine image variants to pull and run as well as the platform metadata to set on the image config.

func (s State) Reset(s2 State) State

Reset is used to return a new State with all of the current state and the provided State as the parent. In effect you can think of this as creating a new state with all the output from the current state but reparented to the provided state. See Reset for more details.

func (s State) Run(ro ...RunOption) ExecState

Run performs the command specified by the arguments within the context of the current State. The command is executed as a container with the State's filesystem as the root filesystem. As such any command you run must be present in the State's filesystem. Constraints such as [State.Ulimit], [State.ParentCgroup], State.Network, etc. are applied to the container.

Run is useful when none of the LLB ops are sufficient for the operation that you want to perform.

Security sets the security mode for the state. Security modes are used by State.Run to the privileges that processes in the container will run with. Security modes are not applied to image configs.

func (s State) SetMarshalDefaults(co ...ConstraintsOpt) State

User sets the user for this state. See User for more details.

Validate validates the state. This validation, unlike most other operations on State, is not lazily performed.

func (s State) With(so ...StateOption) State

With applies [StateOption]s to the State. Each applied StateOption creates a new State object with the previous as its parent.

func (s State) WithCgroupParent(cp string) State

WithCgroupParent sets the parent cgroup for any containers created from this state. This is useful when you want to apply resource constraints to a group of containers. Cgroups are Linux specific and only applies to containers created from this state such as via `[State.Run]` Cgroups do not apply to image configs.

WithImageConfig adds the environment variables, working directory, and platform specified in the image config to the state.

func (s State) WithOutput(o Output) State

WithOutput creates a new state with the output set to the given output.

func (s State) WithValue(k, v any) State

type StateOption func(State) State

AddEnv returns a StateOption whichs adds an environment variable to the state. Use this with State.With to create a new state with the environment variable set. This is the equivalent of `[State.AddEnv]`

AddEnvf is the same as AddEnv but allows for a format string. This is the equivalent of `[State.AddEnvf]`

Dir returns a StateOption sets the working directory for the state which will be used to resolve relative paths as well as the working directory for State.Run. See State.With for where to use this.

Dirf is the same as Dir but allows for a format string.

Hostname returns a StateOption which sets the hostname used for containers created by State.Run. This is the equivalent of State.HostnameSee State.With for where to use this.

Network returns a StateOption which sets the network mode used for containers created by State.Run. This is the equivalent of State.NetworkSee State.With for where to use this.

func Reset(other State) StateOption

Reset returns a StateOption which creates a new State with just the output of the current State and the provided State is set as the parent. This is the equivalent of State.Reset

Security returns a StateOption which sets the security mode used for containers created by State.Run. This is the equivalent of State.SecuritySee State.With for where to use this.

User returns a StateOption which sets the user for the state which will be used by State.Run. This is the equivalent of State.UserSee State.With for where to use this.

func (fn StateOption) SetRunOption(ei *ExecInfo)

type SymlinkInfo struct { ChownOpt *ChownOpt CreatedTime *time.Time }

SymlinkInfo is the modifiable options used to create symlinks

func (si *SymlinkInfo) SetSymlinkOption(si2 *SymlinkInfo)

type SymlinkOption interface { SetSymlinkOption(*SymlinkInfo) }

type TmpfsInfo struct { Size int64 }

type TmpfsOption interface { SetTmpfsOption(*TmpfsInfo) }

const ( UlimitCore UlimitName = "core" UlimitCPU UlimitName = "cpu" UlimitData UlimitName = "data" UlimitFsize UlimitName = "fsize" UlimitLocks UlimitName = "locks" UlimitMemlock UlimitName = "memlock" UlimitMsgqueue UlimitName = "msgqueue" UlimitNice UlimitName = "nice" UlimitNofile UlimitName = "nofile" UlimitNproc UlimitName = "nproc" UlimitRtprio UlimitName = "rtprio" UlimitRttime UlimitName = "rttime" UlimitSigpending UlimitName = "sigpending" UlimitStack UlimitName = "stack" )