> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.34.0/getting-started/deployment/http-state-backend.md).

# Executor HTTP State Backend

Added in Terrakube 2.34.0, the HTTP state backend lets the executor read and write current Terraform state through the Terrakube API. The API persists it in the configured storage backend. The Helm chart (4.7.16) **enables it by default**. Terrakube itself defaults `TerraformStateHttpBackend` to `false`, so deployments that don't use the chart must turn it on.

Use it when you want Terraform state operations to use workspace-scoped executor credentials through the API. Plans, logs, artifacts and binary caches still use the executor's configured storage implementation, so enabling it does not remove all executor storage credentials or access requirements.

### Enable it

Upgrade the API and executors to 2.34.0 before enabling this feature. With the Helm chart it is already on (`storage.httpBackend: true`; `executor.properties.httpBackend` overrides it for the executor). Set either to `false` to keep state on the configured storage only. Without the chart, on each executor, including standalone and ephemeral agents that should use it, set:

```yaml
executor:
  env:
    - name: TerraformStateHttpBackend
      value: "true"
```

Retain the existing storage configuration. The HTTP implementation wraps it for state operations and delegates the other storage operations. Configure equivalent environment variables in your standalone/ephemeral executor deployment as needed.

The executor generates `terrakube_override.tf` with an HTTP backend pointing at:

```
/tfstate/v1/organization/{organizationId}/workspace/{workspaceId}/backend/terraform.tfstate
```

It passes authentication through `TF_HTTP_USERNAME` and `TF_HTTP_PASSWORD`, keeping credentials out of the generated backend configuration. Users continue to use their existing Terrakube workflow; they do not replace their local `cloud` or `remote` block with this executor endpoint.

### Access and limits

The token the executor uses lasts as long as the executor's maximum job duration (`ExecutorJobMaxDurationMinutes`, 360 minutes by default), so long applies and destroys can still write state at the end. Terrakube revokes it as soon as the step finishes. To set the lifetime separately, use `TerraformStateHttpTokenTtlMinutes` on the executor.

The endpoint accepts scoped `WORKSPACE_EXECUTOR` tokens matching the organization and workspace. It is not a general-purpose HTTP backend for user PATs. Plan steps can read state but cannot write or delete it. Apply, destroy and custom-script flow steps can write/delete state with the required executor token.

| API behavior                                                     | Result                  |
| ---------------------------------------------------------------- | ----------------------- |
| GET with no current state                                        | `204 No Content`        |
| POST/PUT with an empty body or mismatched supplied `Content-MD5` | `400 Bad Request`       |
| Upload exceeding `TerraformStateMaxSizeBytes`                    | `413 Payload Too Large` |
| Missing/invalid credentials or insufficient scope                | `401` or `403`          |

`TerraformStateMaxSizeBytes` is an **API** environment variable with a default of `104857600` bytes (100 MiB). Change it if your state requires a different upload limit. Writes and deletes log organization, workspace, job and step identifiers for audit context.

This endpoint does not implement HTTP backend lock/unlock operations. Terrakube continues to serialize runs per workspace; do not treat it as a separately managed state service for external writers.

See [Terraform State](https://docs.terrakube.io/2.34.0/run-terraform/workspaces/terraform-state.md) for viewing versions, and the [API](https://docs.terrakube.io/2.34.0/reference/configuration/api.md) and [executor](https://docs.terrakube.io/2.34.0/reference/configuration/executor.md) configuration references for exact environment variable names.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terrakube.io/2.34.0/getting-started/deployment/http-state-backend.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
