> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Self-Hosted Remote State

> Store env zero remote backend state in your own AWS S3 bucket using the env zero Terraform module for data residency and compliance requirements.

env zero stores remote backend state securely by default, with encryption and SOC-II compliance. However, if you need to store state within your own AWS account (for example, for data residency or compliance requirements), you can configure env zero to use your own S3 bucket.

This only affects environments using the env zero remote backend. Environments using a standard Terraform S3 backend are not affected.

<Info>
  **We recommend using the env zero-provided module** to create the required S3 bucket and IAM resources. The module sets up the correct bucket configuration and a trust relationship that allows env zero's infrastructure to securely access your state.

  It is possible to use an existing S3 bucket, but the bucket configuration and IAM role must match what the module creates. Review the [module source code](https://github.com/env0/remote-state-bucket-module/tree/main/aws) to ensure your existing resources are configured correctly.
</Info>

## Prerequisites

* An AWS account with permissions to create S3 buckets and IAM roles
* [AWS credentials configured](/guides/getting-started/connect-your-cloud-account) on the **project** where you will create the environment (if deploying through env zero)
* Your env zero Organization ID (found in **Organization Settings**, where you can copy it directly)

## Setup

<Steps>
  <Step title="Deploy the remote state bucket module">
    Deploy the [env0/remote-state-bucket-module](https://github.com/env0/remote-state-bucket-module) to create the required S3 bucket and IAM role in your AWS account.

    ### Deploying through env zero (recommended)

    1. [Create a new template](/guides/admin-guide/templates) with the following settings:
       * **Repository URL**: `https://github.com/env0/remote-state-bucket-module`
       * **Terraform folder path**: `aws`
    2. Create a new environment from this template
       * Make sure the **Use env zero Remote Backend** option is **disabled** for this environment
    3. Configure the following Terraform variables for the environment:

    | Variable            | Description                            |
    | ------------------- | -------------------------------------- |
    | `external_id`       | Your env zero Organization ID          |
    | `state_bucket_name` | The name for the S3 bucket to create   |
    | `region`            | The AWS region to deploy the bucket in |

    4. Deploy the environment

    ### Deploying locally

    Alternatively, you can deploy the module from your local machine or any other CI/CD pipeline. Make sure you have valid AWS credentials configured (for example, via `aws configure` or environment variables).

    ```hcl main.tf theme={null}
    module "remote_state_bucket" {
      source = "github.com/env0/remote-state-bucket-module//aws"

      external_id       = "<YOUR_ENV0_ORGANIZATION_ID>"
      state_bucket_name = "<YOUR_DESIRED_BUCKET_NAME>"
      region            = "<YOUR_AWS_REGION>"
    }
    ```

    ```bash terraform theme={null}
    terraform init && terraform apply
    ```

    ```bash opentofu theme={null}
    tofu init && tofu apply
    ```
  </Step>

  <Step title="Collect the module outputs">
    After the apply completes, note the following outputs:

    | Output        | Description                                                      |
    | ------------- | ---------------------------------------------------------------- |
    | `role_arn`    | The IAM role ARN that env zero will assume to access your bucket |
    | `external_id` | Your env zero Organization ID (used for secure role assumption)  |
    | `region`      | The AWS region of your bucket                                    |
    | `bucket_name` | The name of the created S3 bucket                                |
  </Step>

  <Step title="Contact env zero support">
    Send the four output values to [env zero support](mailto:support@env0.com). The support team will configure your organization to use your bucket for remote state storage.
  </Step>
</Steps>

<Warning>
  **Before contacting support, be aware:**

  * Once configured, **all** env zero remote backend environments in your organization will use the new bucket
  * Existing remote backend environments will require a state migration to the new bucket. The support team will guide you through this process.
</Warning>

## Next steps

* [Migrating State](/guides/admin-guide/remote-backend/state-migration) - Move existing state to or from the env zero remote backend.
* [Configuring State Access Control](/guides/admin-guide/remote-backend/state-access-control) - Restrict which environments can read your remote state.
* [Remote State Data Source](/guides/admin-guide/remote-backend/remote-state-data-source) - Reference state outputs across Terraform stacks.