Documentation
¶
Overview ¶
Package connect reaches the in-cluster Burrow control plane from a developer's machine using their ambient kubeconfig and the Kubernetes API server's service proxy — no port-forward, no ingress (ADR-0014). It reads the API token from the install Secret, so a developer with kubectl access configures nothing else.
It is Apache-2.0 (the client surface): it imports client-go to talk to the API server but not the controlplane packages — it reaches Burrow over HTTP, like any client.
Index ¶
- Constants
- func Client(ctx context.Context, o Options) (*client.Client, error)
- func FailureReason(err error) string
- func RESTConfig(path, kubeContext string) (*rest.Config, error)
- func TargetContextName(kubeconfig, override string) (string, error)
- type Context
- type KubeconfigTransport
- type Options
- type UnreachableError
Constants ¶
const ( DefaultNamespace = "burrow" DefaultService = "burrowd" DefaultPort = 8080 DefaultTokenSecret = "burrowd-api-token" DefaultTokenKey = "token" // DefaultAddonNamespace is where `install` provisions Burrow's curated backing services // (logs, metrics) and their collectors — separate from both the control-plane namespace // (which holds credentials) and the app namespace (user workloads), so add-ons don't // clutter apps and stay out of the credential blast radius (ADR-0025). DefaultAddonNamespace = "burrow-addons" // DefaultAppNamespace is where `install` deploys apps by default: a dedicated namespace // rather than the cluster's shared `default`, so burrowd's namespace-scoped Secrets grant // (ADR-0029) stays isolated to Burrow's own app workloads. An operator may still choose // `--app-namespace default` explicitly. DefaultAppNamespace = "burrow-apps" )
Defaults for a standard `burrow install`.
const ProbeTimeout = 5 * time.Second
ProbeTimeout caps a best-effort control-plane probe so a command (e.g. `burrow version`) returns promptly even when the targeted cluster is unreachable. FailureReason names this duration in its timeout message, so the timeout and the message it produces stay in step.
Variables ¶
This section is empty.
Functions ¶
func Client ¶
Client returns a control-plane API client that reaches burrowd through the API-server service proxy, authenticated by the kubeconfig, with the API token read from the install Secret.
func FailureReason ¶ added in v0.7.0
FailureReason reduces a connectivity error to a concise reason, dropping the dialed URL that the Kubernetes client prepends. It names the common failures explicitly (timeout, DNS, refused) and otherwise strips the `Get "<url>": ` prefix so the URL noise stays out of the message. It is the one classifier shared by `burrow version` and connect.Client so the two render the same failures the same way.
func RESTConfig ¶
RESTConfig prefers in-cluster config (when burrow runs inside Kubernetes) and otherwise loads the kubeconfig at path, or the ambient KUBECONFIG / ~/.kube/config when path is empty. When kubeContext is non-empty it overrides the current context, selecting that context's cluster (ADR-0035); empty keeps the kubeconfig's current context (no regression). It is exported so the CLI can build a clientset from the same config logic.
func TargetContextName ¶ added in v0.7.0
TargetContextName returns the name of the kubeconfig context an operation will target: the override when non-empty, otherwise the kubeconfig's current context. It reads the kubeconfig the same way Contexts does (honoring an explicit path, otherwise the ambient KUBECONFIG / ~/.kube/config) and needs no control-plane connection, so a command can name the context it is about to probe even before reaching the cluster.
Types ¶
type Context ¶ added in v0.7.0
type Context struct {
Name string // the kubeconfig context name
Cluster string // the cluster the context points at
Current bool // whether this is the kubeconfig's current context
}
Context is a kubeconfig context: a cluster, each running its own burrowd, so the contexts are the environments a developer or agent can target (ADR-0035 phase 1). The CLI's global --context flag and the MCP per-call context argument both name one of these.
func Contexts ¶ added in v0.7.0
Contexts loads the kubeconfig (honoring an explicit path, otherwise the ambient KUBECONFIG / ~/.kube/config) and returns its contexts sorted by name, marking the current one. It needs no control-plane connection: the kubeconfig itself is the registry of environments (ADR-0035 phase 1), so both `burrow context list` and the MCP burrow_environments tool read it through this one helper rather than duplicating the logic.
type KubeconfigTransport ¶ added in v0.10.0
type KubeconfigTransport struct {
Options Options
}
KubeconfigTransport reaches the in-cluster control plane through the Kubernetes API-server service proxy, authenticated by the developer's kubeconfig, with the burrowd API token read from the install Secret (ADR-0014). Its Connect wraps Client, so requests carry the token on the wire in X-Burrow-Token (ADR-0015). It is the default open-source transport (ADR-0045), shared by the CLI and the MCP server so both reach burrowd over one seam. It lives with the kubeconfig logic it wraps and is importable by both binaries and a private module.
type Options ¶
type Options struct {
Kubeconfig string // explicit kubeconfig path; empty = in-cluster, else ambient
// Context selects which kubeconfig context (cluster) to target. Empty = the current
// context (today's behavior). Each context's cluster runs its own burrowd, so this is
// how a developer points an operation at a specific environment's control plane (ADR-0035).
Context string
Namespace string
Service string
Port int
TokenSecret string
TokenKey string
// ClientVersion is this client's release version, forwarded as X-Burrow-Client-Version so
// burrowd can make version skew legible (ADR-0039). Empty omits the header.
ClientVersion string
}
Options configures how to find the control plane. The zero value uses the defaults and the ambient kubeconfig.
type UnreachableError ¶ added in v0.11.0
type UnreachableError struct {
Context string // the kube context the connection targeted
Reason string // the concise FailureReason (no dialed URL)
}
UnreachableError classifies a connect failure as the targeted cluster's control plane being unreachable — a dial/DNS/timeout/refused failure — as distinct from a NotFound (burrowd not installed) or another API error the server actually returned. It carries the concise, URL-free rendering connectError already produced, so its Error() message is byte-for-byte what the flat error used to be (existing renderings and tests are unaffected). It exists so a caller can detect the unreachable case with errors.As and enrich it — the MCP server, for one, names the other registered environments so a human can redirect (ADR-0047 §4) — without matching on message text.
func (*UnreachableError) Error ¶ added in v0.11.0
func (e *UnreachableError) Error() string
Source Files