connect

package
v0.13.0-rc.1 Latest Latest
Warning

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

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

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

View Source
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"
	// DefaultBuildNamespace is the dedicated namespace `install` provisions for the in-cluster build
	// (ADR-0053, issue #278): each build runs as a Job here, isolated from both the app namespace (so
	// build steps cannot reach a running app's Secrets) and the control-plane namespace (so they
	// cannot reach burrowd's credentials or database). install grants burrowd a namespaced Role here;
	// burrowd never creates the namespace itself (least privilege).
	DefaultBuildNamespace = "burrow-builds"

	// DefaultRegistryService is the in-cluster Service name of the optional lightweight registry
	// `burrow cluster registry install` deploys (Zot, ADR-0053 §5). It is the zero-config default
	// push target for the in-cluster build — a registry that happens to be local; external
	// registries remain fully supported.
	DefaultRegistryService = "burrow-registry"
	// DefaultRegistryPort is the port the in-cluster registry serves on (Zot's default).
	DefaultRegistryPort = 5000
)

Defaults for a standard `burrow install`.

View Source
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

func Client(ctx context.Context, o Options) (*client.Client, error)

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

func FailureReason(err error) string

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

func RESTConfig(path, kubeContext string) (*rest.Config, error)

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 RegistryEndpoint added in v0.13.0

func RegistryEndpoint(namespace string) string

RegistryEndpoint is the in-cluster registry's INTERNAL push endpoint host:port for the given control-plane namespace (ADR-0053 §5, ADR-0054): the cluster-DNS name of the registry Service a build pushes to in-cluster over plain HTTP. It is a fully-qualified cluster-DNS name so a build pod in any namespace resolves it. Nodes do NOT pull by this reference — the resulting deploy references the registry's PUBLIC ingress host instead, which the kubelet pulls over TLS (ADR-0054 §5).

func TargetContextName added in v0.7.0

func TargetContextName(kubeconfig, override string) (string, error)

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

func Contexts(kubeconfig string) ([]Context, error)

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.

func (KubeconfigTransport) Connect added in v0.10.0

Connect resolves the token from the install Secret and returns a proxy-routed client.

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

Jump to

Keyboard shortcuts

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