Agent Lifecycle
Register, install, rotate, and monitor execution agents
Agents are Admiral's execution fleet. They register with the control plane, run next to your workloads, and pull their own work. For the conceptual model see Agents & Execution; this guide covers operating them.
The two kinds
An agent's kind determines what it executes and where it runs:
| Kind | Executes | Runs | Installed |
|---|---|---|---|
| Terraform | infrastructure components (terraform) | wherever it has cloud access | as a process or container with cloud access |
| Kubernetes | workload components (helm / kustomize / manifest) | inside the target cluster | via Helm chart into the cluster it manages |
Both kinds share the same lifecycle: register, install, validate, monitor, rotate, upgrade.
Register
Registering an agent with Admiral yields a token the agent uses to authenticate when it pulls work.
admiral agent register --kind kubernetes --name prod-k8s
admiral agent register --kind terraform --name aws-prod-tfKeep the issued token secret; it is the agent's identity to the control plane.
Install
Terraform agent
Run the Terraform agent where it has the cloud access its targets need: an IAM role, instance profile, or configured cloud credentials. Provide the registration token; the agent deploys with the identity of its environment.
Kubernetes agent
Install the Kubernetes agent via its Helm chart into the Kubernetes cluster it will manage, passing the registration token. It connects outbound to Admiral and begins pulling revisions for workloads bound to it.
Validate registration
Confirm the agent has connected and is pulling:
admiral agent list
admiral agent get prod-k8sA healthy agent reports recent heartbeats and its detected tooling.
Monitor
Agents report health and the work they are executing back to the control plane. Watch for:
- Heartbeat staleness - an agent that stops checking in cannot pull new work.
- Job or revision state - in-flight, succeeded, or failed work attributed to the agent.
- Tooling drift: the runtime versions an agent reports, such as which Terraform version a Terraform agent is running.
Rotate credentials
Rotate an agent's token without downtime by issuing a new one, rolling it into the agent's configuration, then revoking the old one.
admiral agent rotate-token prod-k8sUpgrade
Upgrade an agent by deploying the new agent build (a new container image for Terraform agents, a helm upgrade for Kubernetes agents). Because work is pull-based and idempotent, an agent can be restarted or replaced without coordinating with the control plane; it resumes pulling once it reconnects.