Using Self-Hosted Remote State

Store env zero remote backend state in your own AWS S3 bucket 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.

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 to ensure your existing resources are configured correctly.

Prerequisites

• An AWS account with permissions to create S3 buckets and IAM roles
• AWS credentials configured 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

1. Deploy the remote state bucket module

   Deploy the 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 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).

   main.tf

   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>"
   }
   

   terraform

   terraform init && terraform apply
   

   opentofu

   tofu init && tofu apply
   
2. 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

3. Contact env zero support

   Send the four output values to env zero support. The support team will configure your organization to use your bucket for remote state storage.

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.