Remote R2 backend

Last updated Apr 21, 2026 and Terraform remote backends ↗︎ can interact with each other to provide a seamless experience for Terraform state management.

Cloudflare R2 is an object storage service that provides a highly available, scalable, and secure way to store and serve static assets, such as images, videos, and static websites. R2 has S3 API compatibility making it easy to integrate with existing cloud infrastructure and applications.

Prerequisites

Create R2 bucket

Using Wrangler, API, or Account View Dashboard ↗︎ create an R2 Bucket.

wrangler r2 bucket create <YOUR_BUCKET_NAME>

 curl https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/buckets \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"name": "<YOUR_BUCKET_NAME>"}'

Note

Bucket names can only contain lowercase letters (a-z), numbers (0-9), and hyphens (-).

Create scoped bucket API keys

Next you will need to create a bucket scoped R2 API token with Object Read & Write permissions. To create an API token, do the following:

  1. In Account Home, select R2.
  2. Under Account details, select Manage R2 API tokens.
  3. Select Create API token ↗︎.
  4. Select the R2 Token text to edit your API token name.
  5. Under Permissions, select the Object Read and Write permissions, then scope your token to your <YOUR_BUCKET_NAME> bucket.
  6. Select Create API Token.

After your token has been successfully created, review your Secret Access Key and Access Key ID values.

Define R2 backend

Update your cloudflare.tf file to include a backend ↗︎ for the <YOUR_BUCKET_NAME> bucket you created above.

Note

Terraform code snippets below refer to the v4 SDK only.

terraform {
  backend "s3" {
    bucket = "<YOUR_BUCKET_NAME>"
    key    = "/some/key/terraform.tfstate"
    region                      = "auto"
    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
    skip_s3_checksum            = true
    use_path_style              = true
    access_key = "<YOUR_R2_ACCESS_KEY>"
    secret_key = "<YOUR_R2_ACCESS_SECRET>"
    endpoints = { s3 = "https://<YOUR_ACCOUNT_ID>.r2.cloudflarestorage.com" }
  }
  required_providers {
    cloudflare = {
      source = "cloudflare/cloudflare"
      version = "~> 4"
    }
  }
}
provider "cloudflare" {
  # token pulled from $CLOUDFLARE_API_TOKEN
}
variable "account_id" { default = "<YOUR_ACCOUNT_ID>" }

Migrate state file to R2 backend

After updating your cloudflare.tf file you can issue the terraform init -reconfigure command to migrate from a local state to remote state ↗︎.

Was this helpful?

YesNo

On this page

Remote R2 backend - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/terraform/advanced-topics/remote-backend/#page","headline":"Remote R2 backend","description":"Store Terraform state files remotely using Cloudflare R2 as an S3-compatible backend.","url":"https://developers.cloudflare.com/terraform/advanced-topics/remote-backend/","inLanguage":"en","image":"https://developers.cloudflare.com/terraform/advanced-topics/remote-backend/og.png?v=0142625ae602a8ae","dateModified":"2026-04-21","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Fix the 403 authentication error caused by incorrect zone data source indexing in Terraform. title: 403 Authentication error when creating DNS records image: https://developers.cloudflare.com/terraform/troubleshooting/authentication-error-dns-records/og.png?v=a5efb385efc627d6

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/terraform/llms.txt
Use this file to discover all available pages before exploring further.