Cluster Agent
The Cluster Agent is the tenant-side executor. It runs inside the tenant's Kubernetes cluster and is the only component that directly touches the customer's infrastructure at runtime.
What It Does
The agent runs as a Kubernetes deployment inside the tenant cluster. Its job is simple: repeatedly ask the Control Plane "is there anything for me to do?", claim a command, execute it, and report back.
This pull-based model is deliberate. The Control Plane never needs inbound network access to the tenant's cluster — the agent reaches out, not the other way around. Tenant credentials and secrets never leave the cluster.
The agent handles four execution types:
| Type | What It Does |
|---|---|
| Helm releases | Installs or upgrades a Helm chart via helm upgrade --install. Used for most application deployments. |
| Kubernetes manifests | Applies raw YAML resources via kubectl apply. Used for namespaces, RBAC, CRDs, and cluster-level setup. |
| OpenTofu runs | Clones a git repo and runs tofu apply inside the cluster. Used for in-cluster infrastructure requiring Terraform. |
| Flows | A sequential pipeline of the above, executed in order. Used when a resource requires multiple coordinated steps. |
Bootstrap and Identity
On first startup, the agent exchanges a one-time bootstrap token — issued by the Control Plane when the workspace is created — for mTLS credentials: a client certificate and key that identify this agent going forward. These credentials are stored in a Kubernetes Secret so subsequent restarts skip the bootstrap step.
From that point on, all communication between the agent and the Control Plane is authenticated with mTLS.
Secret Handling
The agent resolves secrets at execution time from Kubernetes Secrets in the cluster — never from the Control Plane. When a Helm values file references a database password, the agent reads it directly from the cluster secret store. The Control Plane never sees the value; it only knows the secret's name.
After execution, the agent writes outputs (connection strings, credentials produced by infrastructure) back into cluster secrets, making them available to downstream resources in the same stack.
How It Relates to Other Services
| Service | Relationship |
|---|---|
| Control Plane | Polls for commands. Reports results and outputs back after each execution. |
| Keycloak | Does not use Keycloak for authentication. Uses mTLS certificates issued at bootstrap time. |
| Platform Stacks | Executes the Helm, manifest, and Terraform resources defined in bundle specs. |
Go Deeper
- Platform Developer → Deployment Lifecycle
- Security → Authentication in the Control Plane