realfireau / worker-tfstate

A cloudflare worker for storing terraform state using HTTP backend

Worker-tfstate

This project is a CloudFlare Worker that stores the state of a Terraform workspace in a KV namespace.

Usage

terraform {
  backend "http" {
    address = "https://worker.example.com/api/v1/example"
  }
}

Configuration

The following environment variables are required:

• USERNAME: The username to authenticate with
• PASSWORD: The password to authenticate with (wrangler secret put PASSWORD)
• NAMESPACE_ID: The ID of the KV namespace to use (needs to be bound to the worker) wrangler.toml

Development

Prerequisites

• Node.js
• Wrangler

Setup

npm install

Deployment

wrangler publish

API Reference

All endpoints require basic authentication with the configured username and password.

GET /api/v1/:project

Returns the state of the project as JSON.

curl -X GET https://worker.example.com/api/v1/example -u username:password

Example response - state not found

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Cache-Control: no-store

Example response - state found

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Content-Length: 123
{"version": 4, "terraform_version": "0.12.24", "serial": 4, "lineage": "e2b0f0e0-7f1a-4c4a-8b1a-2b1a0b1a0b1a", "outputs": {}, "resources": []}

POST /api/v1/:project

Updates the state of the project with the JSON body.

curl -X POST https://worker.example.com/api/v1/example -u username:password -H "Content-Type: application/json" -d '{"version": 4, "terraform_version": "0.12.24", "serial": 4, "lineage": "e2b0f0e0-7f1a-4c4a-8b1a-2b1a0b1a0b1a", "outputs": {}, "resources": []}'

Example response - state updated

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Content-Length: 123
{"version": 4, "terraform_version": "0.12.24", "serial": 4, "lineage": "e2b0f0e0-7f1a-4c4a-8b1a-2b1a0b1a0b1a", "outputs": {}, "resources": []}

LOCK /api/v1/:project

Locks the statefile.

curl -X LOCK https://worker.example.com/api/v1/example -u username:password

Example response - state locked

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

Example response - state already locked

HTTP/1.1 423 Locked
Content-Type: application/json
Cache-Control: no-store
{"id": "e2b0f0e0-7f1a-4c4a-8b1a-2b1a0b1a0b1a", "operation": "lock", "who": "username", "created": "2020-05-01T00:00:00Z"}

UNLOCK /api/v1/:project

Unlocks the statefile.

Example response - state unlocked

HTTP/1.1 200 OK
Cache-Control: no-store

DELETE /api/v1/:project

Deletes the statefile.

Example response - state deleted

HTTP/1.1 200 OK
Cache-Control: no-store

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

worker-tfstate's Issues

Make expiring state locks

Sometimes the state lock can be forgotten if for example CTRL+C is pressed during a run or if an error occurs

https://developers.cloudflare.com/workers/runtime-apis/kv#expiring-keys

V2 API

For V2 api looking to add several enhancements.

• Ability to generate per project username/passwords
• Ability to generate readonly project credentials for local dev (can get state but can't lock/unlock/update/delete)
• Removal of /:project from the api to be replaced by per-project usernames

KV is not durable

I will need to implement a solution for updates to a KV value during the TTL of the record as it can lead to the lock having no effect if the update occurs to quickly.

An example is where I wrote script to import the state of 40 objects however only half the records made it to the final state due to the TTL