Documentation
¶
Overview ¶
Package kubectl provides helpers for running kubectl commands with the correct KUBECONFIG environment variable set. It centralises the pattern that was previously duplicated across network, x402, model, agent, and cmd/obol packages.
Index ¶
- Constants
- Variables
- func Apply(binary, kubeconfig string, data []byte) error
- func ApplyOutput(binary, kubeconfig string, data []byte) (string, error)
- func ApplyServerSideForceConflicts(binary, kubeconfig string, data []byte, fieldManager string) error
- func EnsureCluster(cfg *config.Config) error
- func FormatClusterDownError(err error, args []string) string
- func MigrateLocalPathStorageClass(cfg *config.Config) (bool, error)
- func Output(binary, kubeconfig string, args ...string) (string, error)
- func ParseForwardedPort(r io.Reader, timeout time.Duration) (int, error)
- func Paths(cfg *config.Config) (binary, kubeconfig string)
- func PipeCommands(binary, kubeconfig string, args1, args2 []string) error
- func PrepareLocalPathStorageClass(cfg *config.Config, u *ui.UI)
- func Run(binary, kubeconfig string, args ...string) error
- func RunSilent(binary, kubeconfig string, args ...string) error
- func SetManagedBy(obj map[string]any)
- type Forward
Constants ¶
const ( ManagedByLabel = "obol.org/managed-by" ManagedByObol = "obol" // FieldManagerObol is the server-side apply field manager for objects obol // applies from its records. FieldManagerObol = "obol" )
ManagedByLabel marks objects obol applies from its host-side records (Agent CRs, CLI-created ServiceOffers, storefront profile, x402 pricing). Groundwork for label-scoped pruning in a declarative `obol stack apply` (plans/2026-10-lean-stack.md §1). Distinct value from the serviceoffer-controller's "serviceoffer-controller", which it uses as a selector for its own children — never reuse that value here.
const LocalPathStorageClass = "local-path"
LocalPathStorageClass is the default StorageClass rendered by the base release (internal/embed/infrastructure/base/templates/local-path.yaml).
Variables ¶
var ErrClusterDown = errors.New("cluster appears to be stopped — run 'obol stack up' to start it")
ErrClusterDown indicates the Kubernetes API server is unreachable, typically because the k3d cluster is stopped.
Functions ¶
func ApplyOutput ¶ added in v0.8.0
ApplyOutput pipes the given data into kubectl apply -f - and returns stdout.
func ApplyServerSideForceConflicts ¶ added in v0.9.0
func ApplyServerSideForceConflicts(binary, kubeconfig string, data []byte, fieldManager string) error
ApplyServerSideForceConflicts pipes the given data into kubectl apply --server-side --force-conflicts -f -. Use it only for narrow compatibility migrations where the caller has already decided which manager must own the restored fields.
func EnsureCluster ¶
EnsureCluster verifies that the Kubernetes API server is reachable using the kubeconfig under cfg.ConfigDir. It checks the kubeconfig file exists, then actively probes the API server (kubectl is the source of truth — file presence alone does not mean ops will succeed). When the probe fails with a "cluster down"-shaped error AND the deployment looks like a k3d stack, it attempts ONE kubeconfig refresh via `k3d kubeconfig write` and retries the probe before giving up. This recovers from the common port-drift case after `k3d cluster stop && k3d cluster start`, where the kubeconfig on disk still points at the previous (now-defunct) API server port.
func FormatClusterDownError ¶ added in v0.8.0
FormatClusterDownError returns a contextual message for a cluster-down error based on the CLI arguments. Returns empty string if err is not ErrClusterDown.
func MigrateLocalPathStorageClass ¶ added in v0.15.0
MigrateLocalPathStorageClass deletes a stale local-path StorageClass so the following base-release helm sync recreates it with the current parameters.
local-path-provisioner >= v0.0.33 rejects our pathPattern unless the class carries allowUnsafePathPattern: "true". StorageClass parameters are immutable, so a helm upgrade cannot patch a class created by an older release: the update is rejected and new PVCs stay Pending forever. Deleting a StorageClass does not touch existing PVs/PVCs (the provisioner only reads the class when provisioning new volumes), and helm's upgrade recreates a release resource that is missing from the cluster (kube.Client.Update creates on NotFound), so the caller MUST run the base release sync right after this.
Returns true when the class was deleted. A missing class (fresh cluster) is not an error.
func Output ¶
Output executes kubectl and returns the captured stdout. Stderr is captured and included in the returned error on failure.
func ParseForwardedPort ¶ added in v0.16.0
ParseForwardedPort reads kubectl port-forward output until it sees "Forwarding from 127.0.0.1:<port> -> <remote>" and returns <port>.
func PipeCommands ¶ added in v0.8.0
PipeCommands pipes the stdout of the first kubectl command into the stdin of the second. Both commands run with the correct KUBECONFIG. This is useful for patterns like "kubectl create --dry-run -o yaml | kubectl replace -f -" which avoid the 262KB annotation limit that kubectl apply imposes.
func PrepareLocalPathStorageClass ¶ added in v0.15.0
PrepareLocalPathStorageClass is the best-effort, user-facing wrapper both `obol stack up` and `obol upgrade` call right before syncing the base release. It never fails the caller: a failure only means a stale class may survive, which the warning tells the operator how to fix by hand.
func Run ¶
Run executes kubectl with the given arguments, inheriting stdout and capturing stderr. The error message includes stderr output on failure.
func RunSilent ¶
RunSilent executes kubectl without inheriting stdout. Stderr is captured and included in the returned error on failure.
func SetManagedBy ¶ added in v0.15.0
SetManagedBy stamps ManagedByLabel=ManagedByObol onto a decoded manifest (map from json/yaml.Unmarshal). A v1 List gets every item stamped. Malformed shapes are left untouched.
Types ¶
type Forward ¶ added in v0.16.0
type Forward struct {
LocalPort int
// contains filtered or unexported fields
}
Forward is a running `kubectl port-forward` bound to an OS-chosen loopback port. Close it when done.
func PortForward ¶ added in v0.16.0
func PortForward(ctx context.Context, binary, kubeconfig, namespace, target string, remotePort int, readyTimeout time.Duration) (*Forward, error)
PortForward starts `kubectl port-forward -n <namespace> <target> :<remotePort>` against the given kubeconfig (always obol's own stack kubeconfig — never the user's ambient KUBECONFIG) and waits up to readyTimeout for kubectl to report the local port. target is e.g. "svc/ethereum-execution".
On failure the error carries kubectl's stderr (e.g. "pod is not running"), so callers can surface it as-is.
func (*Forward) Close ¶ added in v0.16.0
func (f *Forward) Close()
Close stops the port-forward and reaps the process.
func (*Forward) URL ¶ added in v0.16.0
URL returns http://127.0.0.1:<local port>.
Source Files