igbackend

package
v0.3.336 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 61 Imported by: 0

README

Persistent execution-policy backend

The public service now uses NewFull with NewNativeFullEngine and NewContainerdFullSource. The legacy NewNative / path-only converter remains for historical tests, but is not a fallback for unsupported full policies.

FullBackend installs immutable generation provenance before native startup or publication. First activation follows successful manager startup. Reload uses Owner.Update / Resume on the same maps and links, retaining successful policy UID epochs. Kernel commit is irreversible even if reopening/finalization fails; reconciliation resumes that generation rather than rolling it back. Whole-exec gate closure can disrupt concurrent execs. Unsupported inputs are refused.

One administrator-configured aggregate budget bounds all native owners. Exact cgroups stay exclusively reserved until actual detach and release. Startup failures retain partial owners and untransferred leases. Stop must complete BeforeStop before manager cancellation, join real teardown, then call ReleaseAfterDetach; failed cleanup remains owned and retryable. The trusted containerd client closes only after every lease has been consumed.

The combined lease pins the exact proc allocation, cgroup, workload mount namespace, initial-host PID/mount namespaces, stable root and complete lower image inode index. It authenticates containerd task/image/CRI metadata, never policy annotations. The protected socket and administrator host mounts are trusted deployment inputs, not proven authentic merely by their path names. The supported root/seccomp/capability and immutable overlay constraints apply even when the current revision has no image predicate, because later revisions reuse the same owner and origin index. A changed image/root invalidates that owner, not an in-place index refresh. No inferred helper exemptions exist.

FullVerdictCatalog keeps at most 16 generation-specific decoders, including active and staged provenance. Evicted/unknown generations are dropped rather than attributed to a newer plan. Full verdicts use the kernel's typed four-word match bitmap, with explicit incomplete matches for operational failures. UID, argv, actor and image facts remain absent when the event does not supply them. Exporter failures do not change kernel decisions.

Verification boundary

Compiler, catalogue, transaction and lifecycle unit/race tests do not prove the combined node-agent native path. The matching IG owner has isolated real-kernel native OCI proof, and constrained containerd image discovery has separate proof. The combined native/containerd1.7.30/runc1.3.4 CRI fixture now passes on the pinned amd64 kernel, including generated managed files, shared memory, readonly cgroup2, 13 paths, same-owner reload and actual public events. It does not run a kubelet/API server or establish generic runtime/kernel compatibility. The exact supported kernel BTF gate is intentionally narrow. Private OTel implementation is outside this public change.

The expanded IG revision is published and pinned at v0.0.0-20261027133411-87a796fe9780; standalone node-agent targeted tests, race checks, vet and binary builds pass without a development workspace. This revision also includes IG main through #16, preserving the ordinary-symbol streaming fix, and the individually proved Kubernetes-capable exact BTF artifact. Its isolated upstream predicate/persistent OCI/CRI proof does not replace the still-pending private Kubernetes/OTLP integration proof. The pin is still on PR #15 rather than main, so the repository merge guard correctly blocks consumer merging until the upstream change is merged and re-pinned. No chart version has changed. No image is implicitly downloaded or trusted: the local OCI archive is privileged administrator-supplied code, and IG skips its signature verification for explicit local targets.

Shared node engine (G020)

