Operator CLI for Galactic

[privateip]

Summary

galactic-cli is a standalone operator-facing CLI tool for inspecting, debugging,
and managing galactic-router instances running in a Kubernetes cluster. It provides
a human-readable interface to the BGP control plane state maintained by galactic-router,
surfacing GoBGP session state, RIB contents, VRF-to-route-target mappings, and CRD
health — without requiring kubectl exec into router pods.

The CLI reads from the Kubernetes API (Cosmos BGP CRDs, Node/Secret resources) and
queries the galactic-router gRPC health endpoint. For RIB and peer inspection, it
relies on CRD status fields populated by the reconciler's RuntimeStatus feedback
loop. Future phases may add a dedicated gRPC admin service on galactic-router for
deeper introspection (full GoBGP RIB dumps, per-VRF route target index, EVPN path
details).

Problem statement

Operators troubleshooting galactic-router today face the following gaps:

Gap	Current workaround	Friction
Check BGP peer session state across nodes	kubectl get bgppeer -A -o wide + reading status conditions	Scattered across namespaces, no aggregation
Inspect GoBGP RIB / EVPN paths	kubectl exec into galactic-router pod, no built-in dump command	Requires pod access, no structured output
Verify VRF-to-route-target mapping	Read CRD YAML manually, cross-reference with ip rule on node	No single source of truth
Validate SRv6 SID encoding / interface naming	Manual base62↔hex conversion	Error-prone, no validation helper
Audit CRD health across the fleet	kubectl get per resource type	No unified health view
Diagnose reconciliation failures	Read pod logs, correlate with CRD status conditions	No structured error summary

Goals

Phase 1 — Read-only inspection (MVP)

• galactic-cli status — Cluster-wide health summary: galactic-router pod status,
  BGPRouter readiness, peer establishment count, advertisement acceptance rate.
• galactic-cli peers — List all BGPPeer resources with session state, last
  established time, and router reference, filterable by namespace/node.
• galactic-cli advertisements — List all BGPAdvertisement resources with
  acceptance status, advertised prefix count, and VPC/VPCAttachment identifiers.
• galactic-cli vrfs — List all BGPVRFInstance resources with route distinguisher,
  import/export route targets, and kernel table ID derivation.
• galactic-cli describe <resource> <name> — Detailed view of any BGP CRD with
  status conditions, observed generation, and related resources.
• galactic-cli sid decode <sid> — Decode an SRv6 USID, showing locator prefix,
  function ID, and argument fields per RFC 8986.
• galactic-cli sid encode <locator> <func-id> — Encode locator + function ID into
  a /128 USID string.
• galactic-cli intf decode <name> — Decode a kernel interface name
  (e.g., G09vpc03attV) into VPC hex, VPCAttachment hex, and suffix role.
• galactic-cli config validate <file> — Validate a CNI JSON config or galactic-router
  DaemonSet manifest against known schema constraints.

Phase 2 — Write operations

• galactic-cli apply -f <file> — Apply BGP CRD manifests (BGPRouter, BGPPeer,
  BGPAdvertisement, BGPPolicy, BGPVRFInstance) with pre-flight validation.
• galactic-cli delete <resource> <name> — Delete BGP CRDs with dependency
  checking (e.g., refuse to delete BGPRouter with active peers).
• galactic-cli gc run — Trigger an immediate garbage-collection pass for
  orphaned BGP CRDs (bypasses the configured interval).

Phase 3 — Deep introspection (requires gRPC admin service on galactic-router)

• galagic-cli rib dump — Full GoBGP RIB dump for a given router, filterable by
  AFI/SAFI and peer.
• galactic-cli neighbors — Per-peer BGP FSM state, uptime, message counters,
  and capability negotiation.
• galactic-cli policy trace <prefix> — Simulate policy evaluation for a given
  prefix against import/export policies on a router.

Non-goals

• Not a replacement for kubectl. The CLI is a convenience layer for galactic-specific
  resources and domain knowledge (SRv6 SIDs, interface names, EVPN paths). General
  Kubernetes operations remain the domain of kubectl.
• Not a data-plane tool. The CLI does not manipulate kernel state (VRFs, routes,
  sysctls, netlink). That is the responsibility of galactic-cni and galactic-router.
• Not a multi-cluster orchestrator. The CLI operates against a single cluster's
  Kubernetes API. Cross-cluster correlation is out of scope.
• Not a galactic-cni management tool. CNI plugin lifecycle, NAD management, and
  pod attachment are handled by the companion operator and Multus. The CLI may display
  CNI-related CRD state but does not create or delete CNI resources.
• Not a BGP protocol implementation. The CLI does not speak BGP; it inspects the
  state of galactic-router's embedded BGP server via Kubernetes CRDs and (future) gRPC.
• Not a fabric role tool. The fabric runtime (FRR) is a Phase 2 stub. CLI commands
  scoped to fabric-mode routers are deferred until FRR integration is complete.
• Not a containerlab-specific tool. While the CLI is useful for containerlab
  debugging, it is cluster-agnostic and targets production Kubernetes environments.

Design principles

Principle	Rationale
Read-heavy, write-light	Operators inspect 10× more than they mutate; Phase 1 is read-only
CRD-first	All state derives from Kubernetes CRDs; no side channels
Domain-aware output	Decode SIDs, interface names, and route targets by default
kubectl-composable	Output is both human-readable (table) and machine-parseable (JSON/YAML)
kubeconfig-native	Uses standard Kubernetes auth ($KUBECONFIG, in-cluster config)
No daemon, no daemonset	Pure CLI binary, invoked on-demand

Target users

Role	Primary use case
Platform engineer	Day-2 operations: peer flaps, advertisement failures, CRD drift
Network engineer	SRv6 SID validation, route target verification, policy debugging
Developer	Local containerlab debugging, interface name decoding, config validation

Technical notes

• Language: Go, sharing the internal/model and internal/plumbing/intf packages
  with the rest of the galactic repo for SID/interface encoding logic.
• Authentication: Standard Kubernetes client-go auth (kubeconfig, service account).
• Output format: Table (default), JSON (-o json), YAML (-o yaml).
• Binary: galactic-cli, separate from galactic-cni and galactic-router. May
  be co-located in the same container image for kubectl debug exec scenarios.
• Cosmos dependency: Reads go.miloapis.com/cosmos/api/bgp/v1alpha1 types directly.