agent

Documentation

Overview

Package agent implements the faros agent that connects edges to the hub.

Index

• func AgentConfigPath(edgeName string) (string, error)
• func AgentKubeconfigPath(edgeName string) (string, error)
• func AgentKubeconfigSecretName(edgeName string) string
• func DeleteAgentKubeconfig(edgeName string) error
• func IsInCluster() bool
• func LoadAgentKubeconfig(edgeName string) (string, error)
• func LoadKubeconfigFromSecret(edgeName string) (string, error)
• func SaveAgentConfig(edgeName, hubURL, token string) error
• func SaveAgentKubeconfig(edgeName, kubeconfigB64 string) error
• func SaveKubeconfigToSecret(edgeName, kubeconfigData string) error
• func ValidateAgentKubeconfig(kubeconfigPath string, insecureSkipTLS bool) error
• type Agent
  • func New(opts *Options) (*Agent, error)
  • func (a *Agent) Run(ctx context.Context) error
• type AgentConfig
  • func LoadAgentConfig(edgeName string) (*AgentConfig, error)
• type AgentType
• type Options
  • func NewOptions() *Options

Functions

func AgentConfigPath

func AgentConfigPath(edgeName string) (string, error)

AgentConfigPath returns the path for the per-edge agent config file. Default location: ~/.faros/agent-<edgeName>.json

func AgentKubeconfigPath

func AgentKubeconfigPath(edgeName string) (string, error)

AgentKubeconfigPath returns the path for the per-edge agent kubeconfig file. Default location: ~/.faros/agent-<edgeName>.kubeconfig

func AgentKubeconfigSecretName

func AgentKubeconfigSecretName(edgeName string) string

AgentKubeconfigSecretName returns the name of the Secret used to persist the hub kubeconfig for the given edge when running in-cluster.

func DeleteAgentKubeconfig

func DeleteAgentKubeconfig(edgeName string) error

DeleteAgentKubeconfig removes a previously saved agent kubeconfig from disk.

func IsInCluster

func IsInCluster() bool

IsInCluster returns true when the process is running inside a Kubernetes Pod.

func LoadAgentKubeconfig

func LoadAgentKubeconfig(edgeName string) (string, error)

LoadAgentKubeconfig reads a previously saved agent kubeconfig from disk. Returns an empty string without error if the file does not exist yet.

func LoadKubeconfigFromSecret

func LoadKubeconfigFromSecret(edgeName string) (string, error)

LoadKubeconfigFromSecret reads the hub kubeconfig from the in-cluster Secret. Returns ("", nil) when the Secret does not exist yet (first boot before token exchange).

func SaveAgentConfig

func SaveAgentConfig(edgeName, hubURL, token string) error

SaveAgentConfig persists the durable agent token to disk so the agent can reconnect without the bootstrap join token after the first successful auth.

func SaveAgentKubeconfig

func SaveAgentKubeconfig(edgeName, kubeconfigB64 string) error

SaveAgentKubeconfig decodes the base64-encoded kubeconfig returned by the hub (via X-Faros-Agent-Kubeconfig header) and persists it to disk so the agent can reconnect without the bootstrap join token after the first successful auth.

func SaveKubeconfigToSecret

func SaveKubeconfigToSecret(edgeName, kubeconfigData string) error

SaveKubeconfigToSecret writes the hub kubeconfig to the in-cluster Secret so that it survives a pod restart.

func ValidateAgentKubeconfig

func ValidateAgentKubeconfig(kubeconfigPath string, insecureSkipTLS bool) error

ValidateAgentKubeconfig checks whether the saved kubeconfig still has valid credentials by attempting a lightweight API call. Returns an error only if authentication definitively fails (401 Unauthorized — token revoked, e.g. after Edge recreation). All other errors (403 Forbidden, timeouts, network errors) return nil because they don't prove the token is invalid — the hub may be temporarily unreachable or the RBAC may not permit the probe call. When insecureSkipTLS is true, TLS certificate verification is disabled.

Types

type Agent

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

Agent is the faros agent that connects an edge to the hub.

func New

func New(opts *Options) (*Agent, error)

New creates a new agent.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context) error

Run starts the agent and blocks until the context is cancelled.

type AgentConfig

type AgentConfig struct {
	HubURL string `json:"hubURL"`
	Token  string `json:"token"`
}

AgentConfig holds the locally persisted agent configuration. It is written to disk after the first successful join-token authentication so that the agent can reconnect on restart without needing the bootstrap join token again.

func LoadAgentConfig

func LoadAgentConfig(edgeName string) (*AgentConfig, error)

LoadAgentConfig reads a previously saved agent config from disk. Returns nil without error if the config file does not exist yet.

type AgentType

type AgentType string

AgentType discriminates whether the agent connects a Kubernetes cluster or a bare-metal / systemd server to the hub.

const (
	// AgentTypeKubernetes connects a Kubernetes cluster (registers an Edge with spec.type=kubernetes).
	AgentTypeKubernetes AgentType = "kubernetes"
	// AgentTypeServer connects a bare-metal / systemd host via SSH
	// (registers an Edge with spec.type=server).
	AgentTypeServer AgentType = "server"
)

type Options

type Options struct {
	HubURL        string
	HubKubeconfig string
	HubContext    string
	TunnelURL     string // Separate URL for reverse tunnel (defaults to hubConfig.Host)
	Token         string
	EdgeName      string
	Kubeconfig    string
	Context       string
	Labels        map[string]string
	// Type controls whether the agent registers as a Kubernetes edge or a
	// Server edge. Defaults to AgentTypeKubernetes.
	Type AgentType
	// InsecureSkipTLSVerify disables TLS certificate verification for the hub
	// connection. Should only be used in development/testing; never in production.
	InsecureSkipTLSVerify bool
	// SSHProxyPort is the local port of the SSH daemon the agent proxies to.
	// Defaults to 22; override in tests to avoid conflicts with the host sshd.
	SSHProxyPort int
	// SSHUser is the SSH username to authenticate as on server-type edges.
	// Defaults to the current user if not set.
	SSHUser string
	// SSHPassword is the SSH password for password-based authentication.
	// Prefer SSHPrivateKeyPath for better security.
	SSHPassword string
	// SSHPrivateKeyPath is the path to an SSH private key file for key-based auth.
	SSHPrivateKeyPath string
	// Cluster is the kcp logical cluster path (e.g., "root:faros:user-default").
	// If not set, it's extracted from the SA token (for kubeconfig-based auth)
	// or defaults to "default" (for static token auth).
	Cluster string
	// UsingSavedKubeconfig is set to true when the agent loaded a saved
	// kubeconfig from a previous join-token registration. When true, edge
	// registration is skipped (the edge was already registered).
	UsingSavedKubeconfig bool
	// DebugAddr, if non-empty, is the bind address for the agent's debug
	// HTTP server. It exposes /healthz and the standard /debug/pprof/*
	// endpoints. Use "127.0.0.1:6060" for local-only access; bind to a
	// non-loopback address only when port-forwarding is not an option.
	DebugAddr string
}

Options holds configuration for the agent.

func NewOptions

func NewOptions() *Options

NewOptions returns default agent options.