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
- func Exists() (bool, error)
- func Path() (string, error)
- type Config
- func (c *Config) Add(env Environment) error
- func (c *Config) Lookup(name string) (Environment, bool)
- func (c *Config) LookupByContext(context string) (Environment, bool)
- func (c *Config) Remove(name string) error
- func (c *Config) Rename(oldName, newName string) error
- func (c *Config) Save() error
- func (c *Config) SetAgentCredential(name, kubeconfig, context string) bool
- type Environment
- type Mode
- type Resolved
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) LookupByContext ¶ added in v0.8.0
func (c *Config) LookupByContext(context string) (Environment, bool)
LookupByContext returns the handle registered for a kube context name, and whether one matched. It backs follow-mode resolution, where the current context is matched to a handle, and the MCP server's per-context resolution of the scoped agent kubeconfig (ADR-0038).
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.
func (*Config) Rename ¶
Rename changes a handle's name, carrying the pin if the renamed handle was pinned. The new name must be non-empty and unused; the old name must be registered.
func (*Config) Save ¶
Save writes the config to Path, creating ~/.burrow (0700) as needed and writing the file 0600. The apiVersion/kind header is always stamped.
func (*Config) SetAgentCredential ¶ added in v0.8.0
SetAgentCredential records the scoped agent kubeconfig path and its context on the named handle, backing the ADR-0038 phase 3 backfill (`upgrade` and a re-run `install` join provisioning the scoped credential onto a handle registered before it existed). It reports whether a handle by that name was found; the caller Saves.
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"`
// AgentKubeconfig is the path to the self-contained, burrowd-only kubeconfig `burrow install`
// mints for the scoped agent credential (ADR-0038), written under ~/.burrow/ (never
// ~/.kube/config). AgentContext names the single context inside it. Both are empty for handles
// created before the scoped credential existed or joined out of band; consumers fall back to
// the ambient kubeconfig then. The operate path (`burrow-mcp` and the CLI) reads them to reach
// burrowd with the scoped credential; `install` (fresh mint or join), `env list --discover`, and `upgrade`
// write them.
AgentKubeconfig string `yaml:"agentKubeconfig,omitempty"`
AgentContext string `yaml:"agentContext,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
AgentKubeconfig string
AgentContext string
}
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). AgentKubeconfig/AgentContext carry the resolved handle's scoped, burrowd-only credential (ADR-0038) so the operate path can default to it; both are empty when the handle records none.
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