Tofu HTTP State Backend

An HTTP state backend for the OpenTofu/Terraform framework that provides serverless state management via IAM token authentication. This backend allows you to store and retrieve OpenTofu/Terraform state files using HTTP requests with IAM-based authentication.

Features

• 🔐 IAM Token Authentication: Secure authentication using IAM tokens from headers or context
• 🗄️ S3-Compatible Storage: Uses Minio client for S3-compatible object storage
• 🚀 Serverless Ready: Designed to work as a serverless function handler
• 📦 Automatic Bucket Management: Creates buckets automatically when needed
• 🔒 Optional Encryption: Supports KMS-based encryption for state files
• 📊 Versioning Support: Optional state file versioning

Usage

Basic Setup

The main handler function can be used with any serverless platform (AWS Lambda, Yandex Cloud Functions, etc.):

const { handler } = require('@64mb/tofu-http-state-backend');

// Use with your serverless platform
exports.myFunction = handler;

In provider

terraform {
  backend "http" {
    address = "<lambda invoke http endpoint (TF_HTTP_ADDRESS)>"
    headers = {
      "Authorization"      = "Bearer <IAM-token from TF_VAR_>"
      "X-State-Bucket"     = "<S3 state bucket>"
      "X-State-Prefix"     = "<S3 state file name>.tfstate.json"
      "X-State-Versioning" = true
    }
  }

  required_version = ">= 1.10.0" # OpenTofu
}

Environment Variables

Configure the backend using these environment variables:

Variable	Description	Default
STORAGE_ENDPOINT	S3-compatible storage endpoint	Required
STORAGE_PORT	Storage port number	443
STORAGE_ACCESS_KEY	Storage access key	Required
STORAGE_SECRET_KEY	Storage secret key	Required
IAM_TOKEN_HEADER	Header name for IAM token	Authorization

HTTP API

The backend provides a RESTful API for state management:

GET - Retrieve State

curl -X GET "https://your-function-url" \
  -H "Authorization: Bearer <iam-token>" \
  -H "X-State-Bucket: bucket" \
  -H "X-State-Prefix: terraform.tfstate"

POST - Update/Create State

curl -X POST "https://your-function-url" \
  -H "Authorization: Bearer <iam-token>" \
  -H "X-State-Bucket: bucket" \
  -H "X-State-Prefix: terraform.tfstate" \
  -H "X-State-Versioning: true" \
  -H "X-State-Encryption-Key: kms-key-id" \
  -d '{"version": 1, "serial": 1, "terraform_version": "1.0.0"}'

DELETE - Remove State

curl -X DELETE "https://your-function-url" \
  -H "Authorization: Bearer <iam-token>" \
  -H "X-State-Bucket: bucket" \
  -H "X-State-Prefix: terraform.tfstate"

Request Headers

Header	Description	Required
Authorization	IAM token (Bearer format)	Yes*
X-State-Bucket	S3 bucket name	No (default: tofu-http-state-bucket)
X-State-Prefix	State file key/prefix	No (default: tfstate.json)
X-State-Versioning	Enable versioning (true/false)	No
X-State-Encryption-Key	KMS key ID for encryption	No

*Either Authorization header or IAM token in context is required

Authentication

The backend supports two methods of IAM token authentication:

1. Authorization Header: Authorization: Bearer <token>
2. Context Token: IAM token provided in the function context

Development

Prerequisites

• Node.js 18+
• npm

Setup

# Clone the repository
git clone https://github.com/64mb/tofu-http-state-backend.git
cd tofu-http-state-backend

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

Building

# Build the distribution package
npm run build

This creates a zip file in the dist/ directory ready for deployment to serverless platforms.

Testing

The project includes a comprehensive test suite using tap and s3rver for mocking S3-compatible storage:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

Project Structure

tofu-http-state-backend/
├── index.js              # Main handler function
├── package.json          # Project configuration
├── build.js              # Build script for deployment
├── test/                 # Test suite
│   ├── index.test.js     # Main test file
│   └── utils.js          # Test utilities
├── tfplan/               # Terraform plan visualizer (subproject)
│   ├── src/              # React source code
│   ├── public/           # Static assets
│   └── README.md         # TFPlan documentation
├── biome.json            # Code formatting configuration
└── LICENSE               # Apache 2.0 License

Deployment

AWS Lambda

1. Build the package: npm run build
2. Upload the dist/tofu-http-state-backend.zip to Lambda
3. Configure environment variables
4. Set the handler to index.handler

Yandex Cloud Functions

1. Build the package: npm run build
2. Create a new function in the Yandex Cloud console
3. Upload the zip file from dist/
4. Configure environment variables
5. Set the entry point to index.handler

TFPlan - Terraform Plan Visualizer

This repository also includes tfplan, a OpenTofu/Terraform plan visualizer:

• Location: tfplan/
• Purpose: Visualize OpenTofu/Terraform plan outputs in a user-friendly format
• Features: Color-coded changes, browser-based, single HTML file output

See the TFPlan README for more details.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes and ensure tests pass
4. Run the linter: npm run lint
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For support and questions:

• Create an issue in the GitHub repository
• Contact: team@64mb.ru

Related Projects

• OpenTofu - The open source infrastructure as code tool
• Terraform - Infrastructure as Code tool
• Minio - High-performance object storage compatible with S3 API