Introduction
Architecture
Admiral hosts the control plane, and agents on your infrastructure pull their work, so Admiral needs no path into your cloud or clusters.
Admiral hosts the control plane and operates it for you. Agents run on infrastructure you operate and pull their work from it. Admiral never connects into your clusters or runs your Terraform. It connects out only to fetch: a registry pull reads from a source you name, and for a GKE or EKS cluster Admiral reads the issuer's public signing keys.
Where does my code run?
On an agent. Admiral only renders a Helm chart into manifests, and every plan and apply runs on an agent. You publish each component's code to the registry with admiral component publish, as a bundle, the packed bytes of a Terraform module, a Helm chart, or raw manifests. A published bundle is an immutable revision, identified by its digest. A Terraform agent pulls the bundle and runs it. A Kubernetes agent pulls the manifests Admiral renders from it.
- A Terraform agent runs on a machine you operate, wherever that machine can reach your cloud. It pulls the Terraform bundle and runs plan and apply there. The Terraform agent has not shipped yet.
- A Kubernetes agent runs in the cluster. Admiral renders a Helm chart into manifests and passes raw manifests through as written. The agent pulls those manifests and plans them, and reconciles them at apply. Today it plans only.
What happens to a Helm chart's hooks and lookup?
Admiral renders a chart the way helm template does, without a cluster. Hooks are kept and ordered by helm.sh/hook-weight, for the agent to run in their phases at apply. lookup returns nothing without a cluster, so Admiral reports every template that calls it when it renders.
What does my network need to allow?
One outbound path. An agent dials api.admiral.io. It needs no inbound rule, no port mapping, and no route from Admiral back to the agent. An agent in a local kind cluster can reach Admiral as long as that cluster has outbound internet.
The cloud credential used to plan and apply stays on the agent. Admiral does not store it. Inside a cluster, the Kubernetes agent can do what its role allows, so decide its permissions before you install it. Agents explains how that keeps who may ship apart from what the cloud allows.
What does the control plane keep?
The resource model: applications, environments, components, changesets, runs, agents, sources, and the registry. The Concepts overview defines each one.
- Desired state is the set of components in an environment. Each component pins a registry revision and carries its own values. When you add a component from a catalog item, or copy one from another environment, Admiral copies the definition onto it. Editing the catalog item or the other component later does not change it.
- Components declare inputs and outputs and form a dependency graph. An upstream applies, Admiral records its outputs, and the next component renders against those values.
- You change an environment through a changeset, a reviewed batch of changes to one environment. Planning it starts a run, which plans each changed component. You approve once. A component whose inputs come from another component's outputs is planned only after that upstream applies, so you approve without seeing its plan. Apply has not shipped yet.
- Admiral hosts Terraform state for a Terraform component, unless the component keeps a backend of its own. The plan runs on the agent, and Admiral records the plan result. For each component it works on, the Terraform agent gets a short-lived token that reaches only that component's state and expires with the run.
- A change made outside Admiral shows up as drift.
Does Admiral store my secrets?
Yes, if you put one in a value or pass one to an ordinary Terraform argument. Reading it in the code keeps it out.
- A Terraform component reads a secret in its own code with an ephemeral resource, such as one for GCP Secret Manager, AWS Secrets Manager, or Vault, and passes it to a write-only argument. The value never reaches the run artifact, the plan file, or state.
- A Helm chart gets no secret resolution. It keeps the secret handling it already uses, such as Sealed Secrets, External Secrets, or Vault.
- A value you write in plaintext, including one in a Helm chart's values, is stored as you wrote it.
- A secret passed to an ordinary Terraform input lands in Terraform state, which Admiral hosts unless you keep your own backend. An ephemeral input or a write-only argument does not.
Secrets covers each case.
Admiral encrypts what it stores the same way: a value, hosted Terraform state, and a credential for fetching from a private source. Every value, every state version, and every credential is encrypted with AES-256-GCM under its own data key. That key is wrapped by a key for your organization, which is wrapped by a root key held in a cloud KMS. Admiral holds those keys, so it can decrypt what it stores. It decrypts values when it renders a component, hosted state when it serves it to an agent or a person, and a credential only during a registry pull. A stored credential is never the cloud credential an agent uses.
How do I manage Admiral?
In the console or with the admiral CLI. The CLI, the Terraform provider, and the Go SDK call the API at api.admiral.io.
- The console is for day-to-day use in the browser.
- The
admiralCLI is for a terminal and for CI. - The Terraform provider manages Admiral resources as code.
- The Go SDK builds automation against the API.
- The OpenAPI document is the REST contract behind the API reference.
Why is it split this way?
Admiral hosts the control plane, so scaling, patching, and backups are Admiral's job, not your team's.
The agents run where the access already is. That lets Admiral coordinate many clouds and clusters without a path into any of them, and it lets a team ship without holding the cloud credential. Only the agent holds it.