Common Workflows

This guide shows common workflows for using the tensor9 CLI to manage your apps, stacks, and appliances.

Prerequisites

Before starting, ensure you have:

Installed the tensor9 CLI
Set your API key: export T9_API_KEY=<your-key>
Configured AWS credentials for your Tensor9 AWS account

Initial setup workflow

Set up Tensor9 in your AWS account for the first time.

Set up your control plane

Run the interactive setup:

tensor9 vendor setup

Or provide all parameters:

tensor9 vendor setup \
  -cloud aws \
  -region us-west-2 \
  -awsProfile my-tensor9-profile

This creates your Tensor9 control plane in your AWS account. It takes several minutes to complete.

Verify setup

Check that your control plane is ready:

tensor9 report

You should see your vendor information displayed.

Create your first app

tensor9 app create \
  -name my-app \
  -displayName "My Application"

Your app is now created and ready to have a stack bound to it.

Publish and bind your origin stack

Publish an origin stack and bind it to your app.

For Terraform stacks

Publish your Terraform stack

From your Terraform workspace directory:

tensor9 stack publish \
  -stackType TerraformWorkspace \
  -stackS3Key my-app-stack \
  -dir .

This uploads your Terraform files and returns a native stack ID like:

s3://t9-ctrl-000001/terraform-stacks/origins/my-app-stack.tf.tgz

Bind the stack to your app

tensor9 stack bind \
  -appName my-app \
  -stackType TerraformWorkspace \
  -nativeStackId "s3://t9-ctrl-000001/terraform-stacks/origins/my-app-stack.tf.tgz"

Your stack is now bound to your app.

For Docker container stacks

Push your container image to ECR

First, authenticate to your Tensor9 AWS account’s ECR:

aws ecr get-login-password --region us-west-2 --profile my-tensor9-profile | \
  docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-west-2.amazonaws.com

Tag and push your image:

docker tag my-app:latest <account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest
docker push <account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

The native stack ID is the image URI:

<account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

Bind the container to your app

tensor9 stack bind \
  -appName my-app \
  -stackType DockerContainer \
  -nativeStackId "<account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest"

Your container is now bound to your app.

For Docker Compose stacks

Before publishing your Docker Compose file, ensure all container images referenced in your compose file are pushed to their registries (ECR, Docker Hub, etc.). These images must be available when you create a release.

Publish your Docker Compose file

tensor9 stack publish \
  -stackType DockerCompose \
  -stackS3Key my-app-compose \
  -file docker-compose.yml

Returns a native stack ID like:

s3://t9-ctrl-000001/my-app-compose.yml

Bind the stack to your app

tensor9 stack bind \
  -appName my-app \
  -stackType DockerCompose \
  -nativeStackId "s3://t9-ctrl-000001/my-app-compose.yml"

For CloudFormation stacks

Deploy your CloudFormation stack

Deploy your CloudFormation stack using the AWS CLI:

aws cloudformation create-stack \
  --stack-name my-app-stack \
  --template-body file://template.yaml \
  --region us-west-2 \
  --profile my-tensor9-profile

Get the stack ARN

aws cloudformation describe-stacks \
  --stack-name my-app-stack \
  --region us-west-2 \
  --query 'Stacks[0].StackId' \
  --output text

This returns an ARN like:

arn:aws:cloudformation:us-west-2:123456789012:stack/my-app-stack/a1b2c3d4

Bind the CloudFormation stack

tensor9 stack bind \
  -appName my-app \
  -stackType CloudFormation \
  -nativeStackId "arn:aws:cloudformation:us-west-2:123456789012:stack/my-app-stack/a1b2c3d4"

Create a test appliance

Create a test appliance for testing your releases before deploying to customers.

Create a test appliance

tensor9 test appliance create \
  -appName my-app \
  -name my-test-appliance

The test appliance will be created asynchronously.

Monitor appliance creation

Check the status periodically:

tensor9 report

Wait until the test appliance status shows “Live”. This typically takes 10-15 minutes.

Deploy to a test appliance

Deploy your stack to a test appliance to verify it works before releasing to customers.

Create a release

Create a release for your test appliance:

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-test-appliance \
  -vendorVersion "1.0.0" \
  -description "Initial release" \
  -notes "First production release"

After a few minutes, the deployment stack downloads to a directory named my-test-appliance.

Deploy the release

cd my-test-appliance
tofu init
tofu apply

Your application is now deployed in the test appliance.

Verify the deployment

Check the deployed resources:

kubectl get deployments
kubectl get services
kubectl get pods

For services with external ports, get the load balancer endpoint:

kubectl get service <service-name> -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

Access your application through the load balancer URL.

Create a customer appliance

Enable your customer to create an appliance for your app in their environment.

Generate signup link

Generate a signup link for your customer:

