Overview
The Terraform Library provides an easy way to deploy your application to Kubernetes. The library leverages this combination of cloud services:
- Terraform Cloud to manage the setup of the cloud services and app deployments
- DigitialOcean for Kubernetes, PostgreSQL, and domain management
- Let's Encrypt for SSL certificates
- BitBucket or Github as your source control system
- Docker Hub for image repository and builds
- Auth0 for authentication
- SendGrid for authentication emails
Terraform Cloud enables infrastructure automation for provisioning and management of any cloud, datacenter, and service. We will create three Terraform workspaces and use them to:
- Provision a Kubernetes cluster on DigitalOcean
- Configure Auth0 for authentication for apps on the cluster
- Deploy our application as a Docker container onto the cluster
Build your Application in Apex Designer
The first step is to create your application. This process should work for any application built with Apex Designer.
Check your Application into Source Control
To do this, you will need an account on e.g. Bitbucket or Github (the free plans are sufficient). A single account can be used for many applications.
Create a repository for your application (e.g. my-app).
Follow these instructions to push your app to source control.
Set up a Cluster
Follow the instructions here to set up a Terraform workspace that will run to create the kubernetes cluster on Digital Ocean. This is a one time setup and multiple applications can use the same cluster.
Configure Auth0
Follow the instructions here to set up a Terraform workspace that will configure Auth0 for the cluster. This is also a one time setup that multiple applications can use.
Set up a Docker Hub Account
Set up a Docker Hub account and select the Pro subscription ($5 per month at the time of this writing). The paid plan is required in order to have private repositories. A single account can be used for many applications.
- To change plan, click on your avatar (top right), select Billing, and then click the "Change Plan" button.
- Go to Account Settings + Security and create an access token named Terraform. Note the access token which will be used in later steps.
Set up Docker Hub Repository and Automatic Build
In Docker Hub, click Add Repository and:
- Enter your app name (my-app for example)
- Set visibility to Private
- In build settings, connect to BitBucket or Github (depending on where you put your app source code)
- Select the repository you created for your application (e.g. my-app)
- In build rules, set Source Type to Tag, Source to /^v([0-9.]+)$/ and Docker Tag to {\1}
- Click Create and build
Add the Library to Your App in Apex Designer
- In Apex Designer, click on dependencies (left navigation)
- Add the Terraform Library to your app dependencies
- Go to Settings + Parameter values and fill in the Terraform parameters (enter the name of the Docker Hub repo e.g. mydockeraccount/my-app-com)
- Click Generate App to generate the new Terraform files (you can see these in the /terraform directory in Files.
Push App to Source Control
Follow these instructions to push you app to source control. When the push is complete you should see a pending build on the Docker repository Builds tab.
Your app is now checked into source, with a corresponding docker container image built and stored in the Docker Hub repository. The next step is to configure a Terraform workspace to deploy the app container image onto the cluster.
Create a Terraform Variable Set
Most of the variables required to deploy your app will be common across multiple deployments of your app (and even across apps). Terraform uses Variable Sets to manage variable values that are used on multiple workspaces (app deployments).
Go to Settings + Variable sets and click Create variable set. Enter your app name + common as the name (My App Common for example) and add the variables listed below. Be sure to check the "Sensitive" box on the ones that are marked.
- digital_ocean_token: The DigitalOcean token related to the team (check Sensitive).
- domain: The top level domain (my-app.com for example).
- docker_hub_username: The docker hub username for image pulls from private registries (your docker hub username).
- docker_hub_email: The docker hub email for image pulls from private registries (your email).
- docker_hub_token: The docker hub token for image pulls from private registries (check Sensitive).
- auth0_domain: Your Auth0 tenant domain name (myapp.us.auth0.com for example).
- auth0_client_id: The Terraform machine to machine app client id.
- auth0_client_secret: The Terraform machine to machine app client secret (check Sensitive).
- auth0_email_connection_id: The id of the Auth0 email passwordless connection (output from the workspace that configured Auth0).
After all the variables are added click save.
Create the Terraform App Workspace
You can deploy as many copies of the application as you like. You can create one for Test and one for Prod and/or create a separate instance for each client.
Each deployment will have a separate subdomain. Create a new workspace as follows:
- Select Version control workflow
- Connect the workspace to your BitBucket repository (if you have a large number of repositories, you may have to scroll all the way down and enter the repository name manually)
- Set the workspace name to your subdomain name + domain (test-myapp-com for example)
- Select your project
- Click Advanced Options and enter /terraform/app-deployment in the Terraform Working Directory
- Click Auto apply for the Apply Method (for Prod, you probably want to leave that set to manual)
- Click the Create workspace button
The workspace is created.
Apply the Common Variable Set
Click the link to go to the workspace variables page (or go to workspaces, select the workspace and click variables). Click the Apply variable set button, select the variable set you created above, and click the Apply variable set button.
Add the Workspace Specific Variables
On the Variables page, add two workspace specific variables:
- subdomain: The subdomain for this deployment (my-sub will result in my-sub.my-app.com).
- admin_emails: A comma-separated list of emails that will be administrators (enter your email)
Trigger the First Run
Go to Runs, click Actions and click start new run. When the run is planned and applied, your deployment should be ready to test.
Updates
When you push updates to source control, Terraform will automatically trigger a new run to update the deployment.