Documentation
¶
Overview ¶
Package localconfig models Burrow's client-side selector state: the human-edited ~/.burrow/config file that names environment handles and records which one a command targets (ADR-0036). A handle maps a user-chosen name to {context, control-plane namespace, app namespace}; the current selection is either a pinned handle or, by default, whatever kube context kubectl points at ("follow"). This is selector state like the kubeconfig, never agent configuration, so it lives client-side: both `burrow` (the CLI) and `burrow-mcp` consume this package, hence it is a shared top-level package rather than living under cmd/burrow.
This package is foundation only (ADR-0036 slice 1): the config model plus the resolution that decides the active target. Command wiring (`burrow env`, install, MCP) lands in later slices.
Index ¶
Constants ¶
const ( // APIVersion is the schema version stamped into the config header so the format can be // migrated safely across Burrow versions (ADR-0036). APIVersion = "burrow.dev/v1" // Kind identifies the document, mirroring the Kubernetes-style header on ~/.kube/config. Kind = "Config" // DefaultControlPlaneNamespace is where burrowd runs unless a handle says otherwise. The // dimension is carried from day one so a future multi-burrowd-per-cluster setup is a // non-default value, not a breaking change (ADR-0036). DefaultControlPlaneNamespace = "burrow" )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
APIVersion string `yaml:"apiVersion"`
Kind string `yaml:"kind"`
Current string `yaml:"current,omitempty"`
Environments []Environment `yaml:"environments,omitempty"`
}
Config is the on-disk selector state. APIVersion/Kind form the migratable header; Current names the pinned handle, or is empty to follow the current kube context (the default); Environments is the set of named handles.
func Load ¶
Load reads and parses the config from Path. A missing file is not an error: it returns a zero/empty Config (first run). Use Exists to detect the first-run case. An empty file is tolerated as first-run; a present apiVersion/kind is validated so future migrations are safe.
func (*Config) Add ¶
func (c *Config) Add(env Environment) error
Add registers a new handle. The name must be non-empty and not already in use.
func (*Config) Lookup ¶
func (c *Config) Lookup(name string) (Environment, bool)
Lookup returns the handle with the given name, and whether it was found.
func (*Config) Remove ¶
Remove deletes the named handle. Removing the pinned handle reverts the selection to follow mode. It errors if the name is not registered.
type Environment ¶
type Environment struct {
Name string `yaml:"name"`
Context string `yaml:"context"`
ControlPlaneNamespace string `yaml:"controlPlaneNamespace,omitempty"`
AppNamespace string `yaml:"appNamespace,omitempty"`
Env string `yaml:"env,omitempty"`
}
Environment is a user-named handle resolving to a kube context and the namespaces the environment lives in (ADR-0036). ControlPlaneNamespace defaults to DefaultControlPlaneNamespace when empty; AppNamespace empty means callers fall back to the burrowd default app namespace.
Env is the burrowd-registered environment NAME a command sends with each operation, which burrowd maps to the operation's namespace and per-environment guardrails. Empty means the cluster's default app namespace and the global guardrails (the cluster-per-environment case, where the whole cluster is the environment); a namespace-per-environment handle carries the same name it was registered with via `burrow env add`. It is deliberately distinct from AppNamespace, which is for display only: burrowd resolves a registered NAME, not a raw namespace.
type Mode ¶
type Mode string
Mode is how the active target was selected: pinned to a named handle, or following the current kube context.
type Resolved ¶
type Resolved struct {
Name string
Context string
Namespace string
ControlPlaneNamespace string
Env string
Mode Mode
}
Resolved is the concrete target a command will act against, derived from the config and the kubeconfig. Namespace is the app namespace (for display); empty means the caller falls back to the burrowd default app namespace. Env is the burrowd-registered environment NAME to send with the operation (empty means the cluster's default namespace and global guardrails); it is what burrowd resolves, not a raw namespace. In follow mode Name (and Env) are empty when the current context matches no registered handle (an "unregistered" current context).
func Resolve ¶
Resolve decides which environment a command targets (ADR-0036).
When a handle is pinned (cfg.Current set), it resolves to that handle, erroring clearly if the pinned name is not registered. Otherwise it follows the kubeconfig's current context: the target is that context, its namespace (so kubens moves Burrow too; empty when the context sets none, leaving the burrowd default to apply), and the default control-plane namespace. If the current context matches a registered handle by context name, that handle's Name and Env (the burrowd env name to send) are surfaced; otherwise both are empty.
Source Files