TFstate.dev ✨

TFstate.dev is a free Terraform State Provider and Open Source Hosted Service for secure Terraform Remote State hosting using a GitHub Token, courtsey of Scaffoldly

Features:

• GitHub Token used for Authentication and Authorization to Terraform State
• Encrypted State in Amazon S3 using Amazon KMS
• State Locking
• Highly available Hosted API in AWS Lambda + API Gateway
• Plug and Play: Only a GitHub Token is needed to use TFstate.dev

✅ We do not store or save the provided GitHub token.

---

Getting started 🚀

First, a GitHub token is needed. This can be a Personal Access Token, a GitHub Actions Secret, or any other form of GitHub Oauth Token. At a minimum, the token needs repo:read access for the configured repository.

➡ See our example repository.

To use TFstate.dev in Terraform, add the following backend configuration to Terraform:

terraform {
  backend "http" {
    address        = "https://api.tfstate.dev/github/v1"
    lock_address   = "https://api.tfstate.dev/github/v1/lock"
    unlock_address = "https://api.tfstate.dev/github/v1/lock"
    lock_method    = "PUT"
    unlock_method  = "DELETE"
    username       = "{your-github-org}/{your-github-repo}"
  }
}

Then, Terraform can be configured to use the TFstate.dev backend using the GitHub token:

terraform init -backend-config="password={your-github-token}"
terraform plan
terraform apply

Alternatively, the TF_HTTP_PASSWORD environment variable can be set with the GitHub token:

export TF_HTTP_PASSWORD="{your-github-token}"
terraform init
terraform plan
terraform apply

⚠️ Note: If the token previously used has rotated or been changed (such as a GitHub Actions Secret), add the -reconfigure flag.

---

Additional Topics

The following sections detail specifics on how to use TFstate.dev on a regular basis.

Is there anything we haven’t covered or do you need additional help? Message us on Gitter.

Migrating to TFstate.dev

First, change your Terraform Configuration to use TFstate.dev as the Backend:

terraform {
  backend "http" {
    address        = "https://api.tfstate.dev/github/v1"
    lock_address   = "https://api.tfstate.dev/github/v1/lock"
    unlock_address = "https://api.tfstate.dev/github/v1/lock"
    lock_method    = "PUT"
    unlock_method  = "DELETE"
    username       = "{your-github-org}/{your-github-repo}"
  }
}

Then initalize Terraform and migrate state:

export TF_HTTP_PASSWORD="{your-github-token}"
terraform init -migrate-state
terraform plan

Using terraform_remote_state

Using the terraform_remote_state data resource is possible for state sharing.

Use the TF_HTTP_PASSWORD is required, as the GitHub token should NEVER be checked into Source Control.

➡ See our example remote repository, which pulls state from example.

Example:

data "terraform_remote_state" "example" {
  backend = "http"

  config = {
    address        = "https://api.tfstate.dev/github/v1"
    username       = "{your-github-org}/{other-github-repo}"
  }
}

Then plan and apply operations will work:

export TF_HTTP_PASSWORD={your-github-token}
terraform plan
terraform apply

ADVANCED: Manually Unlocking State

If locking or unlocking state is necssary, use the terraform force-unlock command:

terraform force-unlock {lock-id}

---

Contributing 💪

Readme/Docs

We’d love PRs to make things clearer for users. For TFstate.dev there’s two important READMEs:

• This Readme (Also the tfstate.dev website)
• GitHub SLS REST API

Backends

• Githb SLS REST API
  • This is the Open Source Backend for TFstate.dev
  • Follow the Contributing Guidelines

Financial Support

TFstate.dev is provided as a free Hosted API and Open Source project to accelerate the proper usage of Terraform and minimize dependencies.

Scaffoldly generously hosts this API free-of-charge, but donations are graciously acceepted to help cover costs.

Visit TFstate.dev on OpenCollective.

---

About TFstate.dev 📚

TFstate.dev was created to simplify the number of prerequisties required to use Terraform. We desire to extend the functionality of a GitHub token beyond GitHub, and this allows adoption of Terraform along with secure state storage with the one-and-only prerequisite to generate a GitHub token and begin using Terraform.

Scaffoldly is a developer of various tooling designed to ease and simplify the adoption of DevOps for new project. TFstate.dev is one of Scaffoldly’s many projects.

Want to get in touch? Message us on Gitter.

Copyright 2022 Scaffoldly LLC