checker

package
v1.10.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	// LabelChecker marks the Leases of the checkers.
	LabelChecker = "laboratory.cybericebox.com/checker"
	// AnnotationState is "ready" or "unavailable: <CODE>: <detail>" (the start-up check of the node, like the node annotations of
	// the node-agent). AnnotationVersion is the image tag the checker runs.
	AnnotationState   = "laboratory.cybericebox.com/checker-state"
	AnnotationVersion = "laboratory.cybericebox.com/checker-version"

	KeepaliveInterval = 20 * time.Second
	// LeaseDuration is how long a Lease counts as fresh after a renewal (three intervals).
	LeaseDuration = 60 * time.Second
)

The keepalive of a checker instance: one Lease per node (not one signal per check), renewed every KeepaliveInterval. Silence of a check then means "no change" while the Lease is fresh, and "the checker is dead" when it is not. The management agent can read the Leases (label LabelChecker) and report them; today nothing reads them.

View Source
const AckManager = "lab-checker-ack"

AckManager is the field manager of status.checksRunAck.

View Source
const ErrorsBeforePublish = 3

ErrorsBeforePublish is how many scheduled runs in a row must fail (state error) before "error" replaces a result that is already published as passed or not_passed. A manual run publishes an error at once.

What is written on error, precisely:

  • no result published yet for the check: "error" with its detail, at once;
  • a passed / not_passed result is published: nothing is written for the first ErrorsBeforePublish-1 failed scheduled runs, so a hiccup of the device (a restart, a slow exec) never touches what the participant has earned;
  • after that, or at once for a manual run: state error with the detail, changedMs = now, firstPassedMs KEPT (it is never cleared), value cleared. The consumer keeps the state of the previous change (contract section 3);
  • the next run that gives passed or not_passed replaces the error. A once check that has passed never runs again, so an error can never replace its pass.

Variables

This section is empty.

Functions

func CacheOptions

func CacheOptions(node string) (map[client.Object]cache.ByObject, error)

CacheOptions are the informers of a checker: the device pods of its own node only (a field selector the API server applies), and the Labs, stripped of everything the checker does not read. A Lab cannot be selected by node; the cost of watching them all is the one the node-agent already pays.

func LeaseName

func LeaseName(node string) string

LeaseName is the Lease of the checker of a node.

func ManagerForCheck

func ManagerForCheck(id string) string

ManagerForCheck is the field manager of one check: fixed length and characters whatever the id is.

func ParseChecksSecret

func ParseChecksSecret(s *corev1.Secret) ([]labchecks.Check, error)

ParseChecksSecret reads the checks document of a lab's Secret.

Types

type Backend

type Backend interface {
	Open(ctx context.Context, pod PodInfo) (Observer, func(), error)
}

Backend gives access to a device. The returned function releases what Open took.

type CheckRef

type CheckRef struct {
	ID        string
	Device    string
	ManualRun bool
}

CheckRef is the part of a check that is on the Lab object (LabSpec.checks.items).

type Config

type Config struct {
	Backend Backend
	Writer  Writer
	// MaxConcurrent is the most runs at once on this node. At most one run of a lab is going at any time on a node whatever this is: a lab
	// cannot take the room of the others, and the device access service holds the same rule.
	MaxConcurrent int
	// MaxTimeLimit is the ceiling of the time limit of one run (0: no ceiling beyond the one of the contract). A check that asks for more is
	// run with this limit.
	MaxTimeLimit time.Duration
	// FirstRunWindow spreads the first run of the checks of a device that has just become ready (default 10 s).
	FirstRunWindow time.Duration
	Now            func() time.Time
	Log            logr.Logger
}

Config of an Engine.

type Engine

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

Engine keeps the checks of the labs that have devices on this node, decides what runs when, runs it, and publishes changes. It holds no Kubernetes types except the status values; the informers feed it (see Watcher).

func NewEngine

func NewEngine(cfg Config) *Engine

NewEngine makes an Engine.

func (*Engine) Execute

func (e *Engine) Execute(ctx context.Context, job Job)

Execute makes one run and folds the result in. It is safe to call from several goroutines.

func (*Engine) Flush

func (e *Engine) Flush(ctx context.Context)

Flush writes what changed: one entry per changed check, then the acknowledgements of the requests whose work is done and whose results are written. A failed write is retried with a growing pause; nothing else is lost meanwhile (the entry stays dirty).

func (*Engine) HasPods

func (e *Engine) HasPods(key LabKey) bool

HasPods reports whether the lab has a device pod on this node.

func (*Engine) RemoveLab

