--- title: "State" canonical: "https://admiral.io/docs/concepts/state" description: "Admiral hosts one Terraform state per component in an environment, or a component keeps the backend it already uses." --- # State A Terraform component keeps its state in Admiral by default, or in the backend it already uses. A Helm or manifest component has no Terraform state. ## How is state organized? [#how-is-state-organized] Each Terraform component in an environment has one state. An environment can hold many components published from the same registry entry, and each of those components has its own state. The address you see is the application, the environment, and the component, as in `my-api/prod/users-db`. On the wire the name is `__`, and the organization is your tenant. Admiral names do not contain `_`, so the three parts split back apart. State is stored against the component itself, so renaming the component does not move the state. ## How do a run and a person reach hosted state? [#how-do-a-run-and-a-person-reach-hosted-state] Admiral serves the part of the HCP Terraform API that the Terraform `cloud` block uses to store and lock state, at `api.admiral.io`. Terraform and OpenTofu still plan and apply where they were started. Admiral stores the state. The HTTP backend is not offered. ```mermaid flowchart LR Person["Person
personal API key"] --> API["Admiral
cloud backend"] Agent["Terraform agent
per-run token"] --> API API --> State["One state
per Terraform component"] ``` A run and a person use that same backend. * Admiral writes the `cloud` block into the [run artifact](https://admiral.io/docs/security/secrets.md#how-do-i-keep-a-secret-out-of-admiral). The Terraform agent receives `TF_TOKEN_`, a credential Admiral issues, scoped to the one component state it is working on, and the token expires with the run. The agent's own token for Admiral is never the state credential. * A person uses a [personal API key](https://admiral.io/docs/access.md#personal-api-keys) limited to the Terraform API. It acts with that person's permissions, and the limit keeps it to the Terraform API. The `admiral` CLI will put that key on the machine as a Terraform credentials helper, so `terraform` finds it for `api.admiral.io` with no extra step. The helper ships with hosted state. ## Can I keep my own backend? [#can-i-keep-my-own-backend] Yes. A Terraform component can keep the backend it already uses, such as Amazon S3, Google Cloud Storage, Azure Blob Storage, or HCP Terraform. The Terraform agent reaches that backend with the credentials it already has on the machine it runs on, and Admiral never holds that state. The rest of this page is about hosted state. None of it applies to a backend you keep: the per-run token, state writes from people through Admiral, and the encryption Admiral applies to what it stores. ## Can I write state outside a changeset? [#can-i-write-state-outside-a-changeset] You can read and write state outside a changeset. `state mv`, `import`, and `state rm` are ordinary work, and a platform that allowed state writes only through its own runs would have no way to do them. A write from outside a run moves the environment. Open changesets rebase onto that state, and an approval stands only when the new plan is identical to the one that was approved. The state lock follows the environment lock, so a partial apply that is holding the environment also refuses a person's write. Every state version records who wrote it, a run or a person. Existing state is adopted by a person with `terraform init -migrate-state` into this backend. ## Where to go next [#where-to-go-next] * [Secrets](https://admiral.io/docs/security/secrets.md): Why a secret fed to an ordinary input can land in state * [Authentication](https://admiral.io/docs/access.md): The personal API key a person uses to reach hosted state