» Deploying a Terraform Enterprise Cluster on AWS

This page outlines the procedure for deploying a Terraform Enterprise cluster on Amazon Web Services (AWS).

» Summary

Deploying Terraform Enterprise involves the following steps:

  1. Follow the pre-install checklist.
  2. Prepare the machine that will run Terraform.
  3. Prepare some required AWS infrastructure.
  4. Write a Terraform configuration that calls the deployment module.
  5. Apply the configuration to deploy the cluster.

» Terraform Module

The clustered deployment process relies on a Terraform module, which is available here:

This page should be used in conjunction with the module's documentation on the Terraform Registry, which includes full documentation for the module's input variables and outputs.

» Pre-Install Checklist

Before you begin, follow the Pre-Install Checklist and ensure you have all of the prerequisites. This checklist includes several important decisions, some supporting infrastructure, and necessary credentials.

In particular, note that Terraform Enterprise's certificate must be available in ACM matching the domain provided or via ARN.

» Prepare a Machine for Terraform

The Terraform module that deploys Terraform Enterprise is written to support Terraform 0.11.x. You can run this configuration from a workspace in an existing Terraform Enterprise instance, or from an arbitrary workstation or server.

Decide where you'll be running Terraform, and ensure:

» Prepare Infrastructure

Make sure the following foundational AWS infrastructure is available:

  • A VPC
  • Subnets (both public and private) spread across multiple AZs
  • A DNS Zone

» Automated Preparation

You can create the required infrastructure resources with an example bootstrap Terraform module. This module has no requirements beyond provider authentication.

» Write the Terraform Configuration

  1. In your web browser, go to the hashicorp/terraform-enterprise/aws module on the Terraform Registry. This is the module you'll use to deploy Terraform Enterprise.
  2. Review the module's input variables.
  3. Create a new Terraform configuration that calls the hashicorp/terraform-enterprise/aws module:

    • Start by copying the "Provision Instructions" example from the module's Terraform Registry page.
    • Fill in values for all of the required input variables.
    • Fill in any optional variables as desired. If you omit all optional variables, the module will deploy a mid-sized cluster using the demo operational mode.
    • Map all of the module's output values to root-level outputs, so that Terraform will display them after applying the configuration. For example:

      output "tfe_cluster" {
        value = {
          application_endpoint = "${module.terraform-enterprise.application_endpoint}"
          application_health_check = "${module.terraform-enterprise.application_health_check}"
          # ...
        }
      }
      

» Init, Plan, Apply

  1. Initialize Terraform and run a plan. If you are running Terraform from the CLI, you can do this by navigating to the configuration's directory and running:

    $ terraform init
    $ terraform plan -out planfile
    
  2. If the plan runs without errors and looks correct, apply it:

    $ terraform apply planfile
    
  3. Once the apply has finished, Terraform will display any root-level outputs you configured. For example:

    Apply complete! Resources: 33 added, 0 changed, 0 destroyed.
    
    Outputs:
    
    tfe_cluster = {
      application_endpoint = https://tfe-hvg9o7lo.example.com
      application_health_check = https://tfe-hvg9o7lo.example.com/_health_check
      iam_role = tfe-hvg9o7lo
      install_id = hvg9o7lo
      installer_dashboard_url = https://tfe-hvg9o7lo.example.com:8800
      installer_dashboard_password = manually-grand-gator
      primary_public_ip = 12.34.56.78
      ssh_config_file = /Users/jsmith/Documents/tfe-beta/.terraform/modules/c8066b63fe35e7cb30635ab501caa438/hashicorp-terraform-aws-terraform-enterprise-4dc067c/work/ssh-config
      ssh_private_key = /Users/jsmith/Documents/tfe-beta/.terraform/modules/a1d4d4cc38b069facc8774038e3ad299/work/tfe-hvg9o7lo.priv
    }
    

    At this point, the infrastructure is finished deploying, but the application is not. It can take up to 30 minutes before the website becomes available.

    The installer dashboard should become available first, and is accessible at the URL specified in the installer_dashboard_url output.

  4. Open the installer dashboard in your web browser, and log in with the password specified in the installer_dashboard_password output. Follow the instructions at Terraform Enterprise Configuration to finish setting up the application.

After the application is fully deployed, you can adjust the cluster's size by changing the module's inputs and re-applying the Terraform configuration.