Documentation
¶
Index ¶
- Constants
- func CacheOptions(node string) (map[client.Object]cache.ByObject, error)
- func LeaseName(node string) string
- func ManagerForCheck(id string) string
- func ParseChecksSecret(s *corev1.Secret) ([]labchecks.Check, error)
- type Backend
- type CheckRef
- type Config
- type Engine
- func (e *Engine) Execute(ctx context.Context, job Job)
- func (e *Engine) Flush(ctx context.Context)
- func (e *Engine) HasPods(key LabKey) bool
- func (e *Engine) RemoveLab(key LabKey)
- func (e *Engine) RemovePod(lab LabKey, device, podUID string)
- func (e *Engine) Run(ctx context.Context, beat func())
- func (e *Engine) SetDefinitions(key LabKey, uid string, checks []labchecks.Check)
- func (e *Engine) SetLab(info LabInfo)
- func (e *Engine) SetPod(p PodInfo)
- func (e *Engine) Tick(now time.Time) []Job
- type ExecResult
- type ExecSpec
- type FileFacts
- type FileProber
- type Job
- type Keepalive
- type LabInfo
- type LabKey
- type ObserveError
- type Observer
- type Outcome
- func EvalCustom(p *labchecks.CustomPart, r ExecResult) (Outcome, []string)
- func EvalDirectory(p *labchecks.DirectoryPart, f *probe.DirectoryFacts, key []byte) (Outcome, []string)
- func EvalFile(p *labchecks.FilePart, f FileFacts) (Outcome, []string)
- func EvalKernelParam(p *labchecks.KernelParamPart, f *probe.KernelParamFacts) (Outcome, []string)
- func EvalPermission(p *labchecks.PermissionPart, f *probe.PermissionFacts) (Outcome, []string)
- func EvalPort(p *labchecks.PortPart, f *probe.PortFacts) (Outcome, []string)
- func EvalProcess(p *labchecks.ProcessPart, f *probe.ProcessFacts) (Outcome, []string)
- func EvalRequest(p *labchecks.RequestPart, f *probe.RequestFacts) (Outcome, []string)
- type PodInfo
- type Prober
- type Published
- type Run
- type RunRequest
- type Runner
- type SocketBackend
- type SocketRunner
- type StatusWriter
- type Watcher
- type Writer
Constants ¶
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.
const AckManager = "lab-checker-ack"
AckManager is the field manager of status.checksRunAck.
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 ¶
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 ManagerForCheck ¶
ManagerForCheck is the field manager of one check: fixed length and characters whatever the id is.
Types ¶
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 (*Engine) Execute ¶
Execute makes one run and folds the result in. It is safe to call from several goroutines.
func (*Engine) Flush ¶
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) Run ¶
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 ¶
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.
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 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.
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 ObserveError ¶
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 ¶
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 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.
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.
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 ¶
func (p Published) Result(id string) laboratoryv1alpha1.CheckResult
Result turns a published entry into the status entry of the check.
type Run ¶
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.
type RunRequest ¶
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.
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.
type StatusWriter ¶
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) 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.
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.