registration

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Jul 18, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package registration implements node self-registration.

Index

Constants

View Source
const DefaultMaxRetryDuration = 5 * time.Minute

DefaultMaxRetryDuration is the default maximum retry duration.

View Source
const DefaultMetadataTimeout = 2 * time.Second

DefaultMetadataTimeout is the default timeout for metadata service requests.

View Source
const DefaultMetadataTokenPath = "/plexd/bootstrap-token"

DefaultMetadataTokenPath is the default metadata key path for the bootstrap token.

View Source
const DefaultTokenEnv = "PLEXD_BOOTSTRAP_TOKEN"

DefaultTokenEnv is the default environment variable name for the bootstrap token.

View Source
const DefaultTokenFile = "/etc/plexd/bootstrap-token"

DefaultTokenFile is the default path to the bootstrap token file.

Variables

View Source
var ErrNotRegistered = errors.New("registration: node is not registered")

ErrNotRegistered indicates that no valid identity files exist in data_dir.

Functions

func SaveIdentity

func SaveIdentity(dataDir string, id *NodeIdentity) error

SaveIdentity persists the node identity atomically to dataDir.

Types

type Config

type Config struct {
	// DataDir is the path to the data directory (required).
	DataDir string `yaml:"data_dir"`

	// TokenFile is the path to the bootstrap token file.
	// Default: /etc/plexd/bootstrap-token
	TokenFile string `yaml:"token_file"`

	// TokenEnv is the environment variable name for the bootstrap token.
	// Default: PLEXD_BOOTSTRAP_TOKEN
	TokenEnv string `yaml:"token_env"`

	// TokenValue is a direct token value override.
	TokenValue string `yaml:"token_value"`

	// UseMetadata enables cloud metadata service for registration.
	// Default: false
	UseMetadata bool `yaml:"use_metadata"`

	// MetadataTokenPath is the metadata key path used to retrieve the
	// bootstrap token from an instance metadata service (e.g. IMDS).
	// Default: /plexd/bootstrap-token
	MetadataTokenPath string `yaml:"metadata_token_path"`

	// MetadataTimeout is the maximum time to wait for a metadata service
	// response.
	// Default: 2s
	MetadataTimeout time.Duration `yaml:"metadata_timeout"`

	// Hostname overrides the system hostname.
	// Default: empty (uses os.Hostname())
	Hostname string `yaml:"hostname"`

	// Metadata holds optional key-value pairs for the registration request.
	Metadata map[string]string `yaml:"metadata"`

	// MaxRetryDuration is the maximum duration to retry registration.
	// Default: 5m
	MaxRetryDuration time.Duration `yaml:"max_retry_duration"`
}

Config holds the configuration for the agent registration process. Config is passed as a constructor argument — no file I/O in this package.

func (*Config) ApplyDefaults

func (c *Config) ApplyDefaults()

ApplyDefaults sets default values for zero-valued fields.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks that required fields are set.

type IMDSProvider

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

IMDSProvider reads a bootstrap token from a cloud instance metadata service. It supports both IMDSv2 (session-based) and IMDSv1 (open GET) with automatic fallback: a PUT is attempted first to acquire a session token; if that fails the subsequent GET proceeds without the session header.

func NewIMDSProvider

func NewIMDSProvider(cfg *Config, baseURL string) *IMDSProvider

NewIMDSProvider creates an IMDSProvider that reads the bootstrap token from baseURL + cfg.MetadataTokenPath. The HTTP client timeout is set to cfg.MetadataTimeout.

func (*IMDSProvider) ReadToken

func (p *IMDSProvider) ReadToken(ctx context.Context) (string, error)

ReadToken fetches the bootstrap token from the metadata service. It first attempts IMDSv2 session token acquisition; if that fails it falls back to an unauthenticated IMDSv1 GET.

type Keypair

type Keypair struct {
	PrivateKey []byte // 32 bytes, never logged
	PublicKey  []byte // 32 bytes
}

Keypair holds a Curve25519 keypair for WireGuard.

func GenerateKeypair

func GenerateKeypair() (*Keypair, error)

GenerateKeypair generates a new Curve25519 keypair for WireGuard mesh encryption.

func (*Keypair) EncodePublicKey

func (k *Keypair) EncodePublicKey() string

EncodePublicKey returns the standard base64 encoding of the public key.

type MetadataProvider

type MetadataProvider interface {
	ReadToken(ctx context.Context) (string, error)
}

MetadataProvider reads a bootstrap token from a cloud metadata service.

type NodeIdentity

type NodeIdentity struct {
	NodeID           string `json:"node_id"`
	MeshIP           string `json:"mesh_ip"`
	SigningPublicKey string `json:"signing_public_key"`
	PrivateKey       []byte `json:"-"` // never serialized to JSON
	NodeSecretKey    string `json:"-"` // never serialized to JSON
}

NodeIdentity holds the registration identity of a node.

func LoadIdentity

func LoadIdentity(dataDir string) (*NodeIdentity, error)

LoadIdentity reads a previously saved node identity from dataDir.

type Registrar

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

Registrar orchestrates node registration with the control plane.

func NewRegistrar

func NewRegistrar(client *api.ControlPlane, cfg Config, logger *slog.Logger) *Registrar

NewRegistrar creates a new Registrar with the given client, config, and logger.

func (*Registrar) IsRegistered

func (r *Registrar) IsRegistered() bool

IsRegistered returns true if a valid identity exists on disk.

func (*Registrar) Register

func (r *Registrar) Register(ctx context.Context) (*NodeIdentity, error)

Register orchestrates the full registration flow. If a valid identity already exists on disk, it is returned without contacting the control plane.

func (*Registrar) SetCapabilities

func (r *Registrar) SetCapabilities(caps *api.CapabilitiesPayload)

SetCapabilities sets the optional capabilities payload for registration.

func (*Registrar) SetClock

func (r *Registrar) SetClock(c api.Clock)

SetClock sets a custom clock for testing.

func (*Registrar) SetMetadataProvider

func (r *Registrar) SetMetadataProvider(mp MetadataProvider)

SetMetadataProvider sets an optional metadata provider for token resolution.

type TokenResolver

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

TokenResolver resolves the bootstrap token from multiple sources.

func NewTokenResolver

func NewTokenResolver(cfg *Config, metadata MetadataProvider) *TokenResolver

NewTokenResolver creates a new TokenResolver.

func (*TokenResolver) Resolve

func (r *TokenResolver) Resolve(ctx context.Context) (*TokenResult, error)

Resolve locates a bootstrap token by checking sources in priority order: direct value, file, environment variable, metadata service.

type TokenResult

type TokenResult struct {
	Value    string // the token value
	FilePath string // non-empty if the token was read from a file (for cleanup)
}

TokenResult holds the resolved token and its source metadata.

Jump to

Keyboard shortcuts

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