Metadata-Version: 2.4
Name: tfrunner
Version: 0.12.0
Summary: A cli tool used to make running terraform or opentofu project simpler. Includes secret fetching and remote state management.
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: doppler-sdk>=1.3.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.3
Requires-Dist: toml>=0.10.2
Requires-Dist: typer>=0.15.1

# Tfrunner

Welcome to `tfrunner`, a `cli` tool to run terraform commands with the following facilities:
- Multi-project support
- Automation support
- Remote backend
- GitLab secrets pulling


## Installation

Since `tfrunner` is a `cli` tool, the recommended installation is using `pipx`.

Please ensure you have a compatible `python >= 3.12` version.

Install with: `pipx install tfrunner`


## Usage

**Requirements**: `tfrunner` expects the following binaries to be installed:
- `terraform`: `tfrunner` is a wrapper on top of `terraform`
- `git`: when using the `--git-sandbox` flag, ensure you have `git` installed and that you are running the command in a `git` project

To use it to manage multiple projects, create a `yaml` file configuring each.

Here is an example file, let's name it `tfrunner.yaml`:
```yaml
flavour: terraform # Can use tofu

state_backend:
  kind: gitlab
  spec:
    url: https://gitlab.com
    project_id: 12345678
    token_var: GITLAB_TOKEN

secrets_backend:
  kind: gitlab
  spec:
    url: https://gitlab.com
    project_id: 12345678
    token_var: GITLAB_TOKEN

tfvars:
  gitlab_token: $GITLAB_TOKEN

projects:
  dev: # Reflects name of the environment
    path: ../infra/dev
    state_name: dev
    # Inner environment gets added (and overrides colliding vars) with global env vars
    # env vars take precedence over secrets
    tfvars:
      doppler_token: $DOPPLER_TOKEN
    # Inner secrets backend takes precendence
    secrets_backend:
      kind: doppler
      spec:
        project: my-project
        config: dev
        token_var: DOPPLER_TOKEN
```

Now you can run `tfrunner` as you would run any regular `terraform` command (options are also included). You need only to be wary of two additional arguments that are needed:
- `--project`: name of your project, as specified in your config file.
- `--config_path`: path to your configuration file. By default it will look for a `tfrunner.yaml` file in the current folder

As examples, for the `great-project` in our example `tfrunner.yaml` file, you could run:
```bash
tfrunner init --project great-project
tfrunner fmt --project great-project
tfrunner validate --project great-project
tfrunner plan --project great-project
tfrunner apply --project great-project
tfrunner destroy --config_path tfrunner.yaml --project great-project
```

The `--config_path` is optional in the `tfrunner destroy` command, as `tfrunner` will by default assume its path to be `tfrunner.yaml`.

## Usage with git-sandboxes

```bash
tfrunner init --project great-project --git-sandbox
tfrunner plan --project great-project --git-sandbox
tfrunner apply --project great-project --git-sandbox
tfrunner destroy --project great-project --git-sandbox
```

## Local development

**Requirements**:
- `uv` installed
- `terraform` installed
- `git` installed

1. Install virtual environment: `uv sync --all-groups`


# TODO:

- Make `tfrunner plan` generate a plan file by default
- Make `tfrunner apply` use that plan file by default
