Documentation
¶
Overview ¶
Package oci provides the OCI + gVisor (runsc) Runtime Provider worker. It implements the fenced Runtime Protocol loop from ADR-006 and delegates workload execution to a sandboxed Executor so the protocol logic stays testable without containerd or runsc installed.
Index ¶
Constants ¶
const ( // ProviderName identifies this provider in checkpoints and audit records. ProviderName = "oci-gvisor" // RuntimeABI is the provider-level Runtime ABI declared in checkpoint envelopes. RuntimeABI = "fenced.oci/v1" // CheckpointSchema is the logical checkpoint state schema version. CheckpointSchema = "fenced.oci-logical/v1" )
const SpoolCap = 4 << 20
SpoolCap bounds spooled output per execution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ArtifactStore ¶
type ArtifactStore interface {
Put(context.Context, string, string, io.Reader) (store.ArtifactReference, error)
Open(context.Context, string, store.ArtifactReference) (io.ReadCloser, error)
}
ArtifactStore is the content-addressed store used for checkpoint state and results. The filesystem adapter is development-only; production must use an S3-compatible adapter with the same artifact:// identity.
type DirectRunscOption ¶
type DirectRunscOption func(*directExecutor)
DirectRunscOption configures the direct runsc executor. It is declared here so the non-Linux stub can reference it; the concrete constructor lives in direct_linux.go.
func WithRunscBinary ¶
func WithRunscBinary(path string) DirectRunscOption
WithRunscBinary sets the runsc binary path (default "runsc" resolved on PATH).
func WithRunscPlatform ¶
func WithRunscPlatform(platform string) DirectRunscOption
WithRunscPlatform sets the runsc platform (default "kvm").
func WithRunscRoot ¶
func WithRunscRoot(root string) DirectRunscOption
WithRunscRoot sets the runsc state root directory (default "/run/containerd/runsc/fenced").
type Execution ¶
type Execution interface {
// ID is the provider-side sandbox identifier (for example the containerd
// container ID), used by Destroy.
ID() string
// Wait blocks until the workload terminates or ctx is cancelled. On
// cancellation the provider must request termination of the workload.
Wait(ctx context.Context) (RunResult, error)
}
Execution is a prepared workload owned by the provider.
type ExecutionSpec ¶
type ExecutionSpec struct {
TenantID string
AttemptID string
AgentVersionRef string
WorkloadSpecJSON []byte
ImageRef string
// Command overrides the image Entrypoint/Cmd as an argv array. Empty uses
// the immutable image configuration.
Command []string
WorkspaceBytes int64
CPUQuotaMillis int64
MemoryLimitMiB int64
RuntimeClass string
RuntimePoolID string
RuntimeInstanceID string
// OutputSpooler persists bounded workload stdout/stderr to the artifact
// store; nil keeps the pre-hardening bounded-discard behavior.
OutputSpooler OutputSpooler
}
ExecutionSpec is the provider-agnostic input to run one Attempt in a sandboxed container. All fields come from the fenced Assignment and from validated workload metadata; the Executor must never trust container-supplied values for its own resource or identity decisions.
func (ExecutionSpec) Limits ¶
func (s ExecutionSpec) Limits() (cpuMillis, memoryMiB, workspaceBytes int64)
ExecutionSpecLimits returns the resource limits encoded in an ExecutionSpec as (cpuMillis, memoryMiB, workspaceBytes); zero values mean "no explicit limit", which Admission must not allow for untrusted workloads.
type Executor ¶
type Executor interface {
Prepare(ctx context.Context, spec ExecutionSpec) (Execution, error)
Destroy(ctx context.Context, execution Execution) error
}
Executor prepares and destroys sandboxed executions. Implementations must be safe for concurrent use by multiple workers on the same RuntimeInstance.
func NewRunscDirectExecutor ¶
func NewRunscDirectExecutor(options ...DirectRunscOption) (Executor, error)
NewRunscDirectExecutor constructs a direct runsc executor after verifying the runsc binary is available. The containerd CLI (ctr) is used only to mount the pinned image's root filesystem; workload execution never touches the containerd shim.
func NewRunscExecutor ¶
func NewRunscExecutor(options ...RunscOption) (Executor, error)
NewRunscExecutor constructs the containerd/runsc executor after verifying that the ctr CLI is available. It must run on Linux with containerd and runsc installed; the worker never falls back to an unsandboxed runtime.
type OutputSpooler ¶
type OutputSpooler interface {
Spool(context.Context, string, string, string, io.Reader) (store.ArtifactReference, error)
}
OutputSpooler persists bounded workload output so container stdout/stderr never grow unbounded in kernel memory (hardening checklist §4.4). The worker's artifact store satisfies it.
type RunResult ¶
type RunResult struct {
ExitCode int
UsageMillis int64
// FailureCode is an optional machine-readable classification. When empty,
// the worker derives one from ExitCode.
FailureCode string
// Stdout is the spooled stdout/stderr artifact, when the execution
// declared an OutputSpooler and produced output.
Stdout *store.ArtifactReference
// StdoutTruncated reports that output exceeded the spool cap.
StdoutTruncated bool
}
RunResult is what a provider reports after the workload terminates. Container stdout is spooled to the artifact store (bounded), never carried in kernel messages.
type RunscOption ¶
type RunscOption func(*ctrExecutor)
RunscOption configures the containerd/runsc executor. It is declared here so the non-Linux stub can reference it; the concrete options and methods live in runsc_linux.go.
func WithNamespace ¶
func WithNamespace(namespace string) RunscOption
WithNamespace sets the containerd namespace (default "fenced").
func WithRuntime ¶
func WithRuntime(runtime string) RunscOption
WithRuntime sets the containerd runtime name (default "io.containerd.runsc.v1").
func WithRuntimeConfigPath ¶
func WithRuntimeConfigPath(path string) RunscOption
WithRuntimeConfigPath sets the gVisor shim configuration passed to ctr. The runsc shim does not read containerd's CRI runtime configuration when invoked directly by ctr, so every sandbox run must carry this path.
func WithSkipPull ¶
func WithSkipPull() RunscOption
WithSkipPull skips the image pull step (development images pre-loaded into containerd only).
func WithSnapshotter ¶
func WithSnapshotter(snapshotter string) RunscOption
WithSnapshotter sets the containerd snapshotter for sandbox rootfs mounts (default "overlayfs"). Nested environments (containerd inside a container, e.g. Docker Desktop/WSL2) cannot mount overlay-on-overlay and must use "native"; the choice is passed to ctr explicitly because ctr hardcodes overlayfs as its own default.
type Worker ¶
type Worker struct {
// contains filtered or unexported fields
}
Worker runs the fenced Runtime Protocol loop for one RuntimeInstance, delegating workload execution to an Executor. It mirrors the protocol choreography of the reference provider while remaining provider-agnostic: every mutation carries the AttemptIdentity fencing token and expected resource version, and a caller that loses a response must re-read the assignment before retrying (ADR-006).
func NewWorker ¶
func NewWorker(client runtimev1.RuntimeControlServiceClient, artifacts ArtifactStore, executor Executor, tenantID, runtimeInstanceID string, heartbeatTTL time.Duration, imageRef string) *Worker
NewWorker constructs a worker. imageRef is the digest-pinned OCI image that runs the published AgentVersion; resource limits are worker configuration until Admission passes them through the Assignment.
func (*Worker) RunOnce ¶
RunOnce polls for one assignment and executes it to a terminal state. It returns processed=true when an assignment was consumed (completed, failed, or cancelled) and false when no assignment was available.
func (*Worker) Spool ¶
func (w *Worker) Spool(ctx context.Context, tenantID, attemptID, mediaType string, reader io.Reader) (store.ArtifactReference, error)
Spool implements the OutputSpooler contract (hardening checklist §4.4): bounded workload output is persisted to the artifact store.
func (*Worker) WithResourceLimits ¶
WithResourceLimits sets the sandbox resource envelope for executions started by this worker.