tensor9 app signup-link -appName my-app

Send the generated URL to your customer. They’ll use it to create their appliance.

Customer creates appliance

The customer uses the signup link to:

Sign up and create their organization (if they haven’t already)
Select their cloud provider and region
Complete the setup to create their appliance

Their appliance will be provisioned automatically in their cloud account.

Monitor appliance creation

Check when the customer’s appliance is ready:

tensor9 report

Wait until their appliance status shows “Live”.

Create a release for the customer

Once their appliance is ready:

tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.0.0" \
  -description "Initial deployment for Acme Corp" \
  -notes "Configured for production use"

The deployment stack downloads to a directory named after their appliance.

Deploy to the customer's appliance

Deploy the release to the customer’s appliance:

cd acme-corp-appliance
tofu init
tofu apply

This deploys your application into the customer’s appliance.

Release to a customer appliance

Release infrastructure or code changes to your customer appliances.

Update your origin stack

Make changes to your Terraform files, docker-compose.yml, or CloudFormation template.

Republish the stack

For Terraform:

tensor9 stack publish \
  -stackType TerraformWorkspace \
  -stackS3Key my-app-stack \
  -dir .

For Docker Compose:

tensor9 stack publish \
  -stackType DockerCompose \
  -stackS3Key my-app-compose \
  -file docker-compose.yml

For CloudFormation:

aws cloudformation update-stack \
  --stack-name my-app-stack \
  --template-body file://template.yaml

You don’t need to re-bind the stack. Tensor9 will use the updated version for new releases.

Test in test appliance

Create a release to your test appliance:

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-test-appliance \
  -vendorVersion "1.1.0" \
  -description "Added new features" \
  -notes "Added caching layer and API improvements"

Deploy and verify

cd my-test-appliance
tofu apply

Verify the changes work as expected.

Release to customers

After testing, release to your customers:

# Release to specific customer
tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.1.0" \
  -description "Feature update" \
  -notes "New caching layer and performance improvements"

# Or release to all customers
tensor9 stack release create \
  -appName my-app \
  -all \
  -vendorVersion "1.1.0" \
  -description "Feature update" \
  -notes "New caching layer and performance improvements"

Manage multiple form factors

Deploy your app to different cloud providers or connectivity modes.

Create form factors

Create form factors for different environments:

# AWS connected
tensor9 form-factor create \
  -appName my-app \
  -formFactorName aws-connected \
  -description "AWS with internet connectivity" \
  -env Aws \
  -connectivity Connected

# GCP connected
tensor9 form-factor create \
  -appName my-app \
  -formFactorName gcp-connected \
  -description "Google Cloud with internet connectivity" \
  -env Gcp \
  -connectivity Connected

# DigitalOcean connected
tensor9 form-factor create \
  -appName my-app \
  -formFactorName digitalocean-connected \
  -description "DigitalOcean with internet connectivity" \
  -env DigitalOcean \
  -connectivity Connected

Test each form factor

Create test appliances for each form factor:

tensor9 test appliance create \
  -appName my-app \
  -name my-aws-test \
  -formFactorName aws-connected

tensor9 test appliance create \
  -appName my-app \
  -name my-gcp-test \
  -formFactorName gcp-connected \
  -cloudRegion gcp:us-central1

Release to each test appliance

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-aws-test \
  -vendorVersion "1.0.0" \
  -description "AWS test" \
  -notes "Testing AWS deployment"

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-gcp-test \
  -vendorVersion "1.0.0" \
  -description "GCP test" \
  -notes "Testing GCP deployment"

Use stack tuning documents

Customize resource allocations per customer or environment.

Create a tuning document

Create a JSON file with resource overrides:

{
  "version": "V1",
  "composeServices": {
    "web": {
      "replicas": 4,
      "resources": {
        "cpu": "2",
        "memory": "4Gi"
      }
    },
    "api": {
      "replicas": 3,
      "resources": {
        "cpu": "1",
        "memory": "2Gi"
      }
    }
  }
}

Save as enterprise-tuning.json.

Release with tuning document

tensor9 stack release create \
  -appName my-app \
  -customerName enterprise-customer \
  -vendorVersion "1.0.0" \
  -description "Enterprise deployment" \
  -notes "High-performance configuration" \
  -tuningDoc enterprise-tuning.json

The deployment stack will use the tuned resource specifications.

Monitor appliances

Check the status of your apps, appliances, and releases.

View comprehensive report

tensor9 report

This shows:

All your apps and their stacks
All test appliances and their status
All customer appliances and their status
Active releases

View detailed report

tensor9 report -detailed

List all appliances

tensor9 appliance list

Use the web console

Start a local web interface:

tensor9 console

This opens a browser with a visual dashboard of your apps and appliances.

Retire a test appliance

Remove a test appliance when no longer needed.