func (e *Engine) RemoveLab(key LabKey)

RemoveLab forgets a Lab that is gone.

func (*Engine) RemovePod

func (e *Engine) RemovePod(lab LabKey, device, podUID string)

RemovePod forgets a pod that is gone.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, beat func())

Run drives the engine until ctx ends: every second it asks for the runs that are due and starts them, and flushes changes.

func (*Engine) SetDefinitions

func (e *Engine) SetDefinitions(key LabKey, uid string, checks []labchecks.Check)

SetDefinitions takes the checks document of a lab (read from its Secret). uid guards against a document that arrives for a lab that was deleted and made again in the meantime.

func (*Engine) SetLab

func (e *Engine) SetLab(info LabInfo)

SetLab takes the current state of a Lab object (a new one, or a change).

func (*Engine) SetPod

func (e *Engine) SetPod(p PodInfo)

SetPod takes a device pod of this node (new, or changed).

func (*Engine) Tick

func (e *Engine) Tick(now time.Time) []Job

Tick decides what runs now: it takes new manual requests, applies the barrier and returns the runs that are due, earliest first, at most as many as there is room for. It does no I/O.

type ExecResult

type ExecResult struct {
	Started   bool
	Exit      int
	Signal    string
	TimedOut  bool
	Output    []byte
	Truncated bool
}

ExecResult is the outcome of running a command in a device.

type ExecSpec

type ExecSpec struct {
	Command     []string
	Script      string
	Interpreter string
	User        string
	// Limit is what is left of the check's time limit.
	Limit time.Duration
}

ExecSpec is a custom observation handed to an Executor.

type FileFacts

type FileFacts struct {
	Exists  bool
	Regular bool
	// Type is what the path itself is (file, directory, symlink, and so on).
	Type string
	// Mode holds the permission bits including setuid, setgid and sticky.
	Mode      uint32
	UID, GID  uint32
	User      string
	Group     string
	Content   []byte
	Truncated bool
	// Unmapped is set when the owner is not known in the device (the file belongs to nobody the device knows).
	Unmapped bool
}

FileFacts is what the in-device program saw of one file. UID and GID are the numbers inside the device, User and Group their names when the device's /etc/passwd and /etc/group give one.

type FileProber

type FileProber interface {
	ProbeFile(ctx context.Context, path string, wantContent bool) (FileFacts, error)
}

FileProber is an Observer that can read a file through the in-device program. A file expectation of type or checksum always goes that way, on every device: the node-side reader follows links and so cannot say what the path itself is; one behaviour for all.

type Job

type Job struct {
	Lab    LabKey
	Pod    PodInfo
	Check  labchecks.Check
	Manual bool
}

Job is one run, handed out by Tick.

type Keepalive

type Keepalive struct {
	Client    client.Client
	Namespace string
	Node      string
	// Holder is the name of the pod.
	Holder  string
	Version string
	// State returns the current state text (see AnnotationState).
	State func() string
	Now   func() time.Time
}

Keepalive renews the Lease of this node's checker.

func (*Keepalive) Beat

func (k *Keepalive) Beat(ctx context.Context) error

Beat renews the Lease once (server-side apply under one manager; the Lease is created by the first apply).

func (*Keepalive) Run

func (k *Keepalive) Run(ctx context.Context, onError func(error))

Run renews until ctx ends. A failed renewal is retried at the next interval (the Lease lasts three).

type LabInfo

type LabInfo struct {
	Key  LabKey
	UID  string
	Refs []CheckRef
	// Results are the entries of status.checks; Ack is status.checksRunAck; Request is the run-checks annotation.
	Results map[string]Published
	Ack     int64
	Request RunRequest
	// BootstrapEnabled is spec.devices[].bootstrap.enabled; BootstrapPhase is status.devices[].bootstrap.phase, both by device name.
	BootstrapEnabled map[string]bool
	BootstrapPhase   map[string]laboratoryv1alpha1.BootstrapPhase
	// Inactive: the lab is retired or being deleted; nothing is run for it.
	Inactive bool
}

LabInfo is what the checker reads from a Lab object.

func LabInfoOf

func LabInfoOf(lab *laboratoryv1alpha1.Lab) LabInfo

LabInfoOf reads a (trimmed) Lab into what the engine needs.

type LabKey

type LabKey struct{ Namespace, Name string }

LabKey names a Lab.

func (LabKey) String

func (k LabKey) String() string

type ObserveError

type ObserveError struct {
	Reason string
	Err    error
}

ObserveError is an error whose Reason is safe to publish in a result detail (it names no path of the node and no content).

