host

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 4, 2026 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Overview

Package host runs the host role: node agent and coordinator in one process on a Linux host without Kubernetes.

Index

Constants

View Source
const (
	ExportRollBytes = 64 << 20
	ExportRollAge   = time.Hour
)

Export file rolling limits for the air-gap profile.

View Source
const (
	SpoolDirName = "spool"
	TSDBDirName  = "tsdb"
	MetaFileName = "meta.db"
)

State directory layout.

View Source
const (
	DefaultCollectInterval = time.Minute
	DefaultTick            = 10 * time.Second
	DefaultDiskInterval    = time.Minute
)

Defaults.

View Source
const DeenrollDrainTimeout = 30 * time.Second

DeenrollDrainTimeout bounds how long offline de-enrollment waits for spooled records to be committed first.

Variables

View Source
var DefaultJournalDirs = []string{"/var/log/journal", "/run/log/journal"}

DefaultJournalDirs are read when host.journalDir is empty.

View Source
var ErrKubernetesNode = errors.New("host mode refuses to run on a Kubernetes node; install the Helm chart instead (docs/install-kubernetes.md)")

ErrKubernetesNode is returned when host mode is started on a Kubernetes node.

View Source
var ErrNoInvestigator = errors.New("host: no investigation service is configured on this agent")

ErrNoInvestigator is returned when this agent was started without investigation tools.

View Source
var ErrRunning = errors.New("the agent is running and holds the state directory lock; use its admin socket")

ErrRunning is returned by offline operations while an agent holds the state directory lock.

View Source
var Version = "dev"

Version is the agent version reported to the control plane; main sets it from its ldflags.

Functions

func Deenroll

func Deenroll(ctx context.Context, cfg *config.Config, reason string, d Deps) (err error)

Deenroll connects a stopped host agent with its stored credential, de-enrolls it, and clears the credential (PRD A6).

func Export

func Export(cfg *config.Config, fromSeq uint64, w io.Writer, d Deps) error

Export writes the spooled records of a stopped host agent to w (PRD A9).

func Run

func Run(ctx context.Context, cfg *config.Config, log *slog.Logger) error

Run starts the host role and blocks until ctx ends or the writer must stop.

Types

type BundleHealth

type BundleHealth struct {
	Version     string            `json:"version,omitempty"`
	Unsupported map[string]string `json:"unsupported,omitempty"`
	Error       string            `json:"error,omitempty"`
}

BundleHealth reports the active rule bundle.

type Clock

type Clock interface {
	Now() time.Time
	After(d time.Duration) <-chan time.Time
}

Clock is the time source; After fires once the clock has passed now plus d.

type Deps

type Deps struct {
	Facts hostfacts.Options
	// FSRoot is the root filesystem for kubelet detection and node_exporter.
	FSRoot            string
	MetricsCollectors []string
	OpenJournal       func(journal.Options) (JournalReader, error)
	// Roots overrides cfg.Trust.
	Roots        *bundle.Roots
	Clock        Clock
	Tunnel       tunnel.Options
	Logger       *slog.Logger
	Investigator Investigator
	// CollectInterval is the host state collection period.
	CollectInterval time.Duration
	Tick            time.Duration
	// Ticks replaces the internal tick timer.
	Ticks          <-chan time.Time
	OnCycle        func(time.Time)
	HealthInterval time.Duration
	BackoffBase    time.Duration
	BackoffMax     time.Duration
}

Deps injects host sources and timing; zero values select the production defaults.

type Freshness

type Freshness struct {
	State   time.Time `json:"state,omitzero"`
	Metrics time.Time `json:"metrics,omitzero"`
	Journal time.Time `json:"journal,omitzero"`
}

Freshness is the time of the last successful collection per source.

type Health

type Health struct {
	Role              string             `json:"role"`
	Agent             protocol.AgentInfo `json:"agent"`
	TargetID          string             `json:"target_id"`
	WriterID          string             `json:"writer_id"`
	Incarnation       uint64             `json:"incarnation"`
	Epoch             string             `json:"epoch,omitempty"`
	Head              uint64             `json:"head"`
	Capabilities      []string           `json:"capabilities"`
	Freshness         Freshness          `json:"freshness"`
	Spool             SpoolHealth        `json:"spool"`
	Disk              disk.Report        `json:"disk"`
	TSDB              *TSDBHealth        `json:"tsdb,omitempty"`
	Metrics           *MetricsHealth     `json:"metrics,omitempty"`
	Bundle            BundleHealth       `json:"bundle"`
	Rules             []RuleHealth       `json:"rules"`
	UnavailableScopes map[string]string  `json:"unavailable_scopes"`
	ScrapeTargets     []ScrapeHealth     `json:"scrape_targets,omitempty"`
	RejectedEndpoints map[string]string  `json:"rejected_endpoints,omitempty"`
	Logs              LogsHealth         `json:"logs"`
	EvidenceLimited   []string           `json:"evidence_limited_rules"`
	Identity          machineState       `json:"identity"`
	AirGap            bool               `json:"airgap"`
	Errors            map[string]string  `json:"errors,omitempty"`
}

