Documentation
¶
Overview ¶
Package coopr executes typed build programs through Coopr's supervised native Buildah backend. Applications must call InitReexec at the start of main before parsing arguments. Workers reexecute that same binary and enter rootless user namespaces themselves; the host application need not enter a user namespace.
Execution requires Linux, configured subordinate IDs/rootless namespaces, containers/storage support and an OCI runtime when running commands. Host or nested-container policy may prevent execution. Callers own store/cache roots, input contexts and successful output paths. Execute owns disposable workers and staging directories and drains cancellation cleanup. ErrCleanupFailed means completion could not be confirmed; callers must retain borrowed inputs and directories containing retained staging while investigating that failure.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCleanupFailed = buildah.ErrWorkerWaitIncomplete
ErrCleanupFailed means worker cleanup failed or could not be confirmed. Check with errors.Is even when the error also reports context cancellation. Keep borrowed inputs and retained staging available until cleanup is resolved.
Functions ¶
func InitReexec ¶
func InitReexec() bool
InitReexec dispatches registered same-binary build workers and runtime helpers. Call first in main, and return immediately when it returns true.
Dispatch runs before application argument checks, following Buildah's embedding contract. It does not authenticate application requests. Do not expose the executable through setuid, file capabilities or restricted sudo rules that rely on those later checks to limit the caller's operations. Operator-authorized root and sudo builds use the operator's existing authority.
Types ¶
type CacheOptions ¶
type CacheOptions struct {
// MountDir selects the private persistent parent for native RUN cache mounts.
// Contents are disposable acceleration and are not hashed into build inputs.
MountDir string
LocalDir string
NoCache bool
RegistryFrom []string
RegistryTo []string
}
CacheOptions controls the optional portable instruction cache. LocalDir is a caller-owned absolute OCI cache directory. RegistryFrom and RegistryTo select bare registry repositories for reads and writes independently; they may be combined with LocalDir. Leaving all locations empty disables portable caching. Native local Buildah layer reuse is separate and is not counted by CacheStats.
type CacheStats ¶
type CacheStats struct{ Hits, Misses, Stored, Skipped, Errors int }
CacheStats counts optional portable-cache decisions, not total backend reuse.
type Env ¶
type Env struct{ Name, Value string }
Env sets one literal image environment value inherited by later commands.
type Mount ¶
type Mount struct {
// HostPath is an explicit live host directory for one bind RUN mount.
// It is exclusive with From and Source. Live mounts bypass result caching;
// ordinary context mounts retain their snapshotted semantics.
HostPath string
// Relabel explicitly opts a live host directory into native SELinux z/Z relabeling.
Relabel string
Type, Target, Source, ID, Sharing string
From Source
ReadOnly bool
}
Mount is a bind, cache or tmpfs RUN mount. Omitted cache IDs use native stable program/platform/stage scope. Sharing is shared or locked; the current Buildah backend does not implement private sharing. From applies only to bind mounts. ReadOnly false requests writable binds. Writable host-context binds use the native disposable build-scoped context copy and side-effect-aware cache; the caller context is preserved. Other mount types retain native defaults when ReadOnly is false.
type Operation ¶
type Operation interface {
// contains filtered or unexported methods
}
Operation is a supported typed build operation. Use value forms of Run, Copy, Env and Workdir; pointer forms are not accepted.
type OperationProgress ¶
type OperationProgress = api.OperationProgress
OperationProgress is a backend-independent observation of execution work.
type Options ¶
type Options struct {
// Progress receives bounded observations while supervised workers execute.
// Callbacks run synchronously and must return; callers sharing a callback
// across concurrent Execute calls synchronize it.
Progress func(OperationProgress)
// Network selects the default RUN network; it does not restrict registry traffic.
Network string
// Contexts supplies named local COPY and RUN inputs independently of ContextDir.
Contexts map[string]string
Store StoreOptions
ContextDir, Runtime, Isolation string
Jobs int
Output Output
Cache CacheOptions
Registry RegistryOptions
Stdout, Stderr io.Writer
}
Options supplies execution resources. ContextDir, when supplied, is an absolute directory. Jobs zero uses the backend default. Writers receive worker output; callers sharing writers across concurrent calls must synchronize them.
type Output ¶
type Output struct {
OCI, Filesystem string
Exports []api.FileExport
}
Output selects fresh absolute destinations whose parent directories exist. OCI optionally exports an image layout. With OCI empty, the native image is retained without image serialization. Filesystem exports the flattened root filesystem. Exports selects files or directories, including diagnostics after an ordinary failed RUN in the selected state. Outputs require confirmed cleanup and are promoted separately; existing paths are never overwritten.
type Program ¶
Program is an ordered, topological graph with one explicit final output. Platform defaults to the host platform. Independent states may run concurrently. Values are literal; coopr does not expand Coopr ARG or ENV expressions.
type RegistryOptions ¶
type RegistryOptions struct {
AuthFile, CertDir, Credentials, PullPolicy, SignaturePolicyPath string
TLSVerify *bool
}
RegistryOptions controls native image authentication and pull policy.
type Result ¶
type Result struct {
ImageID, ManifestDigest, Platform, OCI, Filesystem string
Cache CacheStats
ProgressDropped uint64
Exports []api.ExportResult
}
Result identifies the completed image and caller-owned outputs.
type Run ¶
Run executes Args directly, without adding a shell. Use an explicit shell argv when shell interpretation is desired.
type Source ¶
Source selects an image, earlier state or named local COPY context. Image "scratch" selects an empty filesystem. Inherited ONBUILD triggers are cleared without execution; frontend instruction expansion is outside this API. An empty Copy or bind-mount source uses ContextDir. Context selects a declared local named input for COPY or RUN mounts; it cannot supply a state base.
type StoreOptions ¶
StoreOptions selects caller-owned containers/storage roots. Both roots must be absolute and distinct. Driver defaults to native containers/storage policy.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api defines Coopr's versioned, transport-safe execution contract.
|
Package api defines Coopr's versioned, transport-safe execution contract. |
|
Package client provides Coopr's versioned Unix-socket execution client.
|
Package client provides Coopr's versioned Unix-socket execution client. |
|
cmd
|
|
|
coopr
command
|
|
|
coopr-run-sequence
command
coopr-run-sequence runs direct argv commands within one container execution.
|
coopr-run-sequence runs direct argv commands within one container execution. |
|
coopr-sequoia-signing
command
coopr-sequoia-signing is an optional native signing backend, never a container runtime dependency.
|
coopr-sequoia-signing is an optional native signing backend, never a container runtime dependency. |
|
internal
|
|
|
apibackend
Package apibackend adapts public API requests to Coopr's existing backends.
|
Package apibackend adapts public API requests to Coopr's existing backends. |
|
apiservice
Package apiservice serves Coopr's same-account execution API on Unix sockets.
|
Package apiservice serves Coopr's same-account execution API on Unix sockets. |
|
build
Package build runs local Coopr definitions through the embedded Buildah backend.
|
Package build runs local Coopr definitions through the embedded Buildah backend. |
|
buildah
Package buildah executes Coopr build operations directly through Buildah's library API.
|
Package buildah executes Coopr build operations directly through Buildah's library API. |
|
buildcontext
Package buildcontext defines named inputs supplied independently of the primary build context.
|
Package buildcontext defines named inputs supplied independently of the primary build context. |
|
cache
Package cache stores portable logical transformation results as OCI artifacts.
|
Package cache stores portable logical transformation results as OCI artifacts. |
|
componentstore
Package componentstore manages Coopr's local OCI image-layout component store.
|
Package componentstore manages Coopr's local OCI image-layout component store. |
|
definition
Package definition parses the ordered stage blocks in a Coopr definition.
|
Package definition parses the ordered stage blocks in a Coopr definition. |
|
enginecopy
Package enginecopy delivers Coopr image indexes to Docker Engine.
|
Package enginecopy delivers Coopr image indexes to Docker Engine. |
|
imageconfig
Package imageconfig owns Coopr's executor-neutral OCI image configuration.
|
Package imageconfig owns Coopr's executor-neutral OCI image configuration. |
|
imagestore
Package imagestore operates on images in borrowed containers-storage handles.
|
Package imagestore operates on images in borrowed containers-storage handles. |
|
localstore
Package localstore manages OCI graphs in Coopr-owned local image layouts.
|
Package localstore manages OCI graphs in Coopr-owned local image layouts. |
|
oci
Package oci resolves OCI image and component references to verified content.
|
Package oci resolves OCI image and component references to verified content. |
|
onbuildparse
Package onbuildparse converts Docker-format ONBUILD trigger strings into Coopr's executor-neutral instruction model.
|
Package onbuildparse converts Docker-format ONBUILD trigger strings into Coopr's executor-neutral instruction model. |
|
planner
Package planner separates component publication from invocation without executing commands, resolving registries, or reading build-context files.
|
Package planner separates component publication from invocation without executing commands, resolving registries, or reading build-context files. |
|
stateidentity
Package stateidentity hashes the logical contents of an effective rootfs and its image configuration.
|
Package stateidentity hashes the logical contents of an effective rootfs and its image configuration. |
|
storeactivity
Package storeactivity coordinates long-lived Coopr store operations with destructive maintenance across processes.
|
Package storeactivity coordinates long-lived Coopr store operations with destructive maintenance across processes. |
|
testutil/nativeimage
Package nativeimage seeds private native-store test fixtures.
|
Package nativeimage seeds private native-store test fixtures. |
|
transfer
Package transfer copies already-built Coopr artifacts to named destinations.
|
Package transfer copies already-built Coopr artifacts to named destinations. |
|
scripts
|
|