# castai/k8s-agent architecture

> Architecture diagram of the GitHub repository castai/k8s-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/castai/k8s-agent
- Repository: https://github.com/castai/k8s-agent

## Overview

CAST AI Kubernetes Agent connects a cluster to CAST AI for automation and cost optimization. The principal workflow starts with agent configuration and provider/cluster registration, then watches Kubernetes resources, normalizes events into deltas, and uploads them to CAST AI. Separate capabilities include provider-specific cluster discovery, leader election, monitoring, diagnostic dumping, health and metrics endpoints, and remote log export. Several subsystem links are not visible in the sampled excerpts; those are omitted or marked unverified rather than inferred from names alone.

Main entry points: [`cmd/agent/run.go`](https://github.com/castai/k8s-agent/blob/main/cmd/agent/run.go) (Agent runtime), [`internal/services/controller/controller.go`](https://github.com/castai/k8s-agent/blob/main/internal/services/controller/controller.go) (Resource controller), [`cmd/root.go`](https://github.com/castai/k8s-agent/blob/main/cmd/root.go) (Command routing), [`internal/services/controller/delta`](https://github.com/castai/k8s-agent/tree/main/internal/services/controller/delta) (Delta batching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Agent startup"]
  node_entry["Agent entry<br/>[main.go]"]
  node_commands["Command routing<br/>[root.go]"]
  node_agent["Agent runtime<br/>[run.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_cluster["Cluster integration"]
  node_provider["Provider adapters"]
  node_discovery["Cloud discovery<br/>[discovery.go]"]
  node_registration["Cluster registration<br/>[castai.go]"]
  node_leader["Leader election<br/>[leaderelection.go]"]
  node_controller["Resource controller<br/>[controller.go]"]
  node_informers["Resource informers<br/>[controller.go]"]
  node_handlers["Event handlers<br/>[handler.go]"]
  node_crds["Agent resource types"]
end

subgraph group_telemetry["CAST AI telemetry"]
  node_delta["Delta batching"]
  node_castai["CAST AI API client<br/>[castai.go]"]
  node_logexport["Remote log export<br/>[exporter.go]"]
end

subgraph group_operations["Operations"]
  node_monitor["Monitor mode<br/>[run.go]"]
  node_dump["Diagnostic dump<br/>[run.go]"]
  node_healthmetrics["Health and metrics<br/>[service.go]"]
end

node_operator(("Cluster operator"))
node_platform(("CAST AI platform"))
node_kubernetes(("Kubernetes API"))

node_operator -->|"starts"| node_entry
node_entry -->|"executes"| node_commands
node_commands -->|"routes to"| node_agent
node_commands -->|"routes to"| node_monitor
node_commands -->|"routes to"| node_dump
node_agent -->|"loads"| node_config
node_agent -.->|"selects provider"| node_provider
node_agent -->|"registers cluster"| node_registration
node_agent -->|"starts optionally"| node_leader
node_agent -->|"starts"| node_controller
node_provider -.->|"discovers cloud"| node_discovery
node_agent -.->|"uses for identity"| node_discovery
node_controller -->|"watches resources"| node_kubernetes
node_controller -->|"starts"| node_informers
node_controller -.->|"dispatches events"| node_handlers
node_handlers -->|"queues changes"| node_delta
node_controller -->|"watches custom resources"| node_crds
node_controller -->|"batches changes"| node_delta
node_delta -.->|"uploads deltas"| node_castai
node_registration -->|"registers cluster"| node_platform
node_castai -->|"sends API requests"| node_platform
node_logexport -->|"sends log events"| node_castai
node_agent -->|"serves endpoints"| node_healthmetrics

click node_entry "https://github.com/castai/k8s-agent/blob/main/main.go"
click node_commands "https://github.com/castai/k8s-agent/blob/main/cmd/root.go"
click node_agent "https://github.com/castai/k8s-agent/blob/main/cmd/agent/run.go"
click node_config "https://github.com/castai/k8s-agent/blob/main/internal/config/config.go"
click node_provider "https://github.com/castai/k8s-agent/tree/main/pkg/services/providers"
click node_discovery "https://github.com/castai/k8s-agent/blob/main/internal/services/discovery/discovery.go"
click node_registration "https://github.com/castai/k8s-agent/blob/main/pkg/castai/castai.go"
click node_leader "https://github.com/castai/k8s-agent/blob/main/internal/services/replicas/leaderelection.go"
click node_controller "https://github.com/castai/k8s-agent/blob/main/internal/services/controller/controller.go"
click node_informers "https://github.com/castai/k8s-agent/blob/main/internal/services/controller/controller.go"
click node_handlers "https://github.com/castai/k8s-agent/blob/main/internal/services/controller/handlers/handler.go"
click node_crds "https://github.com/castai/k8s-agent/tree/main/internal/services/controller/crd"
click node_delta "https://github.com/castai/k8s-agent/tree/main/internal/services/controller/delta"
click node_castai "https://github.com/castai/k8s-agent/blob/main/pkg/castai/castai.go"
click node_logexport "https://github.com/castai/k8s-agent/blob/main/pkg/log/exporter.go"
click node_monitor "https://github.com/castai/k8s-agent/blob/main/cmd/monitor/run.go"
click node_dump "https://github.com/castai/k8s-agent/blob/main/cmd/dump/run.go"
click node_healthmetrics "https://github.com/castai/k8s-agent/blob/main/internal/services/metrics/service.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_commands,node_agent,node_config toneBlue
class node_provider,node_discovery,node_registration,node_leader,node_controller,node_informers,node_handlers,node_crds toneAmber
class node_delta,node_castai,node_logexport,node_kubernetes toneMint
class node_monitor,node_dump,node_healthmetrics toneRose
class node_operator,node_platform toneIndigo
```

## Components

### Agent startup

- [Agent entry](https://github.com/castai/k8s-agent/blob/main/main.go): `main.go`
- [Command routing](https://github.com/castai/k8s-agent/blob/main/cmd/root.go): `cmd/root.go`
- [Agent runtime](https://github.com/castai/k8s-agent/blob/main/cmd/agent/run.go): `cmd/agent/run.go`
- [Configuration](https://github.com/castai/k8s-agent/blob/main/internal/config/config.go): `internal/config/config.go`

### Cluster integration

- [Provider adapters](https://github.com/castai/k8s-agent/tree/main/pkg/services/providers): `pkg/services/providers`
- [Cloud discovery](https://github.com/castai/k8s-agent/blob/main/internal/services/discovery/discovery.go): `internal/services/discovery/discovery.go`
- [Cluster registration](https://github.com/castai/k8s-agent/blob/main/pkg/castai/castai.go): `pkg/castai/castai.go`
- [Leader election](https://github.com/castai/k8s-agent/blob/main/internal/services/replicas/leaderelection.go): `internal/services/replicas/leaderelection.go`
- [Resource controller](https://github.com/castai/k8s-agent/blob/main/internal/services/controller/controller.go): `internal/services/controller/controller.go`
- [Resource informers](https://github.com/castai/k8s-agent/blob/main/internal/services/controller/controller.go): `internal/services/controller/controller.go`
- [Event handlers](https://github.com/castai/k8s-agent/blob/main/internal/services/controller/handlers/handler.go): `internal/services/controller/handlers/handler.go`
- [Agent resource types](https://github.com/castai/k8s-agent/tree/main/internal/services/controller/crd): `internal/services/controller/crd`

### CAST AI telemetry

- [Delta batching](https://github.com/castai/k8s-agent/tree/main/internal/services/controller/delta): `internal/services/controller/delta`
- [CAST AI API client](https://github.com/castai/k8s-agent/blob/main/pkg/castai/castai.go): `pkg/castai/castai.go`
- [Remote log export](https://github.com/castai/k8s-agent/blob/main/pkg/log/exporter.go): `pkg/log/exporter.go`

### Operations

- [Monitor mode](https://github.com/castai/k8s-agent/blob/main/cmd/monitor/run.go): `cmd/monitor/run.go`
- [Diagnostic dump](https://github.com/castai/k8s-agent/blob/main/cmd/dump/run.go): `cmd/dump/run.go`
- [Health and metrics](https://github.com/castai/k8s-agent/blob/main/internal/services/metrics/service.go): `internal/services/metrics/service.go`

### Other components

- **Cluster operator**
- **CAST AI platform**
- **Kubernetes API**

## Connections

- Cluster operator → Agent entry: starts (evidence: `README.md`)
- Agent entry → Command routing: executes (evidence: `main.go`)
- Command routing → Agent runtime: routes to (evidence: `cmd/root.go`)
- Command routing → Monitor mode: routes to (evidence: `cmd/root.go`)
- Command routing → Diagnostic dump: routes to (evidence: `cmd/root.go`)
- Agent runtime → Configuration: loads (evidence: `cmd/agent/run.go`)
- Agent runtime → Provider adapters: selects provider
- Agent runtime → Cluster registration: registers cluster (evidence: `cmd/agent/run.go`)
- Agent runtime → Leader election: starts optionally (evidence: `cmd/agent/run.go`)
- Agent runtime → Resource controller: starts (evidence: `cmd/agent/run.go`)
- Provider adapters → Cloud discovery: discovers cloud
- Agent runtime → Cloud discovery: uses for identity
- Resource controller → Kubernetes API: watches resources (evidence: `internal/services/controller/controller.go`)
- Resource controller → Resource informers: starts (evidence: `internal/services/controller/controller.go`)
- Resource controller → Event handlers: dispatches events
- Event handlers → Delta batching: queues changes (evidence: `internal/services/controller/handlers/handler.go`)
- Resource controller → Agent resource types: watches custom resources (evidence: `internal/services/controller/controller.go`)
- Resource controller → Delta batching: batches changes (evidence: `internal/services/controller/controller.go`)
- Delta batching → CAST AI API client: uploads deltas
- Cluster registration → CAST AI platform: registers cluster (evidence: `pkg/castai/castai.go`)
- CAST AI API client → CAST AI platform: sends API requests (evidence: `pkg/castai/castai.go`)
- Remote log export → CAST AI API client: sends log events (evidence: `pkg/log/exporter.go`)
- Agent runtime → Health and metrics: serves endpoints (evidence: `cmd/agent/run.go`)
