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:

Create your Tensor9 account and set up a Tensor9 BYOC control plane in your AWS account.
Create an app and bind a TF workspace as its origin stack.
Onboard a customer and release your app to their appliance.
Release infrastructure changes.

Prerequisites

A Google account to sign up for Tensor9.
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.
- Tensor9 BYOC sets up your control plane in the AWS us-west-2 (US West, Oregon) region. Other regions are not available yet.
Install AWS CLI in your environment, and set up an AWS CLI profile that has admin permissions to your new AWS account. This guide calls it my-vendor-aws.
A second AWS account to act as your first customer. You will open the customer setup link while signed in to this 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.

Create your account and control plane

Follow Get a Tensor9 API key to sign up and install the tensor9 CLI.
Export your API key and set up your control plane in your new AWS account (about 10 minutes):

export T9_API_KEY=<your API key>
tensor9 vendor setup -awsProfile my-vendor-aws

Add -region us-west-2 if your AWS configuration defaults to another region. Setup makes its controller profile your CLI default, so the commands below need no API key or profile options.

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 you want to deploy to. So, your next step is to publish your TF to your Tensor9 BYOC control plane and bind it to your app. tensor9 stack publish-direct does both in one step:

tensor9 stack publish-direct \
  -appName tofu-quickstart \
  -stackType TerraformWorkspace \
  -stackName your-stack \
  -dir <PATH_TO_YOUR_TF_ROOT>

The command bundles the .tf files in -dir, uploads them through your control plane and binds the stack to tofu-quickstart under the name your-stack. It authenticates with your controller profile, so it needs no AWS credentials. When it finishes, it prints a summary such as:

Published stack:
    name:       your-stack
    id:         <STACK_ID>
    bound:      yes
    app stacks: 1

This registers your stack with your app so that you can release your app/stack combination to appliances. When you publish again with the same -stackName, the command updates the stack and keeps the existing binding.

Onboard a customer

Customers install your app in their own cloud accounts through a setup link. In this guide, your second AWS account acts as the customer.

Create a form factor that lets customers install your app in AWS:

tensor9 form-factor create \
  -appName tofu-quickstart \
  -formFactorName aws-connected \
  -env Aws \
  -connectivity Connected

Create a setup link for your customer:

tensor9 app setup -appName tofu-quickstart -customerName acme-corp

The command creates the customer acme-corp if it does not exist yet and prints the customer’s setup link.

Sign in to the AWS console of your customer AWS account, then open the setup link in the same browser. Follow the setup wizard to choose the environment, then download and apply the infrastructure templates in the customer account. The customer installation guide describes each step.
View the output of tensor9 report to determine when the customer’s appliance is ready for a release. While the appliance is creating, tensor9 report displays output such as:

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

Release to your customer

Create a release for your customer:

tensor9 stack release create \
  -appName tofu-quickstart \
  -customerName acme-corp \
  -vendorVersion "1.0.0" \
  -description "First release of my origin stack via Tensor9" \
  -notes "By [email protected]"

The release compiles your stack for the customer’s appliance and downloads its deployment stack into <APPLIANCE_NAME>/your-stack/, using the appliance name and the -stackName you published with. The release output prints the directory.

Change into the new directory that contains the deployment stack for your customer’s appliance:

cd <APPLIANCE_NAME>/your-stack

Deploy as normal by running tofu init followed by tofu apply.

The tensor9 provider in the deployment stack authenticates with your Tensor9 API key, which it reads from the T9_API_KEY environment variable. In the workspace directory, enter the key at a hidden prompt, apply the stack, then unset the variable:

Bash
Zsh

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

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

Use the API key you downloaded from sandbox.tensor9.com. Unset T9_API_KEY as soon as the apply finishes: while it is set, tensor9 CLI commands use the key instead of your controller profile. Do not put the key in a command, a shell profile or a source file.

Run tofu show to review the resulting created resources.

Debug a service-adapter request in the customer appliance

If the deployed application uses an origin-cloud API through a service adapter, record the app, 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, with the same -stackName:

tensor9 stack publish-direct \
  -appName tofu-quickstart \
  -stackType TerraformWorkspace \
  -stackName your-stack \
  -dir <PATH_TO_YOUR_TF_ROOT>

The command reports that the stack is already bound to your app, so you do not need to bind it again.

Create a new release:

tensor9 stack release create \
  -appName tofu-quickstart \
  -customerName acme-corp \
  -vendorVersion "1.0.1" \
  -description "Turning on versioning for the main bucket" \
  -notes "By [email protected]"

The updated deployment stack downloads into <APPLIANCE_NAME>/your-stack/. Run the commands below from the directory where you created the release.

Change into the directory that contains the deployment stack for your customer’s appliance:

cd <APPLIANCE_NAME>/your-stack

Deploy as normal by running tofu init followed by tofu apply, with your API key in T9_API_KEY for this step only, as in the first release:

Bash
Zsh

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

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

Run tofu show to review the resulting created resources.

Clean up

When you finish with this guide, remove what you created. You can do the following yourself today:

Remove the resources that your release deployed in the customer’s appliance. From the directory that contains the deployment stack, <APPLIANCE_NAME>/your-stack, run tofu destroy with your API key in T9_API_KEY for this step only:

Bash
Zsh

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

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

Review the plan that tofu destroy shows before you confirm it. Unset T9_API_KEY as soon as the command finishes, so that tensor9 commands keep using your controller profile.

Unbind the stack from your app, so that no new releases are made from it:

tensor9 stack unbind -appName tofu-quickstart -stackName your-stack

Unbinding does not remove anything already deployed, which is why you destroy the deployment first. Some steps currently need Tensor9 support. To remove the customer’s appliance or to remove your control plane from your AWS account, email [email protected] with your vendor ID, which tensor9 whoami reports, and the app and customer names. Do not delete control plane resources from your AWS account by hand.

Tensor9 BYOC

Getting Started

Self-Service Onboarding

How It Works

Deploying

Your Customer's Environment

Service Adapters

Costs

Auto-Customizations

Security

Connectivity & Networking

Observability & Operations

Support

tensor9 CLI

Quick start: Terraform/OpenTofu

Prerequisites

Install OpenTofu or Terraform

Create your account and control plane

Publish your TF and bind it to your new app

Onboard a customer

Release to your customer

Debug a service-adapter request in the customer appliance

Release an infrastructure change

Clean up

​Prerequisites

​Install OpenTofu or Terraform

​Create your account and control plane

​Publish your TF and bind it to your new app

​Onboard a customer

​Release to your customer

​Debug a service-adapter request in the customer appliance

​Release an infrastructure change

​Clean up

Prerequisites

Install OpenTofu or Terraform

Create your account and control plane

Publish your TF and bind it to your new app

Onboard a customer

Release to your customer

Debug a service-adapter request in the customer appliance

Release an infrastructure change

Clean up