How castai/cluster-controller works
Project type and purpose
• This is a Go-based Kubernetes cluster controller (CLI) for CAST AI.
• It acts as an operator-style controller that pulls “work” from the CAST AI API, reconciles desired state (e.g., charts, node operations) against the Kubernetes API, and reports back status and metrics.
File structure
• Top-level “cmd/…” defines three main binaries:
• controller – the core control loop that watches for CAST AI events and applies changes via Kubernetes.
• monitor – a separate process for cluster monitoring tasks.
• testserver – a fake CAST AI API for e2e tests.
• “internal/…” packages implement the core logic:
• internal/actions – handlers for specific event types (chart upsert, drain node, CSR approval, etc.).
• internal/castai – client for the external CAST AI REST API.
• internal/helm – Helm chart loader and client abstraction.
• internal/config, internal/k8sversion, internal/metrics, internal/monitor, internal/waitext – support, utilities, and metrics registration.
• “health/” exposes a simple healthz endpoint.
• “loadtest/” contains load-testing scenarios.
• “e2e/” holds end-to-end tests and an embedded client and fake server.
• “hack/” scripts for local Kind cluster setup, remote cluster deploys, and load-test deployments.
• CI configs, Dockerfile, Makefile, Go module files at root.
Key README insights
• Describes the CLI install and run modes:
• On an existing cluster via helm.
• Locally or in Kind for e2e.
• Points at the helm-charts repo as the source of Kubernetes manifests.
• References load tests and e2e flows that leverage the testserver and loadtest packages.
• CLI entrypoint (cmd/controller)
• CAST AI API (external service)
• Kubernetes API Server (cluster)
• Helm Chart Repository (castai-helm-charts)
• internal modules grouped by function (actions, castai client, helm client, config/health/metrics)
• testserver (e2e fake API)
• loadtest harness
• Controller polls (or streams) CAST AI API → events
• events → internal/actions handlers
• handlers → Kubernetes API (create/update resources via client-go & Helm)
• handlers → metrics registry → Prometheus
• healthz endpoint → Kubernetes probe
• testserver ←→ e2e client (during CI)
• loadtest scenarios → controller API endpoints
c. Architectural patterns & principles:
• Controller pattern (informers, handlers, reconciliation loops)
• Modular design: “internal/…” packages separate concerns (API client, helm, actions, retries).
• Dependency injection via interfaces and mocks (see internal/*/mock folders).
• Retry/backoff logic in internal/waitext.
d. Technologies & frameworks:
• Go modules, client-go for Kubernetes, Helm Go SDK
• Cobra for CLI (cmd/*)
• Prometheus metrics (internal/metrics)
• Kind & Helm for local testing (hack/kind/*)
• GitHub Actions for CI, Docker for container builds
Elements
• Blue for external services (CAST AI API, Helm repo)
• Green for in-cluster components (Kubernetes API, Controller)
• Yellow for test harness (testserver, loadtest)