tensor9 test appliance retire -testApplianceName my-test-appliance

This permanently deletes the test appliance and all its infrastructure. It may take several minutes to fully deprovision.

Troubleshoot common issues

Release deployment fails

Problem: tofu apply fails when deploying a release.Solution:

Check the Terraform error messages
Verify your origin stack is valid: tofu validate in your workspace
Check appliance status: tensor9 report
Review deployment stack variables and configuration
Check AWS credentials and permissions

Test appliance stuck in Creating status

Problem: Test appliance remains in “Creating” status for a long time.Solution:

Wait 15-20 minutes (appliance creation can take time)
Check tensor9 report -detailed for error messages
Verify AWS quotas are sufficient for EKS, VPCs, etc.
Check CloudFormation console in AWS for stack creation issues
Contact support if stuck for more than 30 minutes

Stack publish fails

Problem: tensor9 stack publish fails with upload errors.Solution:

Verify AWS credentials: aws sts get-caller-identity --profile <profile>
Check that no .terraform directories are in your workspace
Ensure you have write permissions to the control plane S3 bucket
For large stacks, check your network connection

Customer can't access their appliance

Problem: Customer reports they can’t reach their deployed application.Solution:

Verify deployment completed: Check with customer that tofu apply succeeded
Check load balancer: kubectl get service shows external IP/hostname
Verify DNS configuration if using custom domains
Check security groups/firewall rules in customer’s cloud
Review application logs: kubectl logs <pod-name>

Release not downloading

Problem: After creating a release, the deployment stack doesn’t download.Solution:

Wait a few minutes (compilation takes time)
Check release status: tensor9 report
Verify appliance is in “Live” status
Check for stack validation errors in the report
Review control plane CloudWatch logs for compilation errors

Best practices

Version your releases semantically

Use semantic versioning for your releases:

1.0.0 - Initial release
1.0.1 - Patch (bug fixes)
1.1.0 - Minor (new features, backward compatible)
2.0.0 - Major (breaking changes)

This helps customers understand the impact of updates.

Test every release

Always create a release to a test appliance before releasing to customers:

Create release to test appliance
Deploy and verify functionality
Test upgrade path from previous version
Only then release to customers

Use descriptive release notes

Write clear, customer-facing release notes:

tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.2.0" \
  -description "Bug fixes and performance improvements" \
  -notes "Fixed authentication timeout issue. Improved API response time by 40%. Added support for batch operations."

Your customers see these notes when deploying.

Organize your origin stacks

Keep your origin stacks in version control and use consistent naming:

Use Git to track changes to origin stacks
Tag releases in Git: git tag v1.0.0
Use the same version in Git and Tensor9 releases
Document infrastructure changes in commit messages

Monitor appliance health

Regularly check appliance status:

# Weekly check
tensor9 report

# Monthly detailed review
tensor9 report -detailed

Set up alerts for customer appliance issues.

Next steps

CLI Reference: Complete command reference
Quick Start Guides: Step-by-step tutorials
Deployments: Learn more about the deployment process
Testing: Best practices for testing releases

Tensor9

Getting Started

Fundamentals

Your Origin Stack

Your Customer's Environment

Integrations

tensor9 CLI

Common Workflows

Prerequisites

Initial setup workflow

Publish and bind your origin stack

For Terraform stacks

For Docker container stacks

For Docker Compose stacks

For CloudFormation stacks

Create a test appliance

Deploy to a test appliance

Create a customer appliance

Release to a customer appliance

Manage multiple form factors

Use stack tuning documents

Monitor appliances

View comprehensive report

View detailed report

List all appliances

Use the web console

Retire a test appliance

Troubleshoot common issues

Best practices

Next steps

Tensor9

Getting Started

Fundamentals

Your Origin Stack

Your Customer's Environment

Integrations

tensor9 CLI

​Prerequisites

​Initial setup workflow

​Publish and bind your origin stack

​For Terraform stacks

​For Docker container stacks

​For Docker Compose stacks

​For CloudFormation stacks

​Create a test appliance

​Deploy to a test appliance

​Create a customer appliance

​Release to a customer appliance

​Manage multiple form factors

​Use stack tuning documents

​Monitor appliances

​View comprehensive report

​View detailed report

​List all appliances

​Use the web console

​Retire a test appliance

​Troubleshoot common issues

​Best practices

​Next steps

Prerequisites

Initial setup workflow

Publish and bind your origin stack

For Terraform stacks

For Docker container stacks

For Docker Compose stacks

For CloudFormation stacks

Create a test appliance

Deploy to a test appliance

Create a customer appliance

Release to a customer appliance

Manage multiple form factors

Use stack tuning documents

Monitor appliances

View comprehensive report

View detailed report

List all appliances

Use the web console

Retire a test appliance

Troubleshoot common issues

Best practices

Next steps