oci

package
v1.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

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

View Source
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"
)
View Source
const SpoolCap = 4 << 20

SpoolCap bounds spooled output per execution.

Variables

This section is empty.

Functions

This section is empty.

Types

type ArtifactStore

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

func (w *Worker) RunOnce(ctx context.Context) (bool, error)

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

func (w *Worker) WithResourceLimits(cpuQuotaMillis, memoryLimitMiB, workspaceBytes int64) *Worker

WithResourceLimits sets the sandbox resource envelope for executions started by this worker.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL