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
- func EntryHash(key []byte, name string) []byte
- func Install(src, dir string) error
- func LocalAddrs() []string
- func RunCheckCommand(cmd string, args []string) int
- func RunConsoleCommand(cmd string, args []string) int
- func RunPermChild(path string) int
- type Check
- type DirectoryFacts
- type ExecRequest
- type ExecResponse
- type FileRequest
- type FileResponse
- type IDNames
- type KernelParamFacts
- type Listener
- type ObserveRequest
- type ObserveResponse
- type PermissionFacts
- type PortFacts
- type Process
- type ProcessFacts
- type RequestFacts
Constants ¶
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 )
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 )
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.
const ( SchemeTCP = "tcp" SchemeHTTP = "http" SchemeHTTPS = "https" // InstalledName is the file name of the copy in the shared directory. InstalledName = "probe" )
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
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 ¶
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
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
RunConsoleCommand runs the console command and returns the process exit code.
func RunPermChild ¶ added in v1.10.0
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.
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
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
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
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).