Quick start: Terraform/OpenTofu

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

As you follow this guide, you will:

Set up a Tensor9 BYOC 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 [email protected] and request an API key. You must have an API key to complete the quick start.
Create an AWS account for Tensor9 BYOC. We will refer to this as the Tensor9 BYOC AWS account. Important:
- Your Tensor9 BYOC AWS account should be a dedicated AWS account used only for Tensor9 BYOC. This reduces the risk of conflicts between your app deployed in a Tensor9 BYOC appliance and any other software, infrastructure, or resources you might have in a general-purpose AWS account.
- Your Tensor9 BYOC 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 in your environment, and set up an AWS CLI profile 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):

brew tap tensor9ine/tensor9
brew trust tensor9ine/tensor9
brew install tensor9

Alternatively, install via the install script:

curl -sSL https://t9-artifacts-prod-1.s3.us-west-2.amazonaws.com/install-latest.sh | sh

Then authenticate the CLI: A Tensor9 API key is required. Use the key issued during onboarding, or email [email protected] to request one for your organization. Do not share your account or key with another customer or organization. If your secret manager has already supplied T9_API_KEY, skip the prompt. Otherwise, enter your key at a hidden prompt in the terminal where you will run tensor9:

Bash
Zsh

set +x
IFS= read -r -s -p 'Tensor9 API key: ' T9_API_KEY
printf '\n'
export T9_API_KEY

set +x
IFS= read -r -s 'T9_API_KEY?Tensor9 API key: '
printf '\n'
export T9_API_KEY

Check that the variable is set without printing it, then verify your Tensor9 identity:

: "${T9_API_KEY:?Set T9_API_KEY before continuing}"
tensor9 whoami

Confirm that the reported identity belongs to the intended customer account. Do not continue if authentication fails or the account is wrong. Keep shell tracing disabled while using the key. Do not paste the key into commands, shell profiles, source files, screenshots or support messages.

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

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

tensor9 vendor setup \
  -cloud aws \
  -region <YOUR-REGION> \
  -awsProfile <YOUR_AWS_CLI_PROFILE>

Create a new Tensor9 BYOC app.

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 BYOC 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 BYOC control plane:

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:

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

Create a test appliance:

tensor9 test appliance create \
  -appName tofu-quickstart \
  -name tofu-quickstart-test

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:

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

Create a release to your test appliance:

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 [email protected]"

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

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

cd tofu-quickstart-test

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

Debug a service-adapter request in the test appliance

If the deployed application uses an origin-cloud API through a service adapter, make the test appliance your first debugging environment. Record the app, test appliance, release, selected service mapping and operation, then follow Debugging Service Adapters. Inspect the directed profile before sending another request, and use a hypothetical explanation where the selected operation supports it. Do not repeat a mutating request until you have checked whether the first request changed the target resource.

Release an infrastructure change

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

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.

Re-publish the origin stack to Tensor9 BYOC:

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:

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.

Create a new release:

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 [email protected]"

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

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

cd tofu-quickstart-test

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

Tensor9 BYOC

Getting Started

How It Works

Deploying

Your Customer's Environment

Service Adapters

Auto-Customizations

Security

Connectivity & Networking

Observability & Operations

Support

tensor9 CLI

Quick start: Terraform/OpenTofu

Prerequisites

Install OpenTofu or Terraform

Install Tensor9 CLI

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

Publish your TF and bind it to your new app

Create a test appliance and test your app

Debug a service-adapter request in the test appliance

Release an infrastructure change

​Prerequisites

​Install OpenTofu or Terraform

​Install Tensor9 CLI

​Set up a Tensor9 BYOC control plane and create a new app

​Publish your TF and bind it to your new app

​Create a test appliance and test your app

​Debug a service-adapter request in the test appliance

​Release an infrastructure change

Prerequisites

Install OpenTofu or Terraform

Install Tensor9 CLI

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

Publish your TF and bind it to your new app

Create a test appliance and test your app

Debug a service-adapter request in the test appliance

Release an infrastructure change