Skip to main content
This quick start guide explains how to use Tensor9 BYOC to deploy your existing Docker container as a private, customer-owned appliance. Tensor9 BYOC provides a click-to-install UI experience for your customers, as well as an AWS console and Tensor9 CLI control plane experience for your team. 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 your Docker container as its origin stack. In this guide, we use Nginx as an example app.
  • Try the customer click-to-install experience and release your app to the customer’s appliance.
  • Explore your control plane in the AWS Console that allows you to observe and operate all customer appliances.
  • Deploy code changes and monitor them rolling out to customer appliances.

​
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.
  • A second AWS account to simulate your first customer.

​
Launch an AWS EC2 instance

To use the Tensor9 CLI, you need to set up an AWS EC2 instance.
  1. Go to your AWS EC2 dashboard.
  2. Select the US West (Oregon) region, us-west-2. Tensor9 BYOC control planes run only in us-west-2 today.
  3. Click the Launch instances button.
  4. Provide a name for your new instance.
  5. Under Application and OS images, choose your desired configuration.
Important: You must use an x86 Linux or MacOS machine image. Windows is not supported. For the purposes of deploying Nginx, we recommend using an Ubuntu x86 Amazon Machine Image (AMI) with a t2.small instance type and at least 20GB of storage, but the needs of other apps may vary.
  1. Select a new or existing Key pair to log in via SSH, if needed. (You can alternatively access your instance via Session Manager.)
  2. Review the Network settings section. These can be left at their defaults in most environments, but you can customize them, if needed.
  3. In the Configure storage section, increase your storage to at least 20GB.
  4. Under Advanced details, select an IAM instance profile that has the AdministratorAccess policy assigned to the role. If you do not have such a profile:
    1. Click the Create new IAM profile link, then click the Create role button.
    2. Select EC2 as Service or use case.
    3. Search for and select AdministratorAccess to add the policy to the role.
    4. Name the role and click Create Role.
    5. Return to your Launch an instance tab and select the new instance profile that you just created.
  5. Click Launch instance.

​
Install the Tensor9 CLI

  1. Connect to your new AWS EC2 instance.
  2. Install the AWS CLI.
  3. Install the Tensor9 CLI by following Install tensor9 CLI.

​
Create your account and control plane

  1. On your own computer, follow Get a Tensor9 API key to sign up and copy your API key.
  2. In your session on the EC2 instance, export your API key and set up your control plane in your new AWS account (about 10 minutes):
Setup uses the instance profile’s AWS credentials and makes its controller profile your CLI default, so the commands below need no API key or profile options.

​
Create an app and prepare a Docker container

  1. Create a new Tensor9 BYOC app. As an example, we use Nginx:
tensor9 app create -name nginx-example -displayName "Nginx example app" Note: The length of the displayName field must be 32 characters or fewer.
  1. Install Docker, if it is not already installed:
sudo apt install docker.io
  1. Verify that Docker is running:
sudo docker version
  1. Prepare a docker container with your app. In this example, we download Nginx:
sudo docker pull nginx
  1. Push your container to a repository in the Elastic Container Registry (ECR) in your Tensor9 BYOC AWS account. For more information and for a list of push commands, go to your list of private repositories, click a repository link, and then click the View push commands button.
Note: The list of push commands includes a build step, but because you are pulling down an existing Docker container for Nginx, you do not need to complete the build step. The build step is only required if you are building your own container. If you are building your own container, make sure the container supports the linux/amd64 architecture.
  1. Bind your container as your new origin stack:
You can find your container URI by checking the chosen docker image in the ECR repository. The URI should look like this: <YOUR_AWS_ACCOUNT_ID>.dkr.ecr.<YOUR-REGION>.amazonaws.com/<IMG_NAME>:<IMG_TAG>

​
Testing the customer install process

As a vendor providing services to customers, you can test your environment by going through the process of installing your app from the perspective of a customer.
  1. Create a form factor that lets customers install your app in AWS:
  1. Create a setup link for your simulated customer:
The command creates the customer acme-corp if it does not exist yet and prints the customer’s setup link.
  1. Log into the AWS console of your second AWS account as your simulated customer. Verify that you have admin permissions.
  2. Visit the setup link in the same browser window that you used to log into the AWS console as a simulated customer. 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.
  3. 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:
  1. Create a release for your customer:
Docker container releases deploy automatically to the customer’s appliance. The CLI follows the deployment progress until the install finishes. Next, we will explore the control plane for this customer appliance.

​
Explore your control plane in AWS

AWS is your control plane for all your customer appliances. You can view the status of your customer appliances in AWS.
  1. Visit the deployment stack for a customer appliance by searching for your customer name in the AWS CloudFormation console.
Note: The customer deployment stack might not appear immediately. It takes approximately 10 minutes for your deployment stack to deploy for the first time after the appliance is provisioned.
  1. Click the link to the customer app deployment stack, then click Events and Timeline View. This view shows the deployment timeline of your stack to the customer’s appliance.
  2. Click the Resources tab, search for “service”, then click the Service link to view the ECS cluster for your customer. Here you can explore deployments, see which containers are running, and view logs and metrics.
Note: Logs and metrics might not appear immediately. It takes at least 10-15 minutes for your customer’s appliance to provision hardware, download your docker container, and start publishing logs and metrics to your deployment stack. When startup logs for Nginx appear in the container, then Nginx is running:
The load balancer in your deployment stack should also show as healthy:
  1. Run tensor9 report and look for a line labeled DnsNameForLbAppliance in the Customer Appliances section of the output. This is the DNS name for the customer appliance. For example, nginx--LbApp-tAUAT8tDV5hn-0c7199c912e8827d.elb.us-west-2.amazonaws.com .
  2. Visit http://<DNS_NAME_FOR_LB>:80 to use Nginx as if you were the customer.

​
Release a code change

At any time, you can make a code change, build the latest container, and push it to Elastic Container Registry in your Tensor9 BYOC AWS account using the same Docker image tag you used to deploy the container. Important: Verify that your container supports the linux/amd64 platform.
  1. Retire the current release:
  1. Create a new release:
Important: You must use a different -vendorVersion than the currently deployed app.
  1. Inspect your customer’s deployment stack in the AWS CloudFormation console to find the ECS cluster. A recent blue or green deployment for your change appears. The old software will not be turned off until the new software is up and passing health checks.
  2. Run tensor9 report and look for a line labeled DnsNameForLbAppliance in the Customer Appliances section. This is the DNS name for the customer appliance. For example, nginx-LbApp-6SOn9F6auFHS-bb813efec3dd0c2c.elb.us-west-2.amazonaws.com .
  3. Visit http://<DNS_NAME_FOR_LB>:80 to test Nginx on the customer appliance and verify that your code changes were applied.

​
Clean up

When you finish with this guide, remove what you created. You can do the following yourself today:
  1. Unbind the container from your app, so that no new releases are made from it:
Unbinding does not remove anything already deployed.
  1. Delete the images you pushed to your ECR repository, and terminate the EC2 instance you launched for this guide, if you no longer need them.
Some steps currently need Tensor9 support. Tensor9 deploys Docker container releases into the customer’s appliance for you, and removing that deployment, the customer’s appliance or your control plane in your AWS account is not yet available to you directly. To remove them, 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.