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

# Quick start: Terraform/OpenTofu

This quick start guide explains how to use Tensor9 to deploy your Terraform/OpenTofu (**TF**) app as a private appliance.

<img src="https://mintcdn.com/tensor9/i99hvSEyeBFodjpK/images/diagrams/terraform-overview-dark.png?fit=max&auto=format&n=i99hvSEyeBFodjpK&q=85&s=109f2c1330b39223d8fb229cd7359be6" className="block dark:hidden" width="2494" height="1408" data-path="images/diagrams/terraform-overview-dark.png" />

<img src="https://mintcdn.com/tensor9/i99hvSEyeBFodjpK/images/diagrams/terraform-overview-light.png?fit=max&auto=format&n=i99hvSEyeBFodjpK&q=85&s=ab5b114fe11ec07e7e97d1025fc55f10" className="hidden dark:block" width="2492" height="1392" data-path="images/diagrams/terraform-overview-light.png" />

As you follow this guide, you will:

* Set up a Tensor9 control plane in your AWS account and bind a TF workspace as the origin stack for your app.
* Test your app running in an appliance.
* Release infrastructure changes.

## Prerequisites

* Send an email to [hello@tensor9.com](mailto:hello@tensor9.com) and request an API key. You must have an API key to complete the quick start.
* Create an AWS account for Tensor9. We will refer to this as the Tensor9 AWS account.

  **Important:**

  * Your Tensor9 AWS account should be a dedicated AWS account used only for Tensor9. This reduces the risk of conflicts between your app deployed in a Tensor9 appliance and any other software, infrastructure, or resources you might have in a general-purpose AWS account.
  * Your Tensor9 AWS account must be located in a United States region. Support for non-US regions will be available in the near future.
* Install [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in your environment, and [set up an AWS CLI profile](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html) that has admin permissions to your new AWS account.

## Install OpenTofu or Terraform

In your environment, you'll need to install Terraform/OpenTofu CLI.

This guide assumes you are using OpenTofu and uses the `tofu` command throughout.

## Install Tensor9 CLI

Install the **tensor9** CLI via Homebrew (recommended):

```bash theme={null}
brew tap tensor9ine/tensor9
brew install tensor9
```

Alternatively, install via the install script:

```bash theme={null}
curl -sSL https://t9-artifacts-prod-1.s3.us-west-2.amazonaws.com/install-latest.sh | sh
```

Then set your Tensor9 API key:

```bash theme={null}
export T9_API_KEY=<YOUR_API_KEY>
```

**Note:** An API key is required. If you do not have an API key, send email to [hello@tensor9.com](mailto:hello@tensor9.com) to request one.

## Set up a Tensor9 control plane and create a new app

1. Set up a Tensor9 control plane in your new AWS account (this takes several minutes to complete):

```bash theme={null}
tensor9 vendor setup \
  -cloud aws \
  -region <YOUR-REGION> \
  -awsProfile <YOUR_AWS_CLI_PROFILE>
```

2. Create a new Tensor9 **app**.

```bash theme={null}
tensor9 app create -name tofu-quickstart -displayName "Tofu example app"
```

**Note:** The length of the `displayName` field must be 32 characters or fewer.

## Publish your TF and bind it to your new app

Tensor9 works by compiling your TF for each appliance your want to deploy to.  So, your next step is to **publish** your TF to your Tensor9 control plane:

```bash theme={null}
tensor9 stack publish \
  -stackType TerraformWorkspace \
  -stackS3Key your-stack \
  -dir <PATH_TO_YOUR_TF_ROOT>
```

This will return a **native stack id**, which will will look something like this:

`s3://t9-ctrl-000001/your-stack.tf.tgz`

The next step is to **bind** your published stack to your app:

```bash theme={null}
tensor9 stack bind \
  -appName tofu-quickstart \
  -stackType TerraformWorkspace \
  -nativeStackId <YOUR_NATIVE_STACK_ID>
```

This registers your stack with your app so that you can release your app/stack combination to appliances.  In the future, you can publish new versions of your stack (using the tensor9 stack publish command) without having to bind the app again.

## Create a test appliance and test your app

1. Create a test appliance:

```bash theme={null}
tensor9 test appliance create \
  -appName tofu-quickstart \
  -name tofu-quickstart-test
```

2. View the output of `tensor9 report` to determine when your test appliance is ready for a release. While the test appliance is creating, `tensor9 report` displays output such as:

<Frame>
  <img src="https://mintcdn.com/tensor9/cgNtbQ3izn4fO5B3/images/screenshots/appliance-create-inprogress-tf.png?fit=max&auto=format&n=cgNtbQ3izn4fO5B3&q=85&s=9f14c08d305a9578a8c7a65adccca473" width="1909" height="221" data-path="images/screenshots/appliance-create-inprogress-tf.png" />
</Frame>

When the appliance is ready, `tensor9 report` displays output such as:

<Frame>
  <img src="https://mintcdn.com/tensor9/cgNtbQ3izn4fO5B3/images/screenshots/appliance-create-complete-tf.png?fit=max&auto=format&n=cgNtbQ3izn4fO5B3&q=85&s=631e1754e02d1e2e63fe9f88e5655694" width="1818" height="1637" data-path="images/screenshots/appliance-create-complete-tf.png" />
</Frame>

3. Create a release to your test appliance:

```bash theme={null}
tensor9 stack release create \
  -appName tofu-quickstart \
  -testApplianceName tofu-quickstart-test \
  -vendorVersion "1.0.0" \
  -description "First release of my origin stack via Tensor9" \
  -notes "By engineer@vendor.co"
```

After a few minutes, the workspace bundle for your TF root module downloads into a new directory that is named after your appliance.

4. Change into the new directory that contains the deployment stack for your test appliance:

```bash theme={null}
cd tofu-quickstart-test
```

5. Deploy as normal by running `tofu init` followed by `tofu apply`.
6. Run `tofu show` to review the resulting created resources.

## Release an infrastructure change

You can release infrastructure changes to your stack at any time.

1. Update your origin stack with any desired change. For example, you could enable versioning on the AWS S3 bucket that was created when initially publishing your origin stack.

**Important:** The next step will overwrite the previous origin stack. All new releases will come from the most recently published version of your origin stack.

2. **Re-publish** the origin stack to Tensor9:

```bash theme={null}
tensor9 stack publish \
  -stackType TerraformWorkspace \
  -stackS3Key your-stack \
  -dir <PATH_TO_YOUR_TF_ROOT>
```

If the origin stack is published successfully, the following message is displayed:

```bash theme={null}
Your origin stack is ready to be released.  Use the following native stack id [stack ID URL]
```

Your native stack id is displayed. You will need this stack id in the next step.

3. Create a new release:

```bash theme={null}
tensor9 stack release create \
  -appName tofu-quickstart \
  -testApplianceName tofu-quickstart-test \
  -vendorVersion "1.0.1" \
  -description "Turning on versioning for the main bucket" \
  -notes "By engineer@vendor.co"
```

After a few minutes, the workspace bundle for your TF stack downloads into a new directory that is named after your app.

4. Change into the new directory that contains the deployment stack for your test appliance:

```bash theme={null}
cd tofu-quickstart-test
```

5. Deploy as normal by running `tofu init` followed by `tofu apply`.
6. Run `tofu show` to review the resulting created resources.