Quick start: CloudFormation

• Create your Tensor9 account and set up a Tensor9 BYOC control plane in your AWS account.
• Create an app and bind an AWS CloudFormation stack 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.
• A CloudFormation template that creates your app’s origin stack and runs your container. This guide uses Nginx as the example app; if you would like Tensor9’s sample Nginx template, email [email protected].
• 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

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.

6. Select a new or existing Key pair to log in via SSH, if needed. (You can alternatively access your instance via Session Manager.)
7. Review the Network settings section. These can be left at their defaults in most environments, but you can customize them, if needed.
8. In the Configure storage section, increase your storage to at least 20GB.
9. 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.
10. 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):

export T9_API_KEY=<your API key>
tensor9 vendor setup

​

Create an app and prepare a Docker container

1. Create a new Tensor9 BYOC app. As an example, we use Nginx:

2. Install Docker, if it is not already installed:

3. Verify that Docker is running:

4. Prepare a docker container with your app. In this example, we download Nginx:

5. 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.

​

Set up a CloudFormation origin stack

1. Go to the AWS CloudFormation Console in your region.
2. Click the Create stack button, then click With new resources.
3. Click Choose an existing template, then click Upload a template file. Upload your CloudFormation template, then click Next.
4. Enter a stack name for your new stack (32 characters or fewer, such as t9-quickstart-origin-stack), then click Next.
5. On the Configure Stack Options screen, you can leave all settings at their defaults. Check the checkbox next to I acknowledge that AWS CloudFormation might create IAM resources and click Next.
6. Review all settings, then click the Submit button to create your stack. The stack takes several minutes to be created.
7. After your new stack is created, click on its name to find its Amazon Resource Name (ARN). The ARN of the stack shows as the Stack ID.
8. Bind your stack as the new origin stack:

tensor9 stack bind \
  -appName nginx-example \
  -stackType CloudFormation \
  -nativeStackId <YOUR_STACK_ARN>

​

Testing the customer install process

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

tensor9 form-factor create \
  -appName nginx-example \
  -formFactorName aws-connected \
  -env Aws \
  -connectivity Connected

2. Create a setup link for your simulated customer:

tensor9 app setup -appName nginx-example -customerName acme-corp

3. Log into the AWS console of your second AWS account as your simulated customer. Verify that you have admin permissions.
4. 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.
5. 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:

6. Create a release for your customer:

tensor9 stack release create \
  -appName nginx-example \
  -customerName acme-corp \
  -vendorVersion "1.0.0" \
  -description "First release of Nginx via Tensor9" \
  -notes "By [email protected]"

​

Explore your control plane in AWS

1. Visit the deployment stack for a customer appliance by searching for your customer name in the AWS CloudFormation console.

2. 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.
3. 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.

4. 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 .
5. Visit http://<DNS_NAME_FOR_LB>:80 to use Nginx as if you were the customer.

​

Release a code change

1. Prepare your updated Docker container, then tag the container and push it to your ECR repository just as you did in the Create an app and prepare a Docker container section.
2. Modify the CloudFormation stack template that you used in the Set up a CloudFormation origin stack section so that it has the URI of the new container you just pushed to your ECR repository.
3. Go to your AWS CloudFormation console and select your Tensor9 BYOC origin stack, then click Update stack > Make a direct update. On the next screen, click Replace existing template. Select the template you modified in the previous step, then click the Next button.
4. On the following screen, make any modifications that are appropriate for your environment, then click Next. On the Configure stack options screen, check the checkbox next to I acknowledge that AWS CloudFormation might create IAM resources, then click Next.
5. On the Review screen, verify that all the changes look correct. When you are ready, click the Submit button. The stack takes several minutes for update to complete.
6. Retire the current release:

tensor9 stack release retire \
  -appName nginx-example \
  -customerName acme-corp \
  -vendorVersion "1.0.0"

7. Create a new release:

tensor9 stack release create \
  -appName nginx-example \
  -customerName acme-corp \
  -vendorVersion "1.0.1" \
  -description "<YOUR_DESCRIPTION>" \
  -notes "<YOUR_NOTES>"

8. 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.
9. 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 .
10. Visit http://<DNS_NAME_FOR_LB> to test Nginx on the customer appliance and verify that your code changes were applied.

​

Clean up

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

tensor9 stack unbind -appName nginx-example

2. After unbinding, delete the origin stack that you created in the AWS CloudFormation console, 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.