Documentation
¶
Overview ¶
Package agent is the per-node Rune daemon.
On single-node, the agent runs in-process inside `runed`. On multi-node, the same agent code runs as a separate process on every worker node and talks to the control plane over gRPC. The single-node case is the simplest instantiation: the agent shares the control plane's process, store, and OrderedLog instance directly.
The agent owns the node-local data plane: ordered watch consumer, userspace proxy + nftables (RUNE-041), embedded DNS (RUNE-063), network policy enforcement (RUNE-064), ingress controller (RUNE-066). This package, RUNE-032, ships only the lifecycle scaffold; the subsystems plug in as concrete Subsystem implementations in subsequent tickets.
Index ¶
- type Agent
- func (a *Agent) Identity() Identity
- func (a *Agent) Mode() Mode
- func (a *Agent) Outbox() *outbox.Outbox
- func (a *Agent) Ready() <-chan struct{}
- func (a *Agent) ReadyErr() error
- func (a *Agent) Register(s Subsystem) error
- func (a *Agent) Start(ctx context.Context) error
- func (a *Agent) Stop(ctx context.Context) error
- type Config
- type Identity
- type Mode
- type Subsystem
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent is the per-node Rune daemon. It owns the lifecycle of a set of Subsystems, an outbox for buffered events/logs, and the agent's view of identity and mode.
func (*Agent) Outbox ¶
Outbox returns the agent's local outbox. Subsystems use this to queue logs and events that should be flushed to remote sinks (RuneSight, CloudWatch, etc.) in the background. The outbox is in-memory only in RUNE-032; persistence comes later.
func (*Agent) Ready ¶
func (a *Agent) Ready() <-chan struct{}
Ready returns a channel that is closed once every subsystem has reported ready, or once ReadyTimeout has elapsed (check ReadyErr in that case). For agents with no subsystems, Ready closes immediately after Start.
func (*Agent) ReadyErr ¶
ReadyErr returns the error (if any) that prevented full readiness. nil means every subsystem reported ready before ReadyTimeout. Call only after Ready() has closed.
func (*Agent) Register ¶
Register attaches a Subsystem to the agent. It MUST be called before Start. Returns an error after Start has been called.
func (*Agent) Start ¶
Start brings up every registered subsystem in registration order and then waits (up to ReadyTimeout) for all of them to report ready. Returns nil when the agent is fully ready, or an error if any subsystem fails to start; subsystems already started are stopped on error so the agent leaves no orphaned goroutines behind.
Start is non-blocking once it returns: subsystem long-running work runs in goroutines the subsystems own. Call Stop to shut down.
type Config ¶
type Config struct {
// Identity is the persisted node identity. Required.
Identity Identity
// OrderedLog is the seam to control-plane state. On single-node this
// is the in-process orderedlog.BadgerBackend; on multi-node it is a
// thin RPC client over the watch stream (RUNE-028). Required.
OrderedLog orderedlog.OrderedLog
// Mode selects production vs dev behavior. Defaults to ModeProduction.
Mode Mode
// Logger is the structured logger to use. Defaults to the global
// "agent" logger.
Logger log.Logger
// OutboxCapacity caps the in-memory outbox before back-pressure /
// drop. Defaults to 4096.
OutboxCapacity int
// ReadyTimeout caps how long Start blocks waiting for every
// registered subsystem to report ready. Defaults to 30s.
ReadyTimeout time.Duration
}
Config is the dependencies and tunables an Agent needs to run. Fields marked Required must be non-zero / non-nil; New returns an error otherwise.
type Identity ¶
type Identity struct {
NodeID string `json:"node_id"`
Hostname string `json:"hostname"`
Labels map[string]string `json:"labels,omitempty"`
}
Identity is the agent's stable node identity. Persisted on disk so that a process restart does not change the node ID.
func LoadOrCreateIdentity ¶
LoadOrCreateIdentity reads the agent identity from <dir>/node-identity.json, or creates and persists a new one if the file does not exist.
The persisted file ensures NodeID is stable across restarts. We never regenerate NodeID once written; if the file exists but is malformed, LoadOrCreateIdentity returns an error rather than silently overwriting it (operator must intervene).
type Mode ¶
type Mode string
Mode tags the agent's deployment context. Used by subsystems to branch behavior (e.g. dev-mode skips nftables).
const ( // ModeProduction is the normal single-node or multi-node case. ModeProduction Mode = "production" // ModeDev is the laptop / `--dev-mode` escape hatch. Subsystems MUST // honor this: nftables off, DNS resolves .rune to 127.0.0.1, ingress // can run on alternate ports, etc. See RUNE-041 / RUNE-063. ModeDev Mode = "dev" )
type Subsystem ¶
type Subsystem interface {
Name() string
Start(ctx context.Context) error
Ready() <-chan struct{}
Stop(ctx context.Context) error
}
Subsystem is a node-local component the Agent owns: data plane, DNS, policy enforcement, ingress, etc. Each ticket in the networking layer adds one.
Lifecycle contract:
- Name returns a stable identifier for logs and metrics.
- Start MUST return promptly. Long-running work belongs in a goroutine the subsystem owns. Start returning nil means the subsystem accepted ownership; readiness is reported separately via the ready channel.
- Ready returns a channel closed when the subsystem is ready to serve traffic. The agent waits for all Ready channels (up to ReadyTimeout) before reporting itself ready.
- Stop blocks until the subsystem has fully released resources. Subsystems MUST be safe to Stop after a failed Start.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package dataplane implements the per-node Rune data path (RUNE-041): per-VIP TCP/UDP userspace proxies, a kernel-side nftables reconciler (Linux only), an endpoint cache backed by the OrderedLog watch stream, and Prometheus metrics.
|
Package dataplane implements the per-node Rune data path (RUNE-041): per-VIP TCP/UDP userspace proxies, a kernel-side nftables reconciler (Linux only), an endpoint cache backed by the OrderedLog watch stream, and Prometheus metrics. |
|
Package dns implements the per-node embedded DNS server (RUNE-063).
|
Package dns implements the per-node embedded DNS server (RUNE-063). |
|
Package forwarder is the agent's log forwarder subsystem (plan §4.1).
|
Package forwarder is the agent's log forwarder subsystem (plan §4.1). |
|
Package ingressctl reconciles the ingress route table from the service store and resolves upstream targets from the dataplane endpoint cache.
|
Package ingressctl reconciles the ingress route table from the service store and resolves upstream targets from the dataplane endpoint cache. |
|
Package outbox is the agent's per-node buffer for logs and events destined for remote sinks (RuneSight, CloudWatch, Datadog).
|
Package outbox is the agent's per-node buffer for logs and events destined for remote sinks (RuneSight, CloudWatch, Datadog). |
|
Package volumes is the per-node Subsystem that drives the storage driver Attach/Mount/Unmount/Detach lifecycle for Volumes whose BoundNode equals this node's identity.
|
Package volumes is the per-node Subsystem that drives the storage driver Attach/Mount/Unmount/Detach lifecycle for Volumes whose BoundNode equals this node's identity. |