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

# Provision Stacks with Terraform

> Provision the Nuon install stacks with Terraform.

Nuon supports provisioning install stacks using Terraform. We maintain a collection of [open-source terraform modules](https://github.com/nuonco/install-stacks) that can be used directly, or forked and customized.

## How it works

Provisioning with Terraform is a hand-off between you and your customer:

1. You create the install. The install workflow pauses at the **await install stack** step.
2. On that step, you copy or download the generated `inputs.auto.tfvars` and `secrets.auto.tfvars`.
3. You send them to your customer.
4. Your customer clones the install stack module and applies it in their cloud account.
5. The stack boots up the runner. Once the runner connects, the await install stack step completes.

## Prerequisites

Your customer will need the following in order to apply the stack.

* The [Terraform](https://developer.hashicorp.com/terraform/install) CLI installed, or set up in their chosen automation platform.
* Credentials for the target cloud account, so Terraform can provision resources.
* Outbound network access to the Terraform Registry (to install the `nuonco/stack` provider) and to the Nuon API (so the provider can fetch the stack configuration at apply time).

## Provisioning the stack

Follow these steps to provision a stack using Terraform.

<Steps>
  <Step title="Create an install">
    Create an install as you usually would, and wait for the provision workflow to get to the **await install stack** step.
  </Step>

  <Step title="Send your customer the files">
    On the **await install stack** step, copy or download `inputs.auto.tfvars` and `secrets.auto.tfvars`, then send
    them to your customer.

    The remaining steps are for your customer.
  </Step>

  <Step title="Clone the install stack module">
    Clone the repo and enter the directory for your cloud (`aws` or `gcp`):

    ```bash theme={null}
    git clone https://github.com/nuonco/install-stacks.git
    cd install-stacks/<cloud>
    ```
  </Step>

  <Step title="Configure remote state (recommended)">
    If you have not already, set up a state store and configure it as a remote backend.
    See the [Terraform backend docs](https://developer.hashicorp.com/terraform/language/settings/backends/configuration) for details.

    If you do not have a dedicated terraform state store, you can store the state in the cloud account alongside the stack.

    <CodeGroup>
      ```hcl AWS (S3) theme={null}
      terraform {
        backend "s3" {
          bucket = "<your-state-bucket>"
          key    = "nuon/<install-id>/terraform.tfstate"
          region = "<your-state-bucket-region>"
        }
      }
      ```

      ```hcl GCP (GCS) theme={null}
      terraform {
        backend "gcs" {
          bucket = "<your-state-bucket>"
          prefix = "nuon/<install-id>"
        }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure the install">
    The `inputs.auto.tfvars` file can be stored in version control alongside the terraform module.
    It can also be stored in the environment configuration of your chosen automation platform.

    `secrets.auto.tfvars` should be stored separately as a secret value.
    Alternatively, the secret values can be saved in a secret store and passed to terraform as environment variables.
  </Step>

  <Step title="Provision the stack">
    Initialize the terraform workspace and apply.

    ```bash theme={null}
    terraform init && terraform apply
    ```

    This will provision the Nuon stack.
    Once the runner phones home, the await install stack step in Nuon will complete.
  </Step>
</Steps>