probe

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: 23 Imported by: 0

Documentation

Overview

Package probe is the readiness probe of a device pod. It is a tiny static program, copied by an init container into an emptyDir that the device container mounts read-only, because a device image may carry no shell and no curl. The kubelet runs it as an exec readiness probe inside the container, so it sees the container's own network namespace and file system.

Index

Constants

View Source
const (
	// CommandCheckObserve is the subcommand of the built-in observations.
	CommandCheckObserve = "check-observe"
	// CommandCheckPerm is the child the probe starts for a permission test (see permission): never called by the checker.
	CommandCheckPerm = "check-perm"

	// The observation kinds.
	KindDirectory   = "directory"
	KindProcess     = "process"
	KindPort        = "port"
	KindKernelParam = "kernel_param"
	KindRequest     = "request"
	KindPermission  = "permission"

	// The bounds on what comes back.
	MaxDirHashes    = 32768   // entry names of a directory, as keyed hashes
	DirHashBytes    = 16      // length of one keyed hash
	MinDirKeyBytes  = 16      // the key the checker sends
	MaxProcessScan  = 1 << 20 // entries of the process table looked at
	MaxProcesses    = 2048    // processes returned
	MaxCmdlineBytes = 512     // command line returned per process

	MaxListeners     = 256      // sockets listed for one port
	MaxParamBytes    = 4096     // value of a sysctl
	MaxRequestBody   = 64 << 10 // body of an HTTP answer
	DefaultRequestMs = 10000
	MaxRequestMs     = 600000
)
View Source
const (
	// CommandCheckExec and CommandCheckFile are the two subcommands of the tool.
	CommandCheckExec = "check-exec"
	CommandCheckFile = "check-file"

	// MaxCheckOutput bounds the output of a checked command that comes back (stdout and stderr together).
	MaxCheckOutput = 64 << 10
	// MaxCheckFile bounds the content of a file that comes back.
	MaxCheckFile = 256 << 10
	// MaxIDFile bounds /etc/passwd and /etc/group when names are looked up.
	MaxIDFile = 256 << 10
)
View Source
const (
	ExitUsage = 2
	ExitIO    = 14
	// ExitNoUser is the exit code of resolve-user for a user the device does not know.
	ExitNoUser = 15
)

Exit codes of the console commands.

View Source
const (
	SchemeTCP   = "tcp"
	SchemeHTTP  = "http"
	SchemeHTTPS = "https"

	// InstalledName is the file name of the copy in the shared directory.
	InstalledName = "probe"
)
View Source
const (
	CommandResolveUser = "resolve-user"
)

The in-device side of the console (internal/deviceaccess). The device access service runs these through the container runtime's exec, in the device, with the rights of the console's user; the service itself never touches the file system of a device.

probe resolve-user NAME   answer the numeric ids of a user of the device as one JSON document

A failure is told by the exit code only, never by text the service would have to trust.

Variables

This section is empty.

Functions

func EntryHash added in v1.10.0

func EntryHash(key []byte, name string) []byte

EntryHash is the keyed hash of a directory entry name: HMAC-SHA256 truncated to DirHashBytes. The key is random per question, so the hash tells the device nothing about a name it did not already have, and the checker alone can say which hash is which name.

func Install

func Install(src, dir string) error

Install copies the program src to dir/InstalledName, read-only and executable by everybody, so the device container can run it as any user and cannot change it. The copy is atomic: a rerun of the init container never leaves half a file.

func LocalAddrs

func LocalAddrs() []string