sharedengine.go implements FullEngine over one node-wide IG shared collection, started lazily on the first binding. Two starts share it:

  • product (sharedengine_start_product.go, default build): NewSharedProductEngine selects the running kernel build's image at agent start (fullruntime.SelectSharedProductImage over the BTF sha256 map the integration package passes: the one entry its compiled-in kernel table selected), loads its profile (compiled in, or a file), and requires the trusted store to resolve the image to the pinned manifest digest (again before StartNode). It starts through fullruntime.WithSharedNodeHost. Any refusal leaves an engine that never starts and reports the reason (SharedEngineUnavailable). NewUnavailableSharedEngine builds such an engine for a refusal made before selection; a reason wrapping ErrKernelNotQualified is reported as KernelNotQualified;
  • qualification (sharedengine_start_qualification.go, build tags sandbox_shared_qualification and IG's enforce_exec_shared_qualification): NewSharedQualificationEngine starts through the IG qualification seam and never reports Ready.

Start binds the trusted cgroup/init/CRI container ID; Activate and UpdatePlan compile the binding's single policy through IG (multi-policy plans are refused, D3), check that IG's matched-rule mapping equals the backend's provenance, stage the route generation before PublishCompiled, and retry stale compilations a bounded number of times. The binding's route scope (its registration's scope cookie) is recorded before anything is staged. A publication whose outcome is unknown stays pending with its staging (Resume republishes it, AbortPending discards it). Verdict events are demultiplexed by the bound cgroup (so events between the kernel commit and its receipt are delivered), must carry the registered scope, and are translated from route generations to backend generations; stopped bindings tombstone their (cgroup, scope), so a reused cgroup ID never receives a retired binding's in-flight events. A first publication whose outcome is unknown (fullruntime.ErrSharedPublishUnknown) carries the scope IG minted for it; that scope is kept only so Stop tombstones it too (the latched route's late events are dropped, not reported as unbound), and never attributes an event. Unbound-cgroup reports are rate-limited. Shared events must carry a nonzero load_epoch (a missing or zero epoch is refused); consumers key an exec on Verdict.LoadEpoch, TaskCookie and ExecID together, since task cookies restart on every load. Only this engine opts its decoders into the D1 Audit fault on shared events (deny 1, mode 1, error 1 as a would-deny operational_error); the per-binding engine refuses a shared-event Audit fault. A non-shared (legacy owner) Audit fault decodes as a would-deny operational_error on either engine, because the legacy owner never blocks an Audit exec. A product binding's Check passes only when the node is Ready and SharedBindingStatus.Protected holds at the route generation the binding committed (attached, published, not WithdrawPending, no refused adoption, no fault); a qualification binding's Check always fails. ApplySharedNodeHealth maps node Ready, the node's Degraded conditions and the fail-closed, fact and verdict-loss witnesses into node conditions (Degraded never makes Ready False, D2); a Ready product node keeps the controller's Ready condition. The integration status writer applies it to every node status when the shared engine is selected.

Legacy API

NewNative / Compile remain a separate path-only, single-policy API with immutable candidate replacement and dedicated compatibility tests. Actor/image/ filesystem/argv/role predicates and multiple policies are rejected there. The public service never falls back to this API. Legacy events omit richer facts and only attribute unambiguous decisive rules. Local fake-engine tests do not prove BPF readiness or kernel enforcement.

Documentation

Overview

Package igbackend owns strict execution-policy gadgets. The public service uses the persistent full backend; the explicit legacy API remains separate. Unsupported semantics are errors, never silently weakened rules.

Index

Constants

View Source
const (
	SharedDefaultImageProcRoot = "/host/proc"
	SharedDefaultImageHostRoot = "/host"
)

Defaults: the host procfs and root as mounted into the node-agent pod (hostPID is required for the host PID namespace).

View Source
const FullBackendMaxBindings = 1024

FullBackendMaxBindings includes owners awaiting cleanup.

View Source
const FullOperationTimeout = 5 * time.Second

Bound whole-exec drain/re-attestation even when the service lifetime context has no deadline. First admission may need a longer bounded image walk/load.

View Source
const FullStartupTimeout = 2 * time.Minute
View Source
const FullVerdictCatalogCapacity = 16

FullVerdictCatalogCapacity bounds provenance retained per persistent owner, including its active generation and at most one pending publication. Late events for evicted generations are dropped, never decoded with newer rules.

View Source
const SharedEngineAPIVersion = 1

SharedEngineAPIVersion is the IG shared-node API version this engine is written against; the engine constructors refuse any other.

View Source
const SharedPublishAttempts = 3

SharedPublishAttempts bounds Compile/PublishCompiled retries when a compilation goes stale (fullruntime.ErrSharedCompiledStale).

Variables

View Source
var ErrKernelNotQualified = errors.New("running kernel is not a qualified kernel build")

ErrKernelNotQualified: the running kernel is not one of the agent's compiled-in qualified kernel builds (its architecture, BTF sha256, release or GNU build-id differs). Health reports it with reason KernelNotQualified.

View Source
var ErrSharedManifestMismatch = errors.New("shared image manifest digest mismatch")

ErrSharedManifestMismatch: the trusted store resolves the selected image to a manifest other than the configured one.

View Source
var ErrVerdictDecode = errors.New("sandbox verdict decode failed")

ErrVerdictDecode wraps every verdict event dropped because it could not be read from the datasource or decoded against its generation's catalogue. It reaches the onError callback only; enforcement is unaffected.

Functions

func ApplySharedNodeHealth

func ApplySharedNodeHealth(status *api.NodeStatus, h SharedNodeHealth, observedGeneration int64, now metav1.Time)

ApplySharedNodeHealth maps h into status's Ready and Degraded conditions.

Ready: an engine refused at agent start is False (KernelNotQualified when the running kernel is not a qualified build, otherwise SharedEngineUnavailable, with the typed reason), a node start still retrying a native attach capacity refusal is False (SharedNodeAttachCapacity, with the refusal), a node whose start failed is False (SharedNodeStartFailed, with the error), a node not started is False (SharedNodeNotStarted) and a node whose Ready fails, or whose fail-closed witness is NotReady or unknown, is False (SharedNodeNotReady). A qualification node is otherwise False (QualificationOnly). A Ready product node never raises Ready: the controller's Ready condition (True only when every binding's Check passed) is kept, and absent one Ready is False (ReadyUnreported).

Degraded (D2: never NotReady on its own) is merged into an existing Degraded condition: an existing True one keeps its reason and message and gains ours. Ours reports a fail-closed Degraded window, verdict event loss, the image ledger fault, any other Degraded condition of a product node (SharedNodeDegraded), a binding's latched protocol fault (BindingProtocolFault) and unavailable witnesses.

func Compile

func Compile(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64) (execruntime.Config, error)

Compile is an explicit interim legacy converter, not the full exec backend.

func CompileFull

func CompileFull(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64, activatedRoleEpochs map[string]uint64) (*fullpolicy.KernelProgram, error)

CompileFull preserves the complete resolved exec vocabulary and policy-local identities. It prepares immutable data only: it neither attests kernel facts nor authorizes role bootstrap, image evidence or native publication. The interim path-only Compile/Backend remains unchanged until its persistent owner is available. activatedRoleEpochs is the persistent owner's SUCCESSFUL UID activation catalogue; nil is appropriate only for a fresh owner, not reload. The matching expanded IG module is required to build this bridge.

func DecodeVerdict

func DecodeVerdict(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, generation uint64, r RawVerdict) (sandboxpolicy.Verdict, error)

DecodeVerdict leaves argv, UID, image origin and actor paths absent when the legacy event cannot supply them. Time is receipt time, not kernel time.

func LoadSharedProfile

func LoadSharedProfile(path string) (fullruntime.SharedProfile, error)

LoadSharedProfile reads the exact geometry the shared image was built with (a JSON fullruntime.SharedProfile; unknown fields are refused).

func VerifySharedImage

func VerifySharedImage(ctx context.Context, store oras.ReadOnlyTarget, image, expected, arch string) error

VerifySharedImage is the build-time check of a product image in the agent's tracers.tar: the agent's start check for arch (the kernel entry's architecture, not the builder's), then every blob the manifest references (its config and layers) is fetched digest- and size-verified, so the archive cannot ship content other than the pinned image's.

Types

type Backend

type Backend struct {
	// contains filtered or unexported fields
}

func New

func New(engine Engine, validator Validator, receiver sandboxpolicy.VerdictReceiver, onError func(error)) (*Backend, error)

func NewNative

func NewNative(rt runtime.Runtime, kube operators.DataOperator, store oras.ReadOnlyTarget, image string, receiver sandboxpolicy.VerdictReceiver, onError func(error)) (*Backend, error)

NewNative uses an already initialized runtime. Its caller retains ownership of that runtime and must call Backend.Close before runtime.Close.

func (*Backend) Close

func (b *Backend) Close(ctx context.Context) error

Close removes this backend's exact bindings and finishes their cleanup. Call again after an error; it does not stop unrelated instances on the runtime.

func (*Backend) Replace

func (b *Backend) Replace(ctx context.Context, binding sandboxpolicy.Binding, plan sandboxpolicy.Plan) (result sandboxpolicy.ReplaceResult, resultErr error)

func (*Backend) Withdraw

func (b *Backend) Withdraw(ctx context.Context, binding sandboxpolicy.Binding) (result sandboxpolicy.WithdrawResult, resultErr error)

type ContainerdFullSource

type ContainerdFullSource struct {
	// contains filtered or unexported fields
}

ContainerdFullSource owns one trusted containerd connection. Close must follow all native owners' confirmed detach and lease release; it refuses outstanding preparations/leases. A failed Close seals admission, and can be retried.

The administrator must provide a protected host root, host proc/cgroup mounts and containerd socket/parent directory from the same host. These privileged inputs are not authenticated by policy metadata or by merely naming a path. The host-proc check additionally requires Linux's initial PID namespace and pins PID1's current mount namespace; unsupported/container-local proc fails.

func NewContainerdFullSource

func NewContainerdFullSource(socket, hostRoot, procRoot, cgroupRoot string, limits ImageIndexLimits) (*ContainerdFullSource, error)

func (*ContainerdFullSource) Close

func (s *ContainerdFullSource) Close() error

func (*ContainerdFullSource) Prepare

type Engine

type Engine interface {
	Start(context.Context, string, execruntime.Config, func(RawVerdict)) (Instance, error)
}

Engine.Start returns only after native readiness, or after failed-candidate cleanup. Every call owns independent maps and links.

type FullBackend

type FullBackend struct {
	// contains filtered or unexported fields
}

FullBackend publishes into one persistent native owner per exact binding. Native engine and trusted lease source are explicit: there is no legacy fallback.

func NewFull

func NewFull(engine FullEngine, source FullBindingSource, receiver sandboxpolicy.VerdictReceiver, onError func(error)) (*FullBackend, error)

func (*FullBackend) Attest

func (b *FullBackend) Attest(ctx context.Context, binding sandboxpolicy.Binding, revision string) error

Attest observes only the exact committed owner; it never resumes a pending publication, including an uncommitted candidate from a previously failed reload.

func (*FullBackend) Close

func (b *FullBackend) Close(ctx context.Context) error

func (*FullBackend) KernelEventStats

func (b *FullBackend) KernelEventStats(ctx context.Context) (KernelEventStats, error)

KernelEventStats reads telemetry only; it does not check/repair enforcement. Errors describe incomplete totals, never successful zero-loss observations.

func (*FullBackend) Replace

func (b *FullBackend) Replace(ctx context.Context, binding sandboxpolicy.Binding, plan sandboxpolicy.Plan) (result sandboxpolicy.ReplaceResult, resultErr error)

func (*FullBackend) Withdraw

type FullBindingLease

type FullBindingLease interface {
	fullruntime.BindingLease
	ImageOrigins() *execruntime.ImageOriginSnapshot
}

FullBindingLease is authenticated runtime evidence, never policy input. Origins must describe the same pinned image root for the entire owner lifetime. Close consumes all owned resources even on OS close errors; repeated Close is harmless. This matches the native Owner.ReleaseAfterDetach contract.

type FullBindingSource

type FullBindingSource interface {
	Prepare(context.Context, sandboxpolicy.Binding) (FullBindingLease, error)
}

FullBindingSource transfers an owned lease, including any nonnil lease returned alongside an error. The backend retains it until cleanup is confirmed. Prepare may run concurrently for distinct bindings.

type FullEngine

type FullEngine interface {
	Start(context.Context, string, FullStartConfig, func(RawFullVerdict)) (FullInstance, error)
}

FullEngine prepares one persistent owner without activating its first policy. Install event provenance BEFORE Start and Activate. A non-nil instance returned with an error still owns resources: retain it and retry Stop until successful. Start may run concurrently for distinct bindings. Instance operations are serialized per binding; Close runs only after all Start/instance work joins. Event callbacks must not reenter lifecycle methods or block on their locks.

func NewNativeFullEngine

func NewNativeFullEngine(rt runtime.Runtime, kube operators.DataOperator, store oras.ReadOnlyTarget, image, controlRoot string, budget *fullruntime.Budget, onError func(error)) (FullEngine, error)

NewNativeFullEngine borrows the initialized runtime and trusted OCI archive. The caller must stop every instance before closing the runtime. The one shared budget must cover all engines that could target the same cgroup. No fallback to immutable/path-only enforcement occurs when the persistent image is unsupported.

type FullEngineCloser

type FullEngineCloser interface {
	Close(context.Context) error
}

FullEngineCloser optionally owns node-wide resources shared by instances. The backend calls Close only after every instance and untransferred lease has drained. An error retains ownership for retry; success is called only once. Close must not release the borrowed runtime or binding source: their caller closes those only after backend Close succeeds. Legacy engines need no Close.

type FullInstance

type FullInstance interface {
	Activate(context.Context) (fullruntime.PublicationResult, error)
	Update(context.Context, *fullpolicy.KernelProgram) (fullruntime.PublicationResult, error)
	Resume(context.Context) (fullruntime.PublicationResult, error)
	Generation() uint64
	PendingGeneration() uint64
	Epochs() map[string]uint64
	Check(context.Context) error
	// Detached confirms manager teardown, even if releasing pins still fails.
	Detached() bool
	Stop(context.Context) error
}

FullInstance reloads the same kernel owner; it never replaces the gadget. A publication error may have Committed=true. Resume the same pending generation rather than creating another owner or rolling back successful role epochs.

type FullKernelCounterSource

type FullKernelCounterSource interface {
	KernelEventCounters() (fullruntime.KernelEventCounters, error)
}

FullKernelCounterSource is optional telemetry, independent of readiness. Successful Stop must retain a Final snapshot or an explicit unavailable error.

type FullPendingAborter

type FullPendingAborter interface {
	AbortPending(context.Context) error
}

FullPendingAborter optionally discards an uncommitted candidate without changing the last committed policy. A committed candidate must not abort.

type FullPlanUpdater

type FullPlanUpdater interface {
	UpdatePlan(context.Context, sandboxpolicy.Plan, *fullpolicy.KernelProgram) (fullruntime.PublicationResult, error)
}

FullPlanUpdater optionally receives the resolved plan with each reload. The backend calls UpdatePlan instead of Update when an instance implements it; program is the backend's compilation of plan at its pending generation and keeps the Update contract (result generation, pending/commit semantics).

type FullStartConfig

type FullStartConfig struct {
	Binding      sandboxpolicy.Binding
	Program      *fullpolicy.KernelProgram
	Acquire      func(context.Context) (fullruntime.BindingLease, error)
	ImageOrigins *execruntime.ImageOriginSnapshot
	// Plan is the resolved plan Program was compiled from. Engines that compile
	// in-kernel publications themselves (the shared node engine) need it;
	// per-binding owners ignore it.
	Plan sandboxpolicy.Plan
}

FullStartConfig supplies trusted runtime evidence, never policy annotations. Acquire transfers ownership of its lease (including partial error results) to the instance. ImageOrigins must remain pinned by that lease until Stop succeeds.

type FullVerdictCatalog

type FullVerdictCatalog struct {
	// contains filtered or unexported fields
}

FullVerdictCatalog is local provenance, not proof of kernel publication or health. It must not be copied after first use. One catalogue belongs to one exact binding and must outlive that owner's event subscription.

func NewFullVerdictCatalog

func NewFullVerdictCatalog(binding sandboxpolicy.Binding) *FullVerdictCatalog

func (*FullVerdictCatalog) Abort

func (c *FullVerdictCatalog) Abort(generation uint64) error

Abort removes only an uncommitted pending attempt after the kernel publisher confirms it did not commit. The attempt number is never reusable.

func (*FullVerdictCatalog) Commit

func (c *FullVerdictCatalog) Commit(generation uint64) error

Commit records an irreversible kernel commit, even if publication finalization failed. It is idempotent for the active generation. Never Abort a committed publication: retain its provenance while resuming the same kernel generation.

func (*FullVerdictCatalog) Decode

func (*FullVerdictCatalog) Stage

func (c *FullVerdictCatalog) Stage(generation uint64, plan sandboxpolicy.Plan, program *fullpolicy.KernelProgram) error

Stage validates and snapshots provenance BEFORE calling the kernel publisher. Once admitted (no pending publication), an attempt number is consumed even if validation fails. Resumption uses the existing staged generation, not Stage. Staged events can be decoded because kernel commit may precede its Go receipt.

type FullVerdictDecoder

type FullVerdictDecoder struct {
	// contains filtered or unexported fields
}

FullVerdictDecoder snapshots bounded immutable provenance. It does not attach programs or attest that the kernel supplied complete or trustworthy facts.

func NewFullVerdictDecoder

func NewFullVerdictDecoder(binding sandboxpolicy.Binding, plan sandboxpolicy.Plan, program *fullpolicy.KernelProgram) (*FullVerdictDecoder, error)

func (*FullVerdictDecoder) Decode

type ImageIndexLimits

type ImageIndexLimits struct{ Roots, Files, Entries, Depth, PathBytes int }

ImageIndexLimits may tighten, never enlarge, the finite indexing budget. Zero selects the hard maximum for that dimension.

type ImageInode

type ImageInode struct {
	Inode        uint64
	Major, Minor uint32
}

type Instance

type Instance interface {
	Ready() error
	Unbind(context.Context, execruntime.ContainerIdentity) error
	Stop(context.Context) error
}

type KernelEventStats

type KernelEventStats struct {
	Owned, Retired                       KernelEventTotals
	OwnedInstances, OwnedUnavailable     uint64
	RetiredInstances, RetiredUnavailable uint64
}

KernelEventStats covers this backend's lifetime (not process restarts). Owned includes partial-startup and retiring instances. Retired retains final snapshots after instance removal. Unavailable counts MUST be checked before interpreting zero loss. Live snapshots are not atomic across CPUs/instances.

type KernelEventTotals

type KernelEventTotals struct {
	Submitted, Lost, ObservationErrors uint64
}

KernelEventTotals contains successfully read kernel counter contributions. On read failure, the last successful sample is retained as a lower bound. These counters exclude early native owner refusals; Lost measures failed ring reservations, not userspace queue loss or complete denied-exec event coverage.

type Lease

type Lease interface {
	Check() error
	Close() error
}

Lease pins the exact live identity for the entire instance lifetime.

type LinuxValidator

type LinuxValidator struct{ ProcRoot, CgroupRoot string }

LinuxValidator uses host-visible procfs and the unified cgroup mount. Runtime and container ID must originate from the authoritative runtime cache; neither is inferred from cgroup names. Nonempty roots support node-agent host mounts.

Binding cgroup paths are host-absolute (IG reads them in PID 1's cgroup namespace and CgroupRoot is the host cgroup2 mount), but the kernel renders /proc/<pid>/cgroup relative to the reader's cgroup namespace. A pod-confined agent (containerd on cgroup v2 gives every non-host container a private cgroupns) would read "0::/../<path>", so membership is re-read only from the pinned initial cgroup namespace of ProcRoot's PID 1.

func (LinuxValidator) Acquire

type RawFullVerdict

type RawFullVerdict struct {
	RawVerdict
	MatchedRules [4]uint64
	Error        uint32
	// Shared reports that the event carried the additive shared-engine fields
	// (event ABI 1: exec_class, scope, exec_id, pass, uncertain,
	// facts_unknown, load_epoch); they are zero otherwise. task_cookie is
	// optional within that ABI: HasTaskCookie reports its presence.
	Shared                                   bool
	ExecClass, Pass, Uncertain, FactsUnknown uint32
	Scope, ExecID, LoadEpoch                 uint64
	HasTaskCookie                            bool
	TaskCookie                               uint64
}

func ReadFullVerdict

func ReadFullVerdict(ds datasource.DataSource, data datasource.Data) (RawFullVerdict, error)

ReadFullVerdict checks schema presence before invoking typed accessors. Bitmap words use the producer's byte order, not the host's or the IR encoding order.

type RawVerdict

type RawVerdict struct {
	Generation, Cgroup uint64
	Deny, Mode, PID    uint32
	PathResult         int32
	Path               string
}

type SharedEngine

type SharedEngine struct {
	// contains filtered or unexported fields
}

SharedEngine implements FullEngine and FullEngineCloser over one lazily started node. Events demultiplex by the bound cgroup and must carry the binding's route scope once it is known.

func NewSharedProductEngine

func NewSharedProductEngine(ctx context.Context, rt runtime.Runtime, c SharedProductConfig, onError func(error)) (*SharedEngine, error)

NewSharedProductEngine selects the running kernel build's image now, at agent start (fullruntime.SelectSharedProductImage), loads its profile and binds its manifest digest. Any refusal leaves an engine that never starts: every Start fails and Health reports the reason (wrapping fullruntime.ErrSharedNativeUnavailable); nothing falls back to another image or engine. Otherwise the node starts on the first Start, through a manager of the borrowed runtime, after binding the manifest again.

func NewUnavailableSharedEngine

func NewUnavailableSharedEngine(reason error, onError func(error)) *SharedEngine

NewUnavailableSharedEngine returns a product engine refused at agent start for reason (for example ErrKernelNotQualified): it never starts, every Start fails and Health reports the reason, wrapping fullruntime.ErrSharedNativeUnavailable. The reason is reported once.

func (*SharedEngine) Close

func (e *SharedEngine) Close(ctx context.Context) error

Close stops the node after every instance was stopped. An error retains the node for a retried Close; no binding is admitted after Close found none (a Start that reserved its cgroup first makes Close refuse).

func (*SharedEngine) Health

func (e *SharedEngine) Health() SharedNodeHealth

Health reads the node's witnesses without starting it and never waits on a start in progress.

func (*SharedEngine) Start

func (e *SharedEngine) Start(ctx context.Context, id string, config FullStartConfig, emit func(RawFullVerdict)) (FullInstance, error)

Start binds the trusted binding to a route slot; Activate publishes.

type SharedEngineConfig

type SharedEngineConfig struct {
	Profile fullruntime.SharedProfile
	// Image names the trusted shared image in Store (an explicit OCI target
	// is pretrusted by IG, not signature-verified here; the product start
	// also binds its manifest digest).
	Image string
	Store oras.ReadOnlyTarget
	// ContainerdAddress is the containerd socket as seen by the agent (empty:
	// no image index, FromImage policies are refused by IG). ImageProcRoot and
	// ImageHostRoot default to SharedDefaultImageProcRoot/HostRoot.
	ContainerdAddress            string
	ImageProcRoot, ImageHostRoot string
	FailClosedPollInterval       time.Duration
	RevisionDrainTimeout         time.Duration
}

SharedEngineConfig is administrator configuration, never policy input.

type SharedNodeHealth

type SharedNodeHealth struct {
	// Qualification: the qualification engine (never Ready).
	Qualification bool
	// Unavailable is the product engine's refusal at agent start (wraps
	// fullruntime.ErrSharedNativeUnavailable); nothing was started.
	Unavailable error
	// StartErr is the last failed node start while none succeeded.
	StartErr error
	// AttachRefusal is the native attach capacity refusal IG reported while
	// a node start is still retrying (nil once cleared, or once the start
	// ended). Status only.
	AttachRefusal error
	// BindingFaults joins the bindings' latched commit-time protocol faults
	// (Degraded here; each one also fails its binding's Check).
	BindingFaults                  error
	Started                        bool
	Ready, FailClosedErr, FactsErr error
	// Degraded is the node's Degraded conditions (product only).
	Degraded    error
	CountersErr error
	FailClosed  fullruntime.SharedFailClosedHealth
	Facts       fullruntime.SharedFactHealth
	Counters    fullruntime.KernelEventCounters
}

SharedNodeHealth is one reading of the node's health witnesses.

type SharedProductConfig

type SharedProductConfig struct {
	// Images is keyed by kernel BTF sha256.
	Images map[string]SharedProductImage
	// Store is the agent's read-only image archive.
	Store oras.ReadOnlyTarget
	// ContainerdAddress, ImageProcRoot and ImageHostRoot as in
	// SharedEngineConfig.
	ContainerdAddress            string
	ImageProcRoot, ImageHostRoot string
}

SharedProductConfig is the product engine's administrator configuration.

type SharedProductImage

type SharedProductImage struct {
	Image, ProfileFile, ManifestDigest string
	Profile                            *fullruntime.SharedProfile
}

SharedProductImage is one kernel build's product image: the image reference in Store, the profile it was built with (Profile when set, else the JSON at ProfileFile) and the digest of its manifest for this architecture.

type Validator

type Validator interface {
	Acquire(context.Context, sandboxpolicy.Binding) (Lease, error)
}

Jump to

Keyboard shortcuts

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