Agents & Execution
The pull-based executors that turn desired state into real state
Everything so far describes what should exist. Agents are who makes it real. They are the execution layer, and the single most important property to understand is the direction of control.
Pull-based by design
Admiral never reaches into your environment. Agents run next to your workloads, register with the control plane, and pull their own work. The control plane hands out jobs and revisions; agents fetch and execute them and report back.
┌────────────┐ pulls work ┌─────────┐
│ Admiral │ ◀───────────────────────────│ Agent │
│ server │ ───────────────────────────▶│ │
└────────────┘ hands out jobs/revisions └─────────┘
│
▼
your cloud / clusterThis means an agent only needs outbound connectivity to Admiral. Admiral needs no inbound path into your accounts or clusters, and holds no standing credentials to them.
One concept, two kinds
Terraform and Kubernetes are the two kinds of the one Agent concept. The kind determines what an agent executes and where it runs.
| Agent kind | Executes | Runs | Pulls |
|---|---|---|---|
| Terraform | infrastructure components (terraform) | wherever it has cloud access | jobs |
| Kubernetes | workload components (helm / kustomize / manifest) | inside the target Kubernetes cluster | revisions |
A Terraform agent runs Terraform where it has the cloud credentials and network access to do so. It pulls plan and apply jobs, executes them, and streams results back.
A Kubernetes agent runs inside the Kubernetes cluster it manages, GitOps-style. It pulls rendered revisions for the workloads bound to it and reconciles them against the cluster.
How a component reaches an agent
An environment binds execution by giving each component a target: which agent runs it. When a changeset is applied, the component's target is copied onto it (the same copy-not-link rule as everything else), and the run dispatches each component's work to the agent named by its target.
Component (kind: workload, target: prod-k8s)
│
▼ on apply, work is dispatched...
Kubernetes agent "prod-k8s" ──pulls──▶ renders + reconcilesBecause dispatch follows the component's kind, you cannot accidentally send a Terraform job to a Kubernetes agent or a Helm release to a Terraform agent. The kind and the target are validated together.
Registering an agent
An agent is registered with Admiral, which yields a token. The agent uses that token to authenticate when it pulls work. You install it near its target and it begins pulling.
admiral agent register --kind kubernetes --name prod-k8s
# install the agent into the target cluster with the issued tokenTerraform agents are typically provisioned with a service account token during environment bootstrap; Kubernetes agents are installed via Helm chart into the cluster they manage. See the agent lifecycle guide for the operational detail.
Execution identity
An agent acts with the identity of wherever it runs. A Terraform agent deploys to your cloud using the credentials present in its environment - an IAM role, instance profile, or configured cloud credentials you grant when you install it. A Kubernetes agent reconciles with its in-cluster service account. Admiral holds no standing credentials to your accounts or clusters; the identity lives with the agent.
This is separate from a Credential, which is the stored secret a private Source uses for fetching - not an execution identity.
Because execution runs with agent-held identity, Admiral can coordinate deployments across many clouds and clusters without ever being a standing point of inbound access to any of them.