> ## Documentation Index
> Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform Stack

> Automate Terraform and OpenTofu workflows with git-driven deployments and managed state.

**Type:** `rvn-stack` · **Latest version:** `1.2.4`

## Readme

Automate Terraform and OpenTofu workflows with git-driven deployments and managed state.

### Overview

A Stack represents a single Terraform or OpenTofu project connected to a git repository. Ravion monitors your repository for changes and automatically executes infrastructure workflows when code is pushed or pull requests are opened.

Stacks provide:

* **Automated plan/apply** on git push to your primary branch or via pull requests
* **Manual execution** for ad-hoc plans, applies, and destroys on the primary branch
* **Managed state backend** (optional) for configurations that declare an empty `cloud {}` block

### Use cases

| Scenario                         | Stack helps by...                                 |
| -------------------------------- | ------------------------------------------------- |
| Deploying cloud infrastructure   | Running plan/apply when you push changes          |
| Reviewing infrastructure changes | Running plans from pull requests before merge     |
| Managing multiple environments   | Creating separate stacks per environment          |
| Team collaboration               | Centralizing execution with audit trails          |
| Drift detection                  | Running manual plans to compare state vs. reality |

### Workflow types

#### Git-triggered workflows

Ravion automatically responds to repository events:

| Event                  | Action                 |
| ---------------------- | ---------------------- |
| Push to primary branch | Plan → Approve → Apply |
| Pull request opened    | Plan → Approve → Apply |
| Pull request updated   | Plan → Approve → Apply |

**Watch paths** control which file changes trigger workflows. By default, any file change (`**/*`) triggers a run. Configure specific paths or patterns to limit triggers to relevant files.

#### Manual workflows

Execute workflows on-demand from the Ravion dashboard or API:

| Action  | Description                                      |
| ------- | ------------------------------------------------ |
| Plan    | Preview changes without modifying infrastructure |
| Apply   | Execute the most recent plan                     |
| Destroy | Remove all resources managed by this stack       |

### Pipeline integration

Stacks execute using your organization's **default pipelines**. Pipelines are configured separately and define:

* Execution steps (init, plan, apply)
* Approval requirements (default pipelines require manual approval before apply)
* Environment and runner settings
* Pre/post hooks

When you create a Stack, it automatically inherits the default change pipeline (for plan/apply) and destroy pipeline. This ensures consistent workflow behavior across all stacks in your organization.

### Configuration

| Source Code Fields | Required | Description                                            |
| ------------------ | -------- | ------------------------------------------------------ |
| Git repository     | Yes      | Repository containing your Terraform/OpenTofu files    |
| Primary branch     | Yes      | Branch that triggers apply workflows (default: `main`) |
| Base path          | No       | Subdirectory containing `.tf` files                    |
| Watch paths        | No       | Glob patterns controlling which changes trigger runs   |

| Stack Fields          | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| Terraform variables   | Key/value pairs passed as `-var` flags to Terraform/OpenTofu                                    |
| Environment variables | Available during workflow execution; supports `from_parameter_store` and `from_secrets_manager` |

| Iac Fields           | Description                                                                    |
| -------------------- | ------------------------------------------------------------------------------ |
| Infrastructure tool  | Terraform or OpenTofu                                                          |
| Version              | Specific tool version to use                                                   |
| Ravion state backend | Enable managed state storage for configurations with an empty `cloud {}` block |

### State management

Terraform and OpenTofu track infrastructure in a state file. Ravion offers two options:

* **Managed state (default):** Ravion stores and manages your state file. Add an empty `cloud {}` block to your Terraform configuration; Ravion supplies the workspace configuration at runtime.
* **Self-managed state:** Disable the Ravion backend and configure your own (S3, GCS, Azure Storage, etc.) in your Terraform configuration.

For Ravion-managed state, include:

```hcl theme={null}
terraform {
  cloud {}
}
```

### Terraform vs OpenTofu

**OpenTofu is recommended.** In 2023, HashiCorp changed Terraform's license from open-source to BSL. The open-source Terraform versions are limited to \< 1.6.0. OpenTofu is the community fork that continues active development under a true open-source license (MPL 2.0).

