terraflex

Construct custom backends for your terraform project!

why?

I started this project to provide a free solution for homelabs IAC.
The major constraint here is to find a free backend that I feel safe to use and to have a 0 bootstrap layer if possible.
I found several solutions around this - but most were using a 3rd party hosted http backend servers.
Those backends were problematic for me because I had issues trusting them to store my sensitive state files - and the fact that I didn't own the storage location - made me afraid that I might lose those state files - and we all know how bad it is to lose your state files :P.
The closest solution I found was terraform-backend-git - which this project was heavily influenced on - so go check it out as well!
Eventually I had the idea of creating an extendable modular terraform http backend - which allows customizing the state using transformations (like encryption), and getting starting with it will be as simple as running single command.

Documentation

Check out documentations here: docs

Installation

Recommended: Use uv tooling

Install uv (if not already):

curl -Ls https://astral.sh/uv/install.sh | sh

Install terraflex globally using uv tooling (from PyPI):

uv tool install terraflex

Or install the latest version directly from GitHub:

uv tool install git+https://github.com/IamShobe/terraflex.git

Upgrade terraflex:

uv tool upgrade terraflex

To use terraflex in a project with dev dependencies, you can still use:

uv sync -G dev

Getting started

Git backends preparation

• Create new repository to store your state at
• Make sure the repository is initialized with primary branch (main)

Common

• To start - cd to your IAC repo, for example: ~/git/iac
• Run:

  terraflex init
  

  Follow the wizard
• Update your backend:

  backend "http" {
    address = "http://localhost:8600/state"
    lock_address = "http://localhost:8600/lock"
    lock_method = "PUT"
    unlock_address = "http://localhost:8600/lock"
    unlock_method = "DELETE"
  }
  

• Run any terraform command using terraflex wrap -- <command> - for example:

  terraflex wrap -- terraform init
  

• You can also create a full shell with the context of the backend:

  terraflex wrap -- $SHELL
  

Others

• Checkout issues to see roadmap.