config

Documentation

Overview

Package config loads and validates cluster.yaml against the published JSON Schema (draft 2020-12). Validation is pure and offline: it is the M3 foundation that every orchestration slice builds on, and backs `pandion validate`.

Index

• Constants
• func Validate(data []byte) error
• type Cluster
  • func Load(path string) (*Cluster, error)
  • func (c *Cluster) Effective(n Node) Effective
• type Effective
• type L2Overlay
• type Lifecycle
• type Node
• type NodeCommon
• type Provider
• type Security
• type Sync
• type Toolchain

Constants

const (
	DefaultL2Subnet = "192.168.66.0/24"
	DefaultL2VNI    = 100
)

L2 overlay defaults.

Functions

func Validate

func Validate(data []byte) error

Validate checks raw YAML bytes against the schema without unmarshalling into typed structs. Returns nil if valid.

Types

type Cluster

type Cluster struct {
	APIVersion string     `yaml:"apiVersion"`
	Name       string     `yaml:"name"`
	Provider   Provider   `yaml:"provider"`
	Defaults   NodeCommon `yaml:"defaults"`
	Nodes      []Node     `yaml:"nodes"`
	Lifecycle  Lifecycle  `yaml:"lifecycle"`
}

Cluster is the typed view of cluster.yaml (a subset of the schema — the fields the orchestrator consumes; the schema is the full source of truth for validity).

func Load

func Load(path string) (*Cluster, error)

Load reads, validates, and unmarshals cluster.yaml into a typed Cluster.

func (*Cluster) Effective

func (c *Cluster) Effective(n Node) Effective

Effective resolves a node's effective settings against the cluster defaults.

type Effective

type Effective struct {
	Size  string
	Image string
	// Packages are the node's EXTRA apt packages (declared libraries/tools). They
	// are added to the built-in toolchain unless NoDefaultToolchain is set.
	Packages           []string
	NoDefaultToolchain bool
	// Setup are shell commands run on the node (as root) in the build window,
	// after packages and before the workspace build — for non-apt software.
	Setup       []string
	Region      string
	RunUser     string   // security.run_as; empty means "use the default"
	TTLRaw      string   // ttl string ("60m" | "false" | ""); "" means "use the default"
	EgressAllow []string // union of node + security + defaults egress allowlists
	// Security defaults are ON (secure by default); a cluster.yaml `security:`
	// false explicitly opts out.
	BlockMetadata bool // block the cloud metadata endpoint (S-F)
	AuditLog      bool // install auditd baseline logging (S-F)
	// EncryptVolumes defaults OFF (opt-in) — LUKS makes the volume unrecoverable
	// after reboot, so it's only enabled when explicitly requested.
	EncryptVolumes bool
	// Engine is "native" (default) or "docker"; ContainerImage is the image for
	// engine=docker (default "ubuntu:24.04").
	Engine         string
	ContainerImage string
	// L2, if set, requests an encrypted Layer-2 overlay (security.overlay: l2).
	// nil means the default L3-only WireGuard overlay.
	L2 *L2Overlay
}

Effective is a node's settings after merging cluster defaults with its own overrides (node wins). It's what the orchestrator should consume.

type L2Overlay

type L2Overlay struct {
	Profile string // "safe" (default) | "lab"
	Subnet  string // default 192.168.66.0/24
	VNI     int    // default 100
}

L2Overlay is the parsed `security.overlay: l2` config — an encrypted Layer-2 (VXLAN-over-WireGuard) segment. Profile "safe" is a spoof-resistant hardened LAN; "lab" is a deliberately attackable cyber-range (Phase 2).

type Lifecycle

type Lifecycle struct {
	DestroyOnExit   *bool `yaml:"destroy_on_exit"`
	ConfirmTeardown *bool `yaml:"confirm_teardown"`
	KeepOnFailure   *bool `yaml:"keep_on_failure"`
}

Lifecycle mirrors the session/teardown defaults.

type Node

type Node struct {
	NodeCommon      `yaml:",inline"`
	Name            string   `yaml:"name"`
	Role            string   `yaml:"role"`
	Run             string   `yaml:"run"`
	IPCPorts        []string `yaml:"ipc_ports"`
	PrivilegedPorts []string `yaml:"privileged_ports"`
	NeedsCaps       []string `yaml:"needs_caps"`
	EgressAllow     []string `yaml:"egress_allow"`
}

Node is one host in the topology.

type NodeCommon

type NodeCommon struct {
	Target         string     `yaml:"target"`
	Engine         string     `yaml:"engine"`
	Size           string     `yaml:"size"`
	Image          string     `yaml:"image"`
	ContainerImage string     `yaml:"container_image"` // for engine=docker
	TTL            string     `yaml:"ttl"`
	Toolchain      *Toolchain `yaml:"toolchain"`
	Sync           *Sync      `yaml:"sync"`
	Sec            *Security  `yaml:"security"`
	// Setup is a list of shell commands run on the node (as root) in the
	// egress-open build window — for software apt can't install: pip/npm/cargo,
	// a vendor repo, a binary fetched by curl, etc. Defaults' setup runs first,
	// then the node's own (additive).
	Setup []string `yaml:"setup"`
}

NodeCommon holds fields valid at both defaults and per-node level.

type Provider

type Provider struct {
	Name       string `yaml:"name"`
	Credential string `yaml:"credential"`
	Region     string `yaml:"region"`
}

Provider selects and configures the cloud backend.

type Security

type Security struct {
	Overlay               any      `yaml:"overlay"`
	EgressAllow           []string `yaml:"egress_allow"`
	OpenEgressDuringBuild *bool    `yaml:"open_egress_during_build"`
	RunAs                 string   `yaml:"run_as"`
	EncryptVolumes        *bool    `yaml:"encrypt_volumes"`
	BlockMetadataService  *bool    `yaml:"block_metadata_service"`
	AuditLog              *bool    `yaml:"audit_log"`
}

Security holds the per-node hardening overrides.

type Sync

type Sync struct {
	Mode       string `yaml:"mode"`
	Path       string `yaml:"path"`
	RemotePath string `yaml:"remote_path"`
	Build      string `yaml:"build"`
}

Sync configures workspace synchronization.

type Toolchain

type Toolchain struct {
	Packages  []string `yaml:"packages"`
	NoDefault bool     `yaml:"no_default"`
}

Toolchain is the extra apt packages (libraries/tools) installed on a node. By default these are ADDED to Pandion's built-in C++ toolchain; set NoDefault to install ONLY this list (a minimal node).