LocalAddrs are the addresses the probe tries: the loopback first, then every global unicast address of the container (an application may listen only on the pod's own address).

func RunCheckCommand added in v1.10.0

func RunCheckCommand(cmd string, args []string) int

RunCheckCommand runs check-exec or check-file with its one JSON argument and returns the process exit code: 0 whenever an answer was written (the answer carries the outcome), 2 for a usage error.

func RunConsoleCommand added in v1.10.0

func RunConsoleCommand(cmd string, args []string) int

RunConsoleCommand runs the console command and returns the process exit code.

func RunPermChild added in v1.10.0

func RunPermChild(path string) int

RunPermChild is the child of a permission test: it already runs as the user, asks the kernel three questions and prints the answer.

Types

type Check

type Check struct {
	// File is a marker the application creates; the check passes once it exists. Several markers are separated like the
	// entries of PATH (filepath.ListSeparator) and must all exist.
	File string
	// Port is a port the application must answer on, with Scheme tcp (a connection is accepted), http or https (an HTTP
	// answer with a status below 500: any answer proves the application serves; 4xx is a page behind a login, not a
	// failure).
	Port   int
	Scheme string
}

Check is what makes a device ready. Every set part must pass; an empty Check is an error, not success.

func (Check) Run

func (c Check) Run(ctx context.Context, addrs func() []string) error

Run checks the marker and the port. addrs lists the addresses of the container to try for the port (see LocalAddrs).

type DirectoryFacts added in v1.10.0

type DirectoryFacts struct {
	Exists    bool     `json:"exists"`
	IsDir     bool     `json:"isDir,omitempty"`
	Mode      uint32   `json:"mode,omitempty"`
	UID       uint32   `json:"uid,omitempty"`
	GID       uint32   `json:"gid,omitempty"`
	User      string   `json:"user,omitempty"`
	Group     string   `json:"group,omitempty"`
	Hashes    [][]byte `json:"hashes,omitempty"`
	Truncated bool     `json:"truncated,omitempty"`
}

DirectoryFacts: Exists is false when the path is missing; IsDir false when it is something else. Hashes are the keyed hashes (EntryHash, with the key of the question) of the names directly in the directory; Truncated says there were more than MaxDirHashes, so the set is not the whole directory. The checker hashes the names it expects with the same key and compares: the names the author expects never reach the device.

type ExecRequest added in v1.10.0

type ExecRequest struct {
	// Argv is the command (the first item is looked up in PATH); empty when Script is set.
	Argv []string `json:"argv,omitempty"`
	// Script is run by Interpreter; it is handed over as a file, not as an argument.
	Script      string `json:"script,omitempty"`
	Interpreter string `json:"interpreter,omitempty"`
	// User is a name from /etc/passwd of the device, or a number (uid or uid:gid).
	User string `json:"user,omitempty"`
	// TimeoutMs kills the command (its process group) when it runs longer.
	TimeoutMs int64 `json:"timeoutMs"`
}

ExecRequest is a custom observation as the tool receives it.

type ExecResponse added in v1.10.0

type ExecResponse struct {
	// Started is false when the command could not be started (no such file, no permission, no such user).
	Started  bool   `json:"started"`
	Exit     int    `json:"exit"`
	Signal   string `json:"signal,omitempty"`
	TimedOut bool   `json:"timedOut,omitempty"`
	// Output is stdout and stderr in the order they were written, cut at MaxCheckOutput.
	Output    []byte `json:"output,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
	// Error says why the command did not start; it never repeats output.
	Error string `json:"error,omitempty"`
}

ExecResponse is the outcome of a custom observation.

type FileRequest added in v1.10.0

type FileRequest struct {
	Path        string `json:"path"`
	WantContent bool   `json:"wantContent,omitempty"`
}

FileRequest is a file observation of a device whose file system the node cannot see.

type FileResponse added in v1.10.0

type FileResponse struct {
	Exists  bool `json:"exists"`
	Regular bool `json:"regular,omitempty"`
	// Type is what the path itself is, links not followed: file, directory, symlink or other.
	Type  string `json:"type,omitempty"`
	Mode  uint32 `json:"mode,omitempty"`
	UID   uint32 `json:"uid,omitempty"`
	GID   uint32 `json:"gid,omitempty"`
	User  string `json:"user,omitempty"`
	Group string `json:"group,omitempty"`
	// Content is the start of the file (at most MaxCheckFile bytes) when it was asked for and the file is regular.
	Content   []byte `json:"content,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
	Error     string `json:"error,omitempty"`
}

FileResponse is what the tool saw. Symbolic links are followed (inside the device, which the participant controls anyway).

type IDNames added in v1.10.0

type IDNames struct {
	Users  map[uint32]string
	Groups map[uint32]string
}

IDNames are the user and group names of a device by number, read from its /etc/passwd and /etc/group.

func ParseIDNames added in v1.10.0

func ParseIDNames(passwd, group []byte) IDNames

ParseIDNames reads the first field and the third field of the lines of passwd and group (the first line for a number wins).

type KernelParamFacts added in v1.10.0

type KernelParamFacts struct {
	Exists bool   `json:"exists"`
	Value  string `json:"value,omitempty"`
}

KernelParamFacts: Exists is false when there is no such sysctl.

type Listener added in v1.10.0

type Listener struct {
	Protocol string   `json:"protocol"`
	Addr     string   `json:"addr"`
	Procs    []string `json:"procs,omitempty"`
	Arg0s    []string `json:"arg0s,omitempty"`
}

Listener is a socket that waits for connections (tcp: LISTEN; udp: bound and not connected) on the asked port. Addr is the local address ("0.0.0.0" and "::" are the wildcards). Procs are the names (Comm) of the processes that hold the socket.

type ObserveRequest added in v1.10.0

type ObserveRequest struct {
	Kind string `json:"kind"`
	// directory, permission
	Path string `json:"path,omitempty"`
	// directory: a random key for the keyed hashes of the entry names (see EntryHash). The names that the author expects are never sent.
	Key []byte `json:"key,omitempty"`
	// port, request
	Port     int    `json:"port,omitempty"`
	Protocol string `json:"protocol,omitempty"` // port: tcp | udp; request: tcp | http | https
	// kernel_param: the sysctl name with dots
	Name string `json:"name,omitempty"`
	// request
	Host      string `json:"host,omitempty"`
	Method    string `json:"method,omitempty"`
	URLPath   string `json:"urlPath,omitempty"`
	TimeoutMs int64  `json:"timeoutMs,omitempty"`
	// permission: a user name of the device, or a number
	User string `json:"user,omitempty"`
}

ObserveRequest is one question. Only the fields of its Kind are used.

type ObserveResponse added in v1.10.0

type ObserveResponse struct {
	Error string `json:"error,omitempty"`

	Directory   *DirectoryFacts   `json:"directory,omitempty"`
	Processes   *ProcessFacts     `json:"processes,omitempty"`
	Port        *PortFacts        `json:"port,omitempty"`
	KernelParam *KernelParamFacts `json:"kernelParam,omitempty"`
	Request     *RequestFacts     `json:"request,omitempty"`
	Permission  *PermissionFacts  `json:"permission,omitempty"`
}

ObserveResponse is the answer: Error is set when the question could not be answered, otherwise exactly the member of the kind.

func Observe added in v1.10.0

func Observe(req ObserveRequest) ObserveResponse

Observe answers one question (the entry of check-observe).

type PermissionFacts added in v1.10.0

type PermissionFacts struct {
	UserFound bool `json:"userFound"`
	Exists    bool `json:"exists"`
	Read      bool `json:"read"`
	Write     bool `json:"write"`
	Execute   bool `json:"execute"`
	// Error is set by the child of the test when the kernel gave an answer that is not a yes or a no.
	Error string `json:"error,omitempty"`
}

PermissionFacts: what the kernel says to the user, asked without opening anything and without changing anything. Exists is false when the path is missing (or cannot be reached by the user); UserFound false when the device has no such user.

type PortFacts added in v1.10.0

type PortFacts struct {
	Listeners []Listener `json:"listeners"`
	Truncated bool       `json:"truncated,omitempty"`
	// OwnersIncomplete: some process could not be looked into, so a socket without an owner may have one.
	OwnersIncomplete bool `json:"ownersIncomplete,omitempty"`
}

PortFacts lists the listeners on the asked port and protocol.

type Process added in v1.10.0

type Process struct {
	PID     int    `json:"pid"`
	Comm    string `json:"comm"`
	Arg0    string `json:"arg0,omitempty"`
	Cmdline string `json:"cmdline,omitempty"`
	Cut     bool   `json:"cut,omitempty"`
	UID     uint32 `json:"uid"`
	User    string `json:"user,omitempty"`
}

Process is one process of the device. Comm is the kernel's name (at most 15 characters); Arg0 the first word of the command line without its directory; Cmdline the command line, words joined by a space, cut at MaxCmdlineBytes (Cut says it was longer).

type ProcessFacts added in v1.10.0

type ProcessFacts struct {
	List       []Process `json:"list"`
	Truncated  bool      `json:"truncated,omitempty"`
	Incomplete int       `json:"incomplete,omitempty"`
}

ProcessFacts is the process table of the device (except the probe itself), at most MaxProcesses entries; Truncated says there were more. Incomplete counts the entries that could not be read (a denied read, a table over MaxProcessScan): they may be what is looked for.

type RequestFacts added in v1.10.0

type RequestFacts struct {
	Connected bool   `json:"connected"`
	Failure   string `json:"failure,omitempty"`
	Status    int    `json:"status,omitempty"`
	Body      []byte `json:"body,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
}

RequestFacts: Connected is false when the connection did not open (Failure says how: refused, timeout, unreachable, resolve, tls or error). For http and https Status and Body are the answer (a redirect is an answer, not followed; the body is cut at MaxRequestBody).

Jump to

Keyboard shortcuts

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