func (*ObserveError) Error

func (e *ObserveError) Error() string

func (*ObserveError) Unwrap

func (e *ObserveError) Unwrap() error

type Observer

type Observer interface {
	ReadFile(ctx context.Context, path string, wantContent bool) (FileFacts, error)
	Exec(ctx context.Context, spec ExecSpec) (ExecResult, error)
}

Observer is the two abilities the design asks of the checker for a device (docs/specs/2026-11-11-lab-checkers-bootstrap-devices.md, section 5): read a file and run a command. The node-side implementation reads the files of a container from the node and execs through the runtime; the micro-VM one asks the in-device tool for both.

type Outcome

type Outcome int

Outcome is the verdict of one run of one check.

const (
	// Passed: every part held in this run.
	Passed Outcome = iota + 1
	// NotPassed: at least one part did not hold.
	NotPassed
	// Failed: the check could not be made (the device could not be reached, a command did not start or ran over its time limit,
	// a file was too big to decide). It is published as the state "error".
	Failed
)

func EvalCustom

func EvalCustom(p *labchecks.CustomPart, r ExecResult) (Outcome, []string)

EvalCustom judges the outcome of a command: exit code 0 passes, then the optional output expectations must hold. A command that did not start or ran over its time limit is Failed. A command killed by a signal did not pass.

func EvalDirectory

func EvalDirectory(p *labchecks.DirectoryPart, f *probe.DirectoryFacts, key []byte) (Outcome, []string)

EvalDirectory compares a directory with the expectations of the part. key is the key of the question the facts answer: the names the author expects are hashed with it here, never sent to the device.

func EvalFile

func EvalFile(p *labchecks.FilePart, f FileFacts) (Outcome, []string)

EvalFile compares what a reader saw of a file with the expectations of the part. Every expectation must hold. A file that is too large to decide (content, matches or checksum over the size cap) is Failed, not Passed or NotPassed: the checker does not know.

func EvalKernelParam

func EvalKernelParam(p *labchecks.KernelParamPart, f *probe.KernelParamFacts) (Outcome, []string)

EvalKernelParam judges the value of a sysctl.

func EvalPermission

func EvalPermission(p *labchecks.PermissionPart, f *probe.PermissionFacts) (Outcome, []string)

EvalPermission judges what the kernel said to the user.

func EvalPort

func EvalPort(p *labchecks.PortPart, f *probe.PortFacts) (Outcome, []string)

EvalPort judges the sockets found on a port.

func EvalProcess

func EvalProcess(p *labchecks.ProcessPart, f *probe.ProcessFacts) (Outcome, []string)

EvalProcess judges the process table.

func EvalRequest

func EvalRequest(p *labchecks.RequestPart, f *probe.RequestFacts) (Outcome, []string)

EvalRequest judges the answer of a request made from inside the device. A connection that does not open is a fact about the service (not passed), not an error of the check.

func (Outcome) String

func (o Outcome) String() string

type PodInfo

type PodInfo struct {
	Lab    LabKey
	Device string
	Name   string
	UID    string
	// Ready is the Ready condition of the pod. MicroVM: the pod runs in a micro-VM (it has a RuntimeClass), whose root file system
	// the node cannot see.
	Ready   bool
	MicroVM bool
}

PodInfo is a device pod on this node.

func PodInfoOf

func PodInfoOf(pod *corev1.Pod) (PodInfo, bool)

PodInfoOf reads a (trimmed) pod into what the engine needs.

type Prober

type Prober interface {
	Probe(ctx context.Context, req probe.ObserveRequest) (probe.ObserveResponse, error)
}

Prober is the third ability, of an Observer that can run the built-in observations: it asks the in-device program one question (never an expected value) and gets facts back. An Observer without it cannot judge directory, process, port, kernel_param, request or permission, and a check with one gets the result error.

type Published

type Published struct {
	State         laboratoryv1alpha1.CheckState
	FirstPassedMs int64
	ChangedMs     int64
	Value         string
	Detail        string
}

Published is one entry of LabStatus.checks.

func PublishedFrom

func PublishedFrom(r laboratoryv1alpha1.CheckResult) Published

PublishedFrom reads a result from the status of a lab.

func (Published) Result

Result turns a published entry into the status entry of the check.

type Run

type Run struct {
	Outcome Outcome
	Detail  string
	Value   string
}

Run is the result of one run: the verdict, a short detail for the author and the teacher, and an optional value.

