Concepts Overview
The mental model behind Admiral: resources, ownership, and the deploy flow
Admiral coordinates infrastructure and application delivery across environments. This page lays out the model: the resources, how they nest, and how changes become deployments.
The core idea
Admiral separates what should exist from who makes it real.
- Desired state is per-environment. A Component pairs your configuration with a Source (where the code lives), and each deploy records an immutable Revision of exactly what shipped.
- Execution is pull-based. Agents run in your own accounts and clusters and pull their own work; Admiral never reaches in.
- Change is always reviewable. You never edit live state directly. You stage changes, plan them, and apply them as a single reviewable unit.
The spine: Source, Component, Revision
Three resources form the backbone of what Admiral deploys.
- Source is where bytes live: a type (git, terraform, helm, oci, http), a URL, and optional credentials for private locations.
- Component is the heart of the model: the per-environment desired state you own and edit. It holds its own definition (where to fetch from, how to deploy it, and its values), so an environment never depends on a shared template.
- Revision is the immutable snapshot a deploy produces. It is the history that rollback replays.
A Catalog Item is an optional shortcut, not a step in the flow: a saved template you can use to prefill a Component instead of writing it out by hand. Without one, you author a Component's definition directly, or copy it from another environment.
Ownership
Resources nest into an ownership hierarchy:
An Application groups related work. Each Environment in it holds a set of Components, and a Component lives in exactly one environment.
The change and deploy flow
You never mutate a component directly. Every change flows through a changeset.
- A Changeset is a reviewable batch of changes scoped to one environment. Many can be open at once, like branches.
- A Change is one staged edit to one component: create, update, destroy, or orphan.
- A Run is one execution of an applied changeset. Plan and apply are two phases of one run, not two runs.
- A Revision is produced per changed component when it applies.
A run walks the dependency graph in waves. It plans what it can, defers components whose inputs depend on another component's outputs, then on apply walks the graph one wave at a time: each upstream applies, its outputs are captured, and downstream components render against those outputs and apply. There is a single approval gate at the first apply; the rest of the wavefront cascades automatically.
A changeset is not an atomic transaction. Once an upstream component applies, that state has changed regardless of whether downstream components succeed. There is no automatic rollback of a partial apply.
Execution
Components describe what. The environment binds where it runs through Agents. An agent registers with Admiral, runs where it has access to its target, and pulls its own work.
| Component kind | Engine | Runs via |
|---|---|---|
| infrastructure | terraform | Terraform agent runs where it has cloud access and pulls jobs |
| workload | helm / kustomize / manifest | Kubernetes agent runs inside the target cluster and pulls revisions |
Terraform and Kubernetes are the two kinds of the one Agent concept. An agent never has Admiral reach into it; the direction of control is always agent-to-server.
The data layer
Two kinds of values feed rendering:
- Variables are config you set, referenced in templates as
.var. - Outputs are values a component emits once it deploys, referenced as
.component.NAME.OUTPUT. They are how one component hands data to the next.
Outputs flow along the dependency graph, and across kinds: a Terraform infrastructure component can emit a database endpoint that a Helm workload component reads as an input. The wave-based apply is what makes this real: an upstream applies, its outputs are captured, and the downstream renders against the actual values before it applies.
This is what lets you keep components small and reusable and wire them together, carrying real values across the infrastructure-to-workload boundary instead of copying them by hand.
At apply, each component's values template renders against .var, .component, .self, and .app into the immutable values stored on its Revision.
Where to go next
Sources & Catalog
Where bytes live and the reusable templates that point at them
Applications & Components
The ownership hierarchy and per-environment desired state
Changesets & Runs
How a staged change becomes a deployment
Agents & Execution
The pull-based executors that make state real
Variables & Outputs
How configuration and cross-component data flow