Saltar al contenido principal

Kubernetes adapter

AlphaSwarm wraps every cluster-side operation in a pluggable :class:alphaswarm.kubernetes.KubernetesAdapter. The abstraction makes the rpi_kubernetes attach optional: AlphaSwarm works fully standalone with NoneAdapter, attaches to the rpi management API with RpiClusterAdapter, talks to a Kubernetes API directly with InClusterAdapter, or treats the local Docker Compose stack as the cluster surface with LocalComposeAdapter.

Architecture​

get_kubernetes_adapter() returns the active adapter based on:

  1. Explicit settings.kubernetes_adapter (none / rpi_cluster / in_cluster / local_compose / aws_eks / gcp_gke / azure_aks).
  2. Auto-promote when unset: cluster_mgmt_url set → rpi_cluster; else default_cloud_provider ∈ azure → aws_eks / gcp_gke / azure_aks respectively.
  3. Default: none.

AwsEksAdapter, GcpGkeAdapter, and AzureAksAdapter (alphaswarm/kubernetes/adapters/) are thin cloud-specific subclasses of InClusterAdapter — same capability surface, different adapter_kind for topology/labeling.

Failures during a call surface as :class:KubernetesAdapterUnavailable (routes return 503) or :class:KubernetesAdapterError (routes return 502). Adapters opt out of unsupported methods by raising :class:KubernetesAdapterUnavailable.

Adapter capabilities​

See alphaswarm_internal/agents/agnostic/alphaswarm/rules/kubernetes-adapter.md for the per-method matrix (as of 2026-07-19, alphaswarm/.cursor/rules/ only carries a pointer to this SSoT repo). Today every adapter implements is_available(); RpiClusterAdapter covers the full Kafka / Flink / AlphaVantage / scale_deployment surface; InClusterAdapter covers scale_deployment / pod_logs / apply_manifest; LocalComposeAdapter covers scale_deployment / pod_logs.

The /cluster REST surface is the primary user — /cluster-mgmt is kept as a backwards-compat alias.

Test patterns​

tests/kubernetes/test_adapter.py covers:

  • The metaclass registers every concrete adapter under "k8s_adapter" in the AlphaSwarm registry.
  • NoneAdapter.is_available() is False; every op raises.
  • RpiClusterAdapter forwards to the wrapped client and translates ClusterMgmtError → KubernetesAdapterError.
  • InClusterAdapter reports unavailable when kubernetes isn't installed (CI default).
  • register_adapter(...) / reset_kubernetes_adapter() give tests clean fixtures.

Adding capabilities​

When you need a new cluster op (say list_namespaces):

  1. Add an abstract method (default: raise :class:KubernetesAdapterUnavailable) on the ABC in alphaswarm/kubernetes/protocol.py.
  2. Implement it in each adapter that can support it.
  3. Add a route in alphaswarm/api/routes/cluster_mgmt.py that calls the adapter.
  4. Adapters that can't service the op leave the default; routes catch KubernetesAdapterUnavailable and translate to 503.

Migrating finops_tasks​

The FinOps audit (alphaswarm/tasks/finops_tasks.py) currently uses the kubernetes SDK directly because it needs list APIs (list_pod_for_all_namespaces, etc.) that the adapter doesn't yet expose. Adding those list methods to the adapter ABC + the in-cluster implementation is the migration target — until then, the direct path is grandfathered by the alphaswarm_internal/agents/agnostic/alphaswarm/rules/kubernetes-adapter.md rule.