Detail names the part and the kind of expectation that did not hold ("part 2 (file): content_contains not found") and the facts observed that are no secret of the check (an exit code, a mode). It NEVER holds an expected value of the checks document and never the output of a command or the content of a file: the output may hold what the participant has to find on their own, and text of the participant's device must not travel into the status and the stream.

func RunCheck

func RunCheck(ctx context.Context, c *labchecks.Check, obs Observer) Run

RunCheck makes one run of a check: every part in order, all within the check's time limit, judged together. The observations are made one after another, so the parts "hold in the same run" of the checker, not at one instant of the device.

type RunRequest

type RunRequest struct {
	Token int64    `json:"token"`
	IDs   []string `json:"ids,omitempty"`
}

RunRequest is the value of the annotation laboratory.cybericebox.com/run-checks (names.AnnotationRunChecks): a token that grows by one with every request the agent accepts, and the ids to run. No ids means every check that allows a manual run.

func ParseRunRequest

func ParseRunRequest(raw string) (RunRequest, bool)

ParseRunRequest reads the annotation; ok is false for an empty or damaged value (which is ignored, never guessed at).

type Runner

type Runner interface {
	RunProbe(ctx context.Context, pod PodInfo, command, arg string, limit time.Duration) (stdout []byte, exit int, err error)
}

Runner runs one probe subcommand in a device and returns what it printed.

type SocketBackend

type SocketBackend struct{ Runner Runner }

SocketBackend gives access to the devices of this node through the checker socket. Every observation of every device, container or micro-VM, goes through the probe in the device.

func (*SocketBackend) Open

func (b *SocketBackend) Open(_ context.Context, pod PodInfo) (Observer, func(), error)

Open implements Backend.

type SocketRunner

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

SocketRunner is the Runner over the checker socket of the service.

func NewSocketRunner

func NewSocketRunner(path string) *SocketRunner

NewSocketRunner returns a Runner that talks to the unix socket at path.

func (*SocketRunner) RunProbe

func (r *SocketRunner) RunProbe(ctx context.Context, pod PodInfo, command, arg string, limit time.Duration) ([]byte, int, error)

RunProbe implements Runner.

type StatusWriter

type StatusWriter struct {
	Client client.Client
}

StatusWriter writes the results into Lab.status with server-side apply, so that it cannot fight with the lab controller's own status writes (which are plain updates of other fields):

  • one apply carries one entry of status.checks (the list is a map keyed by id), under a field manager of its own for that check, so applying an entry never touches another entry, any other field of the status, or the fields the controller owns;
  • the controller's Status().Update of the whole object does not take over or drop the entries: an update only changes the ownership of fields whose value it changes, and it never changes these;
  • status.checksRunAck is applied under a manager of its own, the same for every node.

The applied object is unstructured, never the typed Lab: a typed object serializes every non-omitempty field (empty structs such as vpn and internet), and an apply would then claim them.

func (*StatusWriter) AckRun

func (w *StatusWriter) AckRun(ctx context.Context, lab LabKey, token int64) error

AckRun applies status.checksRunAck.

func (*StatusWriter) PublishCheck

func (w *StatusWriter) PublishCheck(ctx context.Context, lab LabKey, r laboratoryv1alpha1.CheckResult) error

PublishCheck applies one entry of status.checks.

type Watcher

type Watcher struct {
	Engine *Engine
	// Reader is an uncached reader (the Secret is not in a cache).
	Reader client.Reader
	Log    logr.Logger
	// Retry is the first pause after a failed read of the Secret (doubled up to five minutes). Default 5 s.
	Retry time.Duration
	// contains filtered or unexported fields
}

Watcher feeds an Engine from the informers and fetches the checks Secret of a lab when it is needed.

The Secret is read with one GET, not watched: a watch would bring every lab's checks to every node. A lab's Secret is read when the lab has a pod on this node and checks, and read again when the agent has rewritten it. The agent rewrites it under the claim annotation names.AnnotationLabVariableAdmission, which is on the Lab while the write is going and removed after; so "the claim came and went" is the signal to read again, and while the claim is on, nothing is read.

func (*Watcher) Start

func (w *Watcher) Start(ctx context.Context, c cache.Cache) error

Start registers the event handlers; ctx bounds the reads.

type Writer

type Writer interface {
	PublishCheck(ctx context.Context, lab LabKey, result laboratoryv1alpha1.CheckResult) error
	AckRun(ctx context.Context, lab LabKey, token int64) error
}

Writer publishes results. PublishCheck writes one entry of status.checks (and only that one); AckRun writes status.checksRunAck.

Jump to

Keyboard shortcuts

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