Documentation
¶
Overview ¶
Package agent is the client side of the agent-hub contract defined in proto/regulus/agent/v1. It reports the machine (system information, heartbeat, metrics) to a hub and executes the commands the hub sends, such as applying an update.
The same code runs in two places:
- inside the hub, as the built-in agent, over the in-process transport of package inproc (see Run in agent.go);
- on a remote server, as `regulus agent`, which connects outbound to the hub over gRPC with TLS 1.3 and a client certificate (remote.go: Enroll exchanges a single-use token for credentials, Credentials.Dial opens the connection).
Reading order: agent.go (Run and Options), collector.go and sysinfo.go (what is measured), update.go (applying an update), remote.go (enrollment and the remote connection). The certificates are issued by package pki through the hub, and the hub side of the protocol lives in package hub.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotEnrolled = errors.New("the agent is not enrolled")
ErrNotEnrolled is returned by LoadCredentials when the agent has no credentials yet.
Functions ¶
Types ¶
type Collector ¶
type Collector interface {
Collect(ctx context.Context) (*agentv1.MetricsReport, error)
}
Collector gathers the metrics sent to the hub.
type Credentials ¶
type Credentials struct {
AgentID string
Key *ecdsa.PrivateKey
CertDER []byte
CADER []byte
}
Credentials identify an enrolled agent to the hub and tell it which hub to trust.
func Enroll ¶
func Enroll(ctx context.Context, hubAddr, fingerprint, token, version, dir string) (*Credentials, error)
Enroll registers the agent with the hub at hubAddr ("host:port") using a token from the dashboard, and saves the credentials in dir. fingerprint is the fingerprint of the hub's CA, which the agent checks before it sends the token: without it, anyone who can intercept the connection could take it.
func LoadCredentials ¶
func LoadCredentials(dir string) (*Credentials, error)
LoadCredentials reads the credentials saved in dir by Enroll.
func (*Credentials) Dial ¶
func (c *Credentials) Dial(hubAddr string) (*grpc.ClientConn, error)
Dial opens the connection to the hub at hubAddr with the credentials. The connection is made lazily and re-made by gRPC when it drops.
type LinuxCollector ¶
type LinuxCollector struct {
// contains filtered or unexported fields
}
LinuxCollector reads CPU, memory, disk, network and uptime metrics from /proc and statfs. CPU usage is computed between two consecutive calls, so the first report covers the time since the collector was created; when that is too short to mean anything (the first report usually follows at once), it is the average since boot instead.
func NewLinuxCollector ¶
func NewLinuxCollector() *LinuxCollector
NewLinuxCollector returns a collector that reads /proc.
func (*LinuxCollector) Collect ¶
func (c *LinuxCollector) Collect(context.Context) (*agentv1.MetricsReport, error)
Collect gathers a report. A source that cannot be read leaves its part of the report empty; it fails only when neither the CPU nor the memory can be read (for example on a system without /proc).
type Options ¶
type Options struct {
// Version is the agent release version sent in Hello.
Version string
// ID is the agent id. Leave it empty to let the hub assign one; the
// assigned id is reused when the agent reconnects.
ID string
// Collector gathers metrics. Defaults to the Linux collector (CPU, memory,
// disks, network, uptime), or to one that reports only the time and the
// uptime where /proc is not available.
Collector Collector
// Log defaults to slog.Default().
Log *slog.Logger
// UpdateDir is the agent's data directory when this agent may update itself:
// the downloaded release and the request for the installer go there. Empty
// (the built-in agent, or an agent without the installer unit) refuses the
// ApplyUpdate command.
UpdateDir string
// Verifier checks the signature of an update before the installer is asked;
// the installer checks it again as root.
Verifier update.Verifier
// MinBackoff and MaxBackoff bound the wait between reconnection attempts
// (defaults 1s and 30s).
MinBackoff, MaxBackoff time.Duration
}
Options configure Run.
type RejectedError ¶
type RejectedError struct {
Reason agentv1.Reject_Reason
Message string
}
RejectedError is returned by Run when the hub refuses the agent for good: it is revoked or unknown. Retrying would not help, so Run does not. A refusal because of versions is different: updating the hub or the agent fixes it, so Run keeps trying (see versionRejection).
func (*RejectedError) Error ¶
func (e *RejectedError) Error() string
Source Files