### Learn more

[Curated list of Terraform resources and learning material](https://github.com/shuaibiyy/awesome-tf)

**OpenTofu**

* [OpenTofu Documentation](https://opentofu.org/docs/) — Official docs
* [Getting Started](https://opentofu.org/docs/intro/) — Installation and first steps
* [Migration from Terraform](https://opentofu.org/docs/intro/migration/) — Switching guide

**Terraform** (limited to \< 1.6.0)

* [HashiCorp Developer Docs](https://developer.hashicorp.com/terraform/docs) — Official documentation
* [Terraform Tutorials](https://developer.hashicorp.com/terraform/tutorials) — Hands-on learning

## Inputs reference

All inputs for `rvn-stack` version `1.2.4`. Use the `name` shown for each field as the input key in module config.

### Where to run Terraform plan & apply

<ResponseField name="aws_account_id" type="string" required>
  **AWS Account.** Where to execute the Terraform plan & apply steps

  * Shown when: `{"default_networking":true}`
</ResponseField>

<ResponseField name="default_networking" type="boolean">
  **Use default VPC, subnet and security group.**

  * Default: `true`
</ResponseField>

<ResponseField name="aws_region" type="string" required>
  **Region.** Where to execute the Terraform plan & apply steps

  * Shown when: `{"default_networking":true}`
</ResponseField>

<ResponseField name="execution_environment_id" type="string">
  **Execution environment.** Specify the VPC, subnet, and security group for Pipeline Terraform runners. Defaults to the Environment's default Execution Environment

  * Shown when: `{"default_networking":false}`
</ResponseField>

### Source code

<ResponseField name="repo" type="gitrepo" required>
  **Git repository.**
</ResponseField>

<ResponseField name="primary_branch" type="string" required>
  **Primary branch.**

  * Default: `main`
</ResponseField>

<ResponseField name="base_path" type="string">
  **Base path.** Folder containing your Terraform files (relative to repo root)
</ResponseField>

<ResponseField name="watch_paths" type="string_array">
  **Watch paths.** File paths glob patterns (e.g., `src/**`) that trigger a pipeline run when changed. Defaults to `**`

  * Default: `["<<module.input.base_path>>/**"]`
</ResponseField>

### Stack inputs

<ResponseField name="terraform_variable_files" type="string_array">
  **Terraform variable files.** Relative paths from base path to `.tfvars` or `.tfvars.json` files (equivalent to -var-file flags)
</ResponseField>

<ResponseField name="tf_variables" type="object">
  **Terraform variables.** Variables passed to Terraform/OpenTofu (equivalent to -var flags)
</ResponseField>

<ResponseField name="env_variables" type="object">
  **Environment variables.**
</ResponseField>

### IaC tool

<ResponseField name="tool" type="string" required>
  **Tool.** Terraform is no longer free open source. OpenTofu is the popular community fork with full Terraform compatibility.

  * Default: `opentofu`
  * Allowed values: `opentofu` (OpenTofu (Recommended)), `terraform` (Terraform (FOSS, limited \< v1.6.0))
</ResponseField>

<ResponseField name="terraform_version" type="string" required>
  **Terraform version.**

  * Default: `$values:first`
  * Shown when: `{"tool":"terraform"}`
</ResponseField>

<ResponseField name="opentofu_version" type="string" required>
  **OpenTofu version.**

  * Default: `$values:first`
  * Shown when: `{"tool":"opentofu"}`
</ResponseField>

<ResponseField name="use_ravion_state_backend" type="boolean">
  **Use Ravion for your Terraform state.** Use Ravion-managed state. Your Terraform configuration must include an empty `terraform { cloud {} }` block; Ravion supplies the workspace configuration. Disable to use your own backend, including S3 or Terraform Cloud.

  * Default: `true`
  * Immutable after creation
</ResponseField>

<ResponseField name="ravion_state_backend_workspace" type="string">
  **Ravion Terraform workspace name.** Override Terraform state backend workspace name. Defaults to project + environment + module given ids.

  * Immutable after creation
  * Shown when: `{"use_ravion_state_backend":true}`
</ResponseField>