How to Set up a CloudFormation System

This document describes the procedures for setting up Kill Bill under AWS using the CloudFormation option. This is one of two recommended alternatives for production use. The multi-tier option requires more setup than CloudFormation, but provides more control over the deployment. The procedures in this document are based on the options recommended by Kill Bill.

Deployment via CloudFormation leverages the capabilities of the AWS infrastructure to provide a robust production ready deployment with a single click. The entire CloudFormation configuration, or stack, is defined by a CloudFormation Template.

The features of the CloudFormation system include:

Running Kill Bill on AWS using our CloudFormation Template is the easiest and fastest way to get started with a production cluster. It is also the only method of installation that is certified by the core developers for a highly available, horizontally scalable and production-ready installation.

With the click of a button, the template will install and configure:

The following diagram shows the various AWS entities that will be created by CloudFormation:

All resources for this system run within a single AWS Virtual Private Cloud (VPC), providing a dedicated block of IP addresses which must be located in a single region. The cloud is partitioned into availability zones, which are accessed by subnets. The resources must be distributed over at least two availability zones.

A single EC2 instance hosts both Kill Bill and Kaui servers in the VPC, running on an Ubuntu Linux server. AWS autoscaling is utilized to dynamically adjust the number of instances for each package based on demand, allowing for efficient scaling.

Access to these instances is managed by an AWS Elastic Load Balancer (ELB). The ELB routes each request to the correct package and distributes the requests across the available instances. The ELB accepts traffic securely using HTTPS by default.

The back end of the system is an Aurora database manager provided through the AWS Relational Database System (RDS). Aurora is a robust database system developed by AWS, compatible with MySQL and Postgres. There are separate databases maintained for Kill Bill and Kaui.

In addition, the complete CloudFormation system makes use of AWS scalable and reliable S3 storage technology.

The procedures described here are based on the Kill Bill CloudFormation Template version 2022.10 or later. This system provides the framework for incorporating a variety of analytic tools, including Datadog, New Relic, Rollbar, Sentry, and AWS CloudWatch. In this How-To we will enable CloudWatch, which is easily integrated with our CloudFormation installation. We will not make use of the other analytic tools.

The setup procedure includes seven steps:

To begin, log in to Amazon Web Services at https://aws.amazon.com. If you are new to AWS, you will be asked to create an account and provide billing information. You will need to sign in as a Root User. This should take you to the AWS Management Console, which provides links to all available services.

Check the upper right corner of your screen to be sure you are in the appropriate region. All resources you create will be placed in this region, and may not be accessible from other regions.

In addition, AWS places all resources within a Virtual Private Cloud (VPC). A default VPC will be created and used automatically in the following steps. However, if you have access to other VPCs, you will need to ensure that all Kill Bill resources are deployed in the same one.

All resources for your CloudFormation deployment must be placed within a single VPC. To prepare for CloudFormation deployment you will first need to setup and identify your VPC and subnets.

The CloudFormation implementation uses the HTTPS protocol for strong security. This requires the use of an X.509 certificate.

If you do not have a certificate, select Security, Identity, and Compliance, then Certificate Manager from the Services menu. Then follow the instructions in How to Add a Certificate Using ACM.

If you have a certificate created by ACM, you are all set. If you have a certificate not created by ACM, set the bottom left dropdown to Import and follow the instructions. Import the certificate to ACM.

Now select your certificate from the ACM list and copy its AWS Resource Name (ARN). Save this value as it will be needed in a later step.

The Kill Bill CloudFormation stack requires a key pair. The key pair provides the credentials you will need to login to your EC2 instances. If you already have a key pair, you are all set. Otherwise you will need to create one.

To create a key pair, from the EC2 console scroll down to Networks & Security / Key Pairs. Select Create Key Pair and follow the instructions. Give the key pair a simple, easy to remember name such as My-Key-Pair.For details about key pairs, see the AWS documentation. Important: You must save the private key that will be generated in this step. If you lose this key, you will not be able to login to your instances.

The setup process starts with the Kill Bill CloudFormation Template at AWS Marketplace. Go to this page, then click Continue to Subscribe.

THe next page gives the AWS Terms and Conditions. You must accept these conditions if asked, then click Continue to Configuration. This will take you to the page titled Configure This Software:

Make sure your Region is correct. There is nothing else to change on this page. Click Continue to Launch. THe next page is titled Launch this Software. There is nothing to do here either. Click Launch.

The next page is designated Step 1: Specify Template and titled Create stack:

Once again everything is filled in for you. Click Next. This brings up the Stack Details page (your complete configuration is called a stack):

Now you have some work to do! This page requires that a number of configuration parameters be filled in. All of these are important, and some are critical.

First, you need to provide a name for your stack. Any name will do, as long as it meets the stated rules. Then you will need to carefully set a series of parameters:

When all of these are set, click Next to go to Configure Stack Options. There is only one thing to do here. Scroll down to the panel labeled Stack Failure Options, and select the option Preserve Successfully Provisioned Resources. This ensures that if your stack creation fails, you can use the resources that were successfully created to help troubleshoot the problem. Then click Next.

The final page gives you a chance to review. If everything seems OK, read and check any warnings at the bottom, then click Submit. you are off!

If there are any errors, you will see a message and the Create will not begin. You will need to go back and fix the errors. Common errors may include using an invalid password form (which may give a misleading message), or not choosing subnets in at least two availability zones.

Otherwise, you will see that your stack is being created, and its status (shown in blue) will be CREATE_IN_PROGRESS. You may also check the Resources tab to see the many resources that are being created to make up the complete stack.

If the create succeeds, the status will eventually change to CREATE_COMPLETE (shown in green). This may take a fairly long time.

A critical resource included in your CloudFormation implementation is the ELB Load Balancer. To complete the protection of this resource by your certificate, as explained in How to Add a Certificate Using ACM, you need to create a CNAME for your domain with the name "kaui" and a value that points to this load balancer.

First, find the load balancer in the EC2 console:

Select the load balancer and copy its DNS name as the value for the CNAME you are creating.

You should now be able to login to Kaui from your browser using the URL https://kaui.<DOMAIN>:9090, where <DOMAIN> is your domain that you have used for your certificate. The Kaui login screen should appear:

For an introduction to Kaui, see our Quick Start with Kaui guide. The default credentials are: admin / <KBA_PASSWORD>, where <KBA_PASSWORD> is the parameter KBAdminPassword that you set earlier.

Similarly, you should be able to login directly to the Kill Bill server using the URL https://kaui.<DOMAIN>. This provides access to certain detailed resources that may be needed for maintenance, including metrics and the Swagger API pages.

Congratulations! Your CloudFormation installation is ready to go!

For information on troubleshooting, maintaining and upgrading your installation see How to Maintain a CloudFormation System.