Documentation
¶
Overview ¶
Package devicestate is the node-agent side of device state persistence: it follows the snapshot-backed device containers of a node, detects changes of their writable layer, and turns them into snapshot images in the platform registry. The container runtime, the cluster API and the registry are interfaces, so the logic runs (and is tested) without containerd.
Index ¶
- Constants
- Variables
- func AcquireCaptureOwner(workDir string) (*os.File, error)
- func AppArmorBlocksSnapshots(label string) bool
- func AppArmorLabel() string
- func CaptureCommittedDeletePreconditions(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) (*metav1.Preconditions, error)
- func CaptureCommittedGuardMatches(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) bool
- func CaptureDeletePreconditions(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) (*metav1.Preconditions, error)
- func CaptureGuardMatches(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) bool
- func CgroupDir(root, cgroupsPath string) string
- func Debounce(ctx context.Context, in <-chan struct{}, quiet, maxWait time.Duration, ...)
- func FindCgroup(root, containerID string) string
- func Fingerprint(root string, pol snapshot.Policy) string
- func Forward(ctx context.Context, listen, target string, log logr.Logger, ...) error
- func Freeze(ctx context.Context, dir string) (thaw func(), err error)
- func FreezeRequired(ctx context.Context, dir string) (thaw func() error, err error)
- func ThawOrphans(root string) []string
- func ThawOrphansExcept(root string, protected map[string]bool) []string
- func UnixTransport(sock string) *http.Transport
- func UpperDir(mounts []mount.Mount) string
- func Watch(ctx context.Context, root string, pol snapshot.Policy, poll time.Duration, ...) (<-chan struct{}, error)
- func WatchWith(ctx context.Context, root string, pol snapshot.Policy, o WatchOptions) (<-chan struct{}, error)
- type CaptureCluster
- type CaptureCommitCluster
- type Cluster
- type Container
- type ContainerdRuntime
- func (r *ContainerdRuntime) Close() error
- func (r *ContainerdRuntime) Diff(ctx context.Context, c Container, freeze bool, pol snapshot.Policy) (io.ReadCloser, error)
- func (r *ContainerdRuntime) Exits(ctx context.Context) (<-chan string, error)
- func (r *ContainerdRuntime) Inspect(ctx context.Context, id string) (Container, error)
- func (r *ContainerdRuntime) LoadImage(ctx context.Context, ref string) (v1.Image, error)
- func (r *ContainerdRuntime) LoadImageForPod(ctx context.Context, c Container, _ PodInfo) (v1.Image, error)
- func (r *ContainerdRuntime) Quiesce(ctx context.Context, c Container) (func() error, error)
- func (r *ContainerdRuntime) TaskAlive(ctx context.Context, c Container) (bool, error)
- func (r *ContainerdRuntime) Thaw(ctx context.Context, c Container) error
- type Engine
- func (e *Engine) CaptureRequired(ctx context.Context, p PodInfo, req api.DeviceCaptureRequest) (result api.DeviceCaptureResult, err error)
- func (e *Engine) RecoverCaptureHolds(ctx context.Context) (map[string]bool, error)
- func (e *Engine) Run(ctx context.Context) error
- func (e *Engine) Sync(ctx context.Context)
- type ForwardOption
- type KubeCluster
- func (k *KubeCluster) AcknowledgeCaptureCommit(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) error
- func (k *KubeCluster) CaptureCommitRequested(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) (bool, error)
- func (k *KubeCluster) CapturePods(ctx context.Context) ([]PodInfo, error)
- func (k *KubeCluster) CheckCapture(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) (bool, error)
- func (k *KubeCluster) InvalidateCapture(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) error
- func (k *KubeCluster) MarkExit(ctx context.Context, p PodInfo) error
- func (k *KubeCluster) Pods(ctx context.Context) ([]PodInfo, error)
- func (k *KubeCluster) Record(ctx context.Context, p PodInfo, s Snapshot) error
- func (k *KubeCluster) RecordCapture(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) error
- func (k *KubeCluster) SetCaptureGuard(ctx context.Context, p PodInfo, req api.DeviceCaptureRequest, boot string) error
- func (k *KubeCluster) Warn(ctx context.Context, p PodInfo, msg string) error
- type PanicError
- type PodInfo
- type Pusher
- type RequiredRuntime
- type Runtime
- type Snapshot
- type SourceImageRuntime
- type WatchBudget
- type WatchOptions
Constants ¶
const ( // DefaultScanEntries is how many entries one scan or one watch registration looks at. DefaultScanEntries = 200000 // DefaultScanTime is how long one scan or one watch registration may take. DefaultScanTime = 10 * time.Second )
The writable layer is a participant's file system. Every walk of it goes through an os.Root opened on the layer (a symlink swapped in during the walk cannot lead it out of the layer), reads a directory in batches, and stops at a cap on the entries it looks at and on its time: a layer with millions of entries or one that is made to stall a walk costs the node a bounded amount.
const (
CaptureGuardAnnotation = "laboratory.cybericebox.com/capture-guard"
)
const DefaultMaxConcurrentDiffs = 2
DefaultMaxConcurrentDiffs is how many layers the node diffs at once. A diff reads a whole writable layer and writes the filtered tar to StateWorkDir; devices of many tenants share the node, so how many run together is a limit of the node and not of a device.
const DefaultMaxWatchDirs = 2000
DefaultMaxWatchDirs is how many directories of all the writable layers of the node are watched with inotify together. A watch costs kernel memory and the limit (fs.inotify.max_user_watches) is shared by everything on the node, so devices that make a million directories must not be able to use it all: past the budget a layer is only polled.
const DefaultPollInterval = 30 * time.Second
DefaultPollInterval is how often the layer is scanned as a safety net next to the filesystem events.
const DefaultPrescanTime = 20 * time.Second
DefaultPrescanTime is how long the pre-scan of a layer may take before the layer is refused as too big to look at.
Variables ¶
var ErrDeleting = errors.New("capture Pod deletion has been accepted; quiescence must remain held")
var ErrNoFreezer = errors.New("cgroup v2 freezer not available")
ErrNoFreezer is returned when the container cgroup cannot be frozen (cgroup v1 or an unknown cgroup path). The snapshot is then taken without freezing.
var ErrSnapshotsBlocked = errors.New("AppArmor blocks snapshots")
ErrSnapshotsBlocked is returned instead of a snapshot when the node-agent's AppArmor profile blocks the snapshot mounts (Engine.SnapshotsBlocked). Nothing is diffed or frozen: every attempt would fail the same way until the node-agent restarts under another profile.
var ErrStale = errors.New("pod is not the current incarnation of its device")
ErrStale is returned by Cluster writes for a pod that is no longer the current one of its device (reset, or a newer incarnation): its state is obsolete.
Functions ¶
func AcquireCaptureOwner ¶ added in v1.1.0
AcquireCaptureOwner serializes startup recovery, API invalidation and thaw across node-agent processes. Hold it until all capture workers have exited.
func AppArmorBlocksSnapshots ¶ added in v1.7.0
AppArmorBlocksSnapshots reports whether label, the AppArmor label of the node-agent (the content of /proc/self/attr/current), is the container runtime's default profile in enforce mode. That profile has `deny mount`, and the snapshot filter mounts read-only overlay views of the device's layers, so every snapshot would fail with "permission denied".
func AppArmorLabel ¶ added in v1.7.0
func AppArmorLabel() string
AppArmorLabel is the AppArmor label of this process; empty when AppArmor is off or the label cannot be read.
func CaptureCommittedDeletePreconditions ¶ added in v1.1.0
func CaptureCommittedDeletePreconditions(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) (*metav1.Preconditions, error)
func CaptureCommittedGuardMatches ¶ added in v1.1.0
func CaptureCommittedGuardMatches(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) bool
func CaptureDeletePreconditions ¶ added in v1.1.0
func CaptureDeletePreconditions(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) (*metav1.Preconditions, error)
CaptureDeletePreconditions supplies the exact current Pod fence after the caller direct-reads the current lifecycle, Device and Pod. On Conflict, reread those objects and repeat; never substitute the capture-time RV.
func CaptureGuardMatches ¶ added in v1.1.0
func CaptureGuardMatches(p *corev1.Pod, req *api.DeviceCaptureRequest, result *api.DeviceCaptureResult) bool
CaptureGuardMatches is the controller's barrier predicate. Call it only on direct-read current Pod and Device. Delete uses that current Pod UID/RV, not the result's capture-time resourceVersion (which is audit information).
func CgroupDir ¶
CgroupDir turns the cgroup path from a container's OCI spec into its directory under the cgroup v2 mount at root. It understands both layouts the kubelet produces: the systemd driver ("kubepods-burstable-pod<uid>.slice:cri-containerd:<id>", whose slice name expands into nested slice directories) and cgroupfs ("/kubepods/burstable/pod<uid>/<id>"). It returns "" when the directory does not exist.
func Debounce ¶
Debounce turns a stream of change signals into snapshot triggers: one trigger after the signals stayed quiet for quiet, or after maxWait of continuous signals (so a constantly written layer is still snapshotted). It returns when ctx ends or in is closed.
func FindCgroup ¶
FindCgroup searches the cgroup tree for the directory of a container by id. The kubelet places it under a kubepods hierarchy; it is used when the path from the spec does not resolve.
func Fingerprint ¶
Fingerprint summarises a layer directory: every non-excluded entry with its size, modification time and mode. Two scans differ when something changed. A layer past the scan caps has one fixed fingerprint (see overCapFingerprint).
func Forward ¶
func Forward(ctx context.Context, listen, target string, log logr.Logger, opts ...ForwardOption) error
Forward listens on listen (a loopback address) and relays the registry requests of the node's container runtime and the kubelet to target, the registry gate. The node-agent uses it to make the cluster-internal registry reachable as localhost:<port>, which the runtime treats as plain HTTP, so no host configuration (registries.yaml, hosts.toml, certificates, DNS) is needed.
The relay is HTTP-aware and has the identity of the node and nothing else to give: every request it forwards carries the projected ServiceAccount token of the node-agent (WithNodeToken) in X-Cib-Node-Token, and no header the client sent is believed: every X-Cib-* header and the client's Authorization header are removed. There is no credential on the node and none is needed: the gate decides by the node and the reference (the tenant is in the image path).
This listener serves pulls only: GET and HEAD on /v2/, /v2/c/** (the image cache) and /v2/lab/** (the snapshots); anything else is answered with 405 before it reaches the gate. Any process on the node can connect to a loopback port, so what arrives here must be no more than what the container runtime gets. Pushes of snapshots go through the unix socket of WithPushSocket (ServePush). It returns when ctx ends.
func Freeze ¶
Freeze freezes every process of the cgroup and returns the function that thaws it. The freeze is confirmed through cgroup.events before it returns.
func FreezeRequired ¶ added in v1.1.0
FreezeRequired retains ownership of the requested freeze even if confirmation fails. Its caller must fence the API before thawing, or wait for actual death. Ordinary snapshots keep using Freeze's automatic error cleanup.
func ThawOrphans ¶
ThawOrphans thaws container cgroups left frozen, which happens when the node-agent dies in the middle of a snapshot. Nothing else freezes them. It returns the directories it thawed.
func ThawOrphansExcept ¶ added in v1.1.0
ThawOrphansExcept preserves required captures that still own live tasks.
func UnixTransport ¶ added in v1.10.0
UnixTransport is a transport that dials the unix socket at sock whatever the URL says: the client keeps the logical host of the registry (localhost:<port>) in every name and reference, and the socket is how it reaches the relay.
func Watch ¶
func Watch(ctx context.Context, root string, pol snapshot.Policy, poll time.Duration, maxDirs int) (<-chan struct{}, error)
Watch reports changes of a writable layer directory; maxDirs is the budget of watched directories for this layer alone. The engine uses WatchWith with the node-wide budget.
func WatchWith ¶ added in v1.10.0
func WatchWith(ctx context.Context, root string, pol snapshot.Policy, o WatchOptions) (<-chan struct{}, error)
WatchWith reports changes of a writable layer directory. It combines two signals: inotify events on the directory tree (low latency; directories are added as they appear, excluded paths are not watched) and a periodic scan that compares a fingerprint of the tree. The scan is the safety net for what events miss: the kernel's inotify watch limit, and overlayfs, which does not always raise events on the upper directory for changes made through the overlay mount. The returned channel is closed when ctx ends, and the layer's share of the watch budget is given back then.
Types ¶
type CaptureCluster ¶ added in v1.1.0
type CaptureCluster interface {
SetCaptureGuard(context.Context, PodInfo, api.DeviceCaptureRequest, string) error
RecordCapture(context.Context, PodInfo, api.DeviceCaptureResult) error
InvalidateCapture(context.Context, PodInfo, api.DeviceCaptureResult) error
CheckCapture(context.Context, PodInfo, api.DeviceCaptureResult) (bool, error)
}
CaptureCluster uses direct reads and optimistic Pod locks, independent of legacy exit markers.
type CaptureCommitCluster ¶ added in v1.1.0
type CaptureCommitCluster interface {
CaptureCommitRequested(context.Context, PodInfo, api.DeviceCaptureResult) (bool, error)
AcknowledgeCaptureCommit(context.Context, PodInfo, api.DeviceCaptureResult) error
}
CaptureCommitCluster is the minimal durable final-capture-to-stop seam. Required capture remains compatible; an operator never deletes until this exact capture's committed acknowledgement is present in status and guard.
type Cluster ¶
type Cluster interface {
// Pods lists the snapshot-backed device pods scheduled on this node.
Pods(ctx context.Context) ([]PodInfo, error)
// Record stores a successful snapshot and clears the warning.
Record(ctx context.Context, p PodInfo, s Snapshot) error
// Warn stores a warning and keeps the last good snapshot.
Warn(ctx context.Context, p PodInfo, msg string) error
// MarkExit records that the exit snapshot of the pod is finished.
MarkExit(ctx context.Context, p PodInfo) error
}
Cluster is the Kubernetes side: which pods to follow and where to report. Every write is guarded by the reset epoch: it is dropped (ErrStale) when the device has been reset since the pod was created.
type Container ¶
type Container struct {
ID string
// ImageRef is the image the container was created from.
ImageRef string
// UpperDir is the writable layer directory on the node.
UpperDir string
// Cgroup is the container's cgroup directory (cgroup v2), "" if unknown.
Cgroup string
// Snapshotter and SnapshotKey name the container's writable snapshot in the
// runtime; they are private to the Runtime implementation.
Snapshotter string
SnapshotKey string
// IDs are the user and group id maps of the container's user namespace (empty without one): the diff of its writable layer
// holds host ids, which a snapshot must not keep.
IDs snapshot.IDMaps
// OwnershipKnown distinguishes a read OCI no-userns map from missing metadata.
OwnershipKnown bool
}
Container is the runtime view of a device container.
type ContainerdRuntime ¶
type ContainerdRuntime struct {
// contains filtered or unexported fields
}
ContainerdRuntime is the Runtime backed by the node's containerd, reached through the CRI socket (containerd serves its native API on the same one).
func NewContainerdRuntime ¶
func NewContainerdRuntime(sock, namespace, cgroupRoot string, log logr.Logger) (*ContainerdRuntime, error)
NewContainerdRuntime connects to containerd at sock; namespace is the one the kubelet's CRI uses ("k8s.io"); cgroupRoot is where the host's cgroup v2 tree is mounted.
func (*ContainerdRuntime) Close ¶
func (r *ContainerdRuntime) Close() error
Close releases the connection.
func (*ContainerdRuntime) Diff ¶
func (r *ContainerdRuntime) Diff(ctx context.Context, c Container, freeze bool, pol snapshot.Policy) (io.ReadCloser, error)
Diff implements Runtime: the containerd diff service compares the container's active snapshot with its parent. Containerd provides whiteouts, opaque markers and security.capability; rooted metadata reads preserve user.* attributes and supplement attribute-only changes. Directory attribute removals fail explicitly because containerd's directory merge cannot restore them faithfully.
func (*ContainerdRuntime) Exits ¶
func (r *ContainerdRuntime) Exits(ctx context.Context) (<-chan string, error)
Exits implements Runtime: init-process exit events of the CRI namespace. The subscription is re-established after a connection error.
func (*ContainerdRuntime) LoadImage ¶
LoadImage implements Runtime: the image the kubelet pulled for this container is read out of the content store, so no registry is contacted.
func (*ContainerdRuntime) LoadImageForPod ¶ added in v1.1.0
func (r *ContainerdRuntime) LoadImageForPod(ctx context.Context, c Container, _ PodInfo) (v1.Image, error)
LoadImageForPod is LoadImage for the source image of a device pod. A layer that the content store does not have is read through the relay of the node-agent (the reference points at it) with no credentials: the gate decides by the node and the reference, and this pod is on this node and names this reference.
func (*ContainerdRuntime) Quiesce ¶ added in v1.1.0
Quiesce uses the native freezer and treats sync failures as required-capture failures. On sync failure the caller still owns the thaw function and must invalidate first.
type Engine ¶
type Engine struct {
Runtime Runtime
NodeAgentEpoch string
Cluster Cluster
Pusher Pusher
// RegistryHost is host:port under which this node reaches the registry; an
// image reference starting with it is a snapshot image.
RegistryHost string
// WorkDir holds the temporary layer files of a snapshot.
WorkDir string
// MaxWatchDirs is how many directories of ALL the writable layers of the node are watched with inotify together (the kernel's watch
// limit is shared by everything on the node, and one budget is shared by every device); past it a layer is only polled. Zero means
// DefaultMaxWatchDirs.
MaxWatchDirs int
// Poll is the writable-layer scan interval (DefaultPollInterval when zero).
Poll time.Duration
// Resync is how often the pods are re-listed (5s when zero).
Resync time.Duration
// ExitTimeout bounds the exit snapshot so it ends before the controller
// stops waiting for it (25s when zero).
ExitTimeout time.Duration
// MaxConcurrentDiffs is how many layers the node diffs at once (DefaultMaxConcurrentDiffs when zero); TempBudgetBytes is how many bytes
// of temporary files in WorkDir all the running diffs may hold together (each reserves the write quota of its device; zero: no budget
// beyond the number of diffs). PrescanTime caps the look at a layer before its diff (DefaultPrescanTime when zero).
MaxConcurrentDiffs int
TempBudgetBytes int64
PrescanTime time.Duration
// RetryBase and RetryMax bound the retry of a failed snapshot (10s doubling to 5m when zero).
RetryBase, RetryMax time.Duration
Log logr.Logger
// Now is the clock; nil means time.Now.
Now func() time.Time
// SnapshotsBlocked, when set, is why no snapshot can be taken on this node (an AppArmor profile that denies mount): devices are
// still followed, but each gets it as its warning and no snapshot is attempted.
SnapshotsBlocked string
// contains filtered or unexported fields
}
Engine follows the snapshot-backed device containers of one node.
func (*Engine) CaptureRequired ¶ added in v1.1.0
func (e *Engine) CaptureRequired(ctx context.Context, p PodInfo, req api.DeviceCaptureRequest) (result api.DeviceCaptureResult, err error)
CaptureRequired explicitly captures a live incarnation and keeps it frozen until actual task death or API-fenced invalidation. It never uses ExitSnapshotPod.
func (*Engine) RecoverCaptureHolds ¶ added in v1.1.0
RecoverCaptureHolds invalidates prior live acknowledgements before startup thaw and preserves deleting/missing Pod holds until actual runtime task death.
type ForwardOption ¶
type ForwardOption func(*forwardOptions)
ForwardOption configures Forward.
func WithNodeToken ¶ added in v1.10.0
func WithNodeToken(tokenFile string) ForwardOption
WithNodeToken gives every request the projected ServiceAccount token in tokenFile (audience laboratory-registry-gate), read again every imagecache.TokenReread, in the header X-Cib-Node-Token. A relay without it does not start: it would have no identity.
func WithPlainDevelopment ¶ added in v1.10.0
func WithPlainDevelopment() ForwardOption
WithPlainDevelopment is the development setup: the relay speaks plain http to the registry and sends no token, so nothing of the node's identity can travel in the clear. A real setup has a certificate authority (WithTLS) and a token (WithNodeToken).
func WithPushSocket ¶ added in v1.10.0
func WithPushSocket(path string, uid int) ForwardOption
WithPushSocket makes the relay serve the snapshot push of node-state on a unix socket at path (mode 0600, owned by uid when uid is not negative: the user of node-state), apart from the TCP listener that cannot be told from any other process of the node.
func WithTLS ¶ added in v1.10.0
func WithTLS(caFile string) ForwardOption
WithTLS makes the forwarder dial the registry over TLS, trusting only the certificate authority in caFile; the name the server's certificate must carry is the host of the target.
type KubeCluster ¶
type KubeCluster struct {
// Client reads from the informer cache.
Client client.Client
// Reader reads straight from the API server; every status write re-reads
// through it so the epoch guard never acts on a stale cache.
Reader client.Reader
NodeName string
}
KubeCluster is the Cluster backed by the Kubernetes API: the device pods of this node are found through their annotations and the Device CR carries the policy and receives the snapshot status.
func (*KubeCluster) AcknowledgeCaptureCommit ¶ added in v1.1.0
func (k *KubeCluster) AcknowledgeCaptureCommit(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) error
func (*KubeCluster) CaptureCommitRequested ¶ added in v1.1.0
func (k *KubeCluster) CaptureCommitRequested(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) (bool, error)
func (*KubeCluster) CapturePods ¶ added in v1.1.0
func (k *KubeCluster) CapturePods(ctx context.Context) ([]PodInfo, error)
CapturePods bypasses the informer cache during crash recovery.
func (*KubeCluster) CheckCapture ¶ added in v1.1.0
func (k *KubeCluster) CheckCapture(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) (bool, error)
func (*KubeCluster) InvalidateCapture ¶ added in v1.1.0
func (k *KubeCluster) InvalidateCapture(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) error
InvalidateCapture first changes the current Pod RV. Any deletion using the previous guard/RV now conflicts. A deleting Pod is never modified or thawed.
func (*KubeCluster) MarkExit ¶
func (k *KubeCluster) MarkExit(ctx context.Context, p PodInfo) error
MarkExit implements Cluster.
func (*KubeCluster) Pods ¶
func (k *KubeCluster) Pods(ctx context.Context) ([]PodInfo, error)
Pods implements Cluster.
func (*KubeCluster) RecordCapture ¶ added in v1.1.0
func (k *KubeCluster) RecordCapture(ctx context.Context, p PodInfo, result api.DeviceCaptureResult) error
func (*KubeCluster) SetCaptureGuard ¶ added in v1.1.0
func (k *KubeCluster) SetCaptureGuard(ctx context.Context, p PodInfo, req api.DeviceCaptureRequest, boot string) error
type PanicError ¶ added in v1.10.0
PanicError is what a recovered panic of a goroutine of the snapshot engine is reported as.
func (*PanicError) Error ¶ added in v1.10.0
func (e *PanicError) Error() string
type PodInfo ¶
type PodInfo struct {
// Device is the Device CR the pod belongs to.
Device types.NamespacedName
Pod string
UID string
ResourceVersion string
CaptureRequest *api.DeviceCaptureRequest
Capture *api.DeviceCaptureResult
Guard string
Deleting bool
// Incarnation is the pod's incarnation number; only the current incarnation
// of a device records snapshots.
Incarnation int32
// ContainerID is the runtime id of the device container; empty until started.
ContainerID string
Running bool
// Ended is true once the pod finished (container exited).
Ended bool
// Epoch is the reset epoch the pod was created in; DeviceEpoch is the
// device's current one. A pod of an older epoch is never snapshotted.
Epoch int32
DeviceEpoch int32
// ExitDone is true when the exit snapshot of this pod is already finished.
ExitDone bool
Policy snapshot.Policy
Repo string
// Tenant is the tenant the device belongs to (names.DefaultTenant when the device carries no tenant label).
Tenant string
// contains filtered or unexported fields
}
PodInfo is what the engine needs to know about one snapshot-backed device pod on this node.
type Pusher ¶
type Pusher interface {
Push(ctx context.Context, repo string, img v1.Image, baseLayers int, sourceRepo string) (ref string, digest v1.Hash, err error)
}
Pusher publishes snapshot images; *snapshot.Registry implements it.
type RequiredRuntime ¶ added in v1.1.0
type RequiredRuntime interface {
// Quiesce returns an owned thaw handle whenever freeze was requested, even on error.
Quiesce(context.Context, Container) (func() error, error)
// Thaw releases a known current container hold only after caller API invalidation.
Thaw(context.Context, Container) error
TaskAlive(context.Context, Container) (bool, error)
}
RequiredRuntime must fail when strict quiescence or task liveness cannot be established.
type Runtime ¶
type Runtime interface {
// Inspect finds a container by id.
Inspect(ctx context.Context, containerID string) (Container, error)
// Diff returns the uncompressed layer tar of the container's writable layer
// against its parent snapshot. With freeze the container is frozen and its
// filesystem synced while the diff is computed, so the result is consistent;
// without it (the container has exited) nothing runs and nothing is frozen.
// Closing the reader releases everything the diff held.
Diff(ctx context.Context, c Container, freeze bool, policy snapshot.Policy) (io.ReadCloser, error)
// LoadImage opens the image a container was created from out of the local
// image store, with the snapshot chain already on the node.
LoadImage(ctx context.Context, imageRef string) (v1.Image, error)
// Exits reports the ids of containers whose task exited, until ctx ends.
Exits(ctx context.Context) (<-chan string, error)
}
Runtime is the container runtime facade.
type Snapshot ¶
type Snapshot struct {
// Image is the pullable reference with digest; empty when the writable
// layer holds nothing beyond the image the device started from and that
// image is the base image.
Image string
At time.Time
SizeBytes int64
Layers int32
}
Snapshot is the outcome of a successful snapshot.
type SourceImageRuntime ¶ added in v1.1.0
type SourceImageRuntime interface {
LoadImageForPod(context.Context, Container, PodInfo) (v1.Image, error)
}
SourceImageRuntime optionally binds source image reads to the current device pod. Runtimes without this capability retain the local-only LoadImage behavior.
type WatchBudget ¶ added in v1.10.0
type WatchBudget struct {
// contains filtered or unexported fields
}
WatchBudget is the node-wide budget of watched directories, shared by every layer that is followed; a layer gives its share back when its watch ends.
func NewWatchBudget ¶ added in v1.10.0
func NewWatchBudget(max int) *WatchBudget
NewWatchBudget is a budget of max directories (DefaultMaxWatchDirs when max is not positive).
func (*WatchBudget) Used ¶ added in v1.10.0
func (b *WatchBudget) Used() int
Used is how many directories are watched now.
type WatchOptions ¶ added in v1.10.0
type WatchOptions struct {
// Poll is the interval of the periodic scan (DefaultPollInterval when zero).
Poll time.Duration
// Budget is the node-wide budget of watched directories shared by every layer; nil gives this layer a budget of its own.
Budget *WatchBudget
// ScanEntries and ScanTime cap one scan or registration (DefaultScanEntries and DefaultScanTime when zero).
ScanEntries int
ScanTime time.Duration
// OnOverCap is called at most once, when the layer is past a cap and is watched by events alone.
OnOverCap func()
// OnPanic is told when the watcher goroutine panicked (it has stopped: the channel is closed); nil: ignored.
OnPanic func(error)
}
WatchOptions configures WatchWith.