---
title: "Agent Lifecycle"
canonical: "https://admiral.io/docs/guides/agent-lifecycle"
description: "Operate Admiral's execution agents end to end: register, install, and validate Terraform and Kubernetes agents, then monitor, rotate, and upgrade them."
---

# Agent Lifecycle

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](https://admiral.io/docs/concepts/agents-and-execution.md); this guide covers operating them.

## The two kinds [#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 [#register]

Registering an agent with Admiral yields a token the agent uses to authenticate when it pulls work.

```bash
admiral agent register --kind kubernetes --name prod-k8s
admiral agent register --kind terraform  --name aws-prod-tf
```

Keep the issued token secret; it is the agent's identity to the control plane.

## Install [#install]

<Steps>
  ### Terraform agent [#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 [#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.
</Steps>

## Validate registration [#validate-registration]

Confirm the agent has connected and is pulling:

```bash
admiral agent list
admiral agent get prod-k8s
```

A healthy agent reports recent heartbeats and its detected tooling.

## Monitor [#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-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.

```bash
admiral agent rotate-token prod-k8s
```

## Upgrade [#upgrade]

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.

## Where to go next [#where-to-go-next]

- [Agents & Execution](https://admiral.io/docs/concepts/agents-and-execution.md): The pull-based execution model in depth

- [Authentication](https://admiral.io/docs/guides/authentication-model.md): Token types and how agents authenticate

- [Connect a Cluster](https://admiral.io/docs/get-started/connect-a-cluster.md): Run an agent and connect your first cluster end to end