Health is the agent.health payload (PRD 8.1 host fields).

type Host

type Host struct {
	// contains filtered or unexported fields
}

Host is one host agent.

func New

func New(cfg *config.Config, d Deps) (*Host, error)

New validates the configuration and applies dependency defaults; nothing is opened until Run.

func (*Host) Commit

func (h *Host) Commit(_ context.Context, r admin.CommitReceipt) error

Commit implements admin.Backend: apply an air-gap commit receipt.

func (*Host) Deenroll

func (h *Host) Deenroll(ctx context.Context, reason string) error

Deenroll implements admin.Backend: revoke the credential over the active session, then stop writing.

func (*Host) Export

func (h *Host) Export(_ context.Context, fromSeq uint64, w io.Writer) error

Export implements admin.Backend; in the air-gap profile exported records are marked transmitted first.

func (*Host) Investigate

func (h *Host) Investigate(ctx context.Context, req admin.InvestigateRequest) (any, error)

Investigate implements admin.Backend (PRD A9 local investigation).

func (*Host) Run

func (h *Host) Run(ctx context.Context) (err error)

Run opens the state directory and runs every component until ctx ends.

func (*Host) Status

func (h *Host) Status(context.Context) (any, error)

Status implements admin.Backend.

type Investigator

type Investigator interface {
	Tools() []client.Tool
	Call(ctx context.Context, name string, args json.RawMessage) (any, error)
}

Investigator serves investigation tools over the tunnel and the admin socket.

type JournalReader

type JournalReader interface {
	Refresh() error
	Next() (journal.Entry, bool)
	SaveCursor() error
	FileErrors() map[string]error
	Close() error
}

JournalReader is the subset of *journal.Reader the host uses.

type LogsHealth

type LogsHealth struct {
	Files          int               `json:"files"`
	Streams        int               `json:"streams"`
	Lines          uint64            `json:"lines"`
	Gaps           uint64            `json:"gaps"`
	Journal        bool              `json:"journal"`
	JournalEntries uint64            `json:"journal_entries"`
	JournalErrors  map[string]string `json:"journal_file_errors,omitempty"`
}

LogsHealth reports log inputs.

type MetricsHealth

type MetricsHealth struct {
	Series           int      `json:"series"`
	DroppedSeries    int      `json:"dropped_series"`
	DroppedFamilies  []string `json:"dropped_families,omitempty"`
	FailedCollectors []string `json:"failed_collectors,omitempty"`
	AppendErrors     int      `json:"append_errors"`
}

MetricsHealth reports the last node metrics gather.

type RuleHealth

type RuleHealth struct {
	ID      string    `json:"id"`
	Version int       `json:"version"`
	Class   string    `json:"class"`
	State   string    `json:"state"`
	Reason  string    `json:"reason,omitempty"`
	Pending int       `json:"pending"`
	Firing  int       `json:"firing"`
	Last    time.Time `json:"last_eval,omitzero"`
}

RuleHealth is one rule state (PRD R9).

type ScrapeHealth

type ScrapeHealth struct {
	URL       string    `json:"url"`
	Health    string    `json:"health"`
	Reason    string    `json:"reason,omitempty"`
	LastError string    `json:"last_error,omitempty"`
	Last      time.Time `json:"last_scrape,omitzero"`
	Series    int       `json:"series"`
}

ScrapeHealth is one local metrics endpoint.

type SessionStatus

type SessionStatus struct {
	Connected      bool            `json:"connected"`
	SessionID      string          `json:"session_id,omitempty"`
	Registered     bool            `json:"registered"`
	Committed      uint64          `json:"committed"`
	BacklogRecords int             `json:"backlog_records"`
	BacklogBytes   int64           `json:"backlog_bytes"`
	LastError      string          `json:"last_error,omitempty"`
	LastErrorCode  string          `json:"last_error_code,omitempty"`
	Halted         string          `json:"halted,omitempty"`
	Compat         protocol.Compat `json:"compat"`
	Exported       uint64          `json:"exported_through,omitempty"`
}

SessionStatus reports the writer session.

type SpoolHealth

type SpoolHealth struct {
	Bytes                  int64     `json:"bytes"`
	Capacity               int64     `json:"capacity"`
	Records                int       `json:"records"`
	InFlightBytes          int64     `json:"in_flight_bytes"`
	Oldest                 time.Time `json:"oldest,omitzero"`
	ProjectedWindowSeconds float64   `json:"projected_window_seconds"`
	RebaselineRequired     bool      `json:"rebaseline_required"`
}

SpoolHealth reports spool use and the projected outage window.

type Status

type Status struct {
	Health
	Session SessionStatus `json:"session"`
}

Status is the admin status document: health plus the session.

type TSDBHealth

type TSDBHealth struct {
	Series           uint64  `json:"series"`
	Bytes            int64   `json:"bytes"`
	RetentionSeconds float64 `json:"retention_seconds"`
	MaxBytes         int64   `json:"max_bytes"`
}

TSDBHealth reports the local TSDB.

Jump to

Keyboard shortcuts

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