Concepts
Concepts Overview
How Admiral's applications, environments, and components nest, and how a changeset becomes a live deployment.
Admiral coordinates infrastructure and application delivery across environments. This page lays out the model: the resources, how they nest, and how changes become deployments.
How does Admiral model a deployment?
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 pins a Revision, an immutable published version of that code.
- Execution is pull-based. Agents run on machines you operate and in your 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.
What does Admiral deploy?
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 (the registry revision it pins, how to deploy it, and its values), so an environment never depends on a shared template.
- Revision is an immutable version of a component's code in the registry, identified by its digest. A component pins one, and many components can pin the same one.
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.
Who owns what?
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.
How does a change become a deploy?
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 a changeset. Planning starts it, and plan and apply are its two phases, not two runs.
- When a component applies, it records the revision it now runs and the digest of its rendered values.
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.
Where does the work run?
Components describe what. The environment binds where it runs through Agents. An agent enrolls 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 the Terraform bundle |
| workload | helm / manifest | Kubernetes agent runs inside the target cluster and pulls the manifests Admiral renders |
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.
How do values reach a component?
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.
When you plan, each component's values template renders against .var, .component, .self, and .app into immutable values. A component that reads another component's outputs renders again once that upstream applies. The component records their digest beside the revision it runs.
Where to go next
Applications & Components
The ownership hierarchy and per-environment desired state
Sources & Catalog
Where a component's code comes from, and the optional template
Registry
Push a repository you own, or pull a copy of an artifact you do not
State
One Terraform state per component, hosted or in your own backend
Variables & Outputs
How configuration and cross-component data flow
Changesets & Runs
How a staged change becomes a deployment
Drift
A change outside the changeset, shown on review
Promote to production
Promote your tested changeset from dev to prod: Admiral copies changes into a new prod changeset, re-based on prod's own state, with per-env values resolved.
Applications & Components
Admiral's ownership hierarchy: applications group environments like dev and prod, and each component is the per-environment desired state you own and change.