» Deploying a Terraform Enterprise Cluster on Azure

This page outlines the procedure for deploying a Terraform Enterprise cluster on Azure.

» 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 Azure 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 in PFX format.

» 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 Azure infrastructure is available:

  • Access to an existing Azure account and subscription.
  • An existing Resource Group.
  • An existing Virtual Network, with a subnet dedicated to the Terraform Enterprise cluster and an associated Network Security Group. The Network Security Group must permit TCP access over the following ports:

    Port Description
    22 SSH access
    443 Application Access
    6443 Cluster access
    8800 Installer Dashboard Access
    23010 Application Health Check
  • An Azure Key Vault (for storing/distributing an SSL certificate).

  • A DNS zone.

If you choose to install in external services mode, you will also need:

  • An Azure Database for PostgreSQL - please see PostgreSQL Requirements.
  • An Azure Blob Storage container created specifically for Terraform Enterprise. The container does not need to be in the same project as the Terraform Enterprise server(s), but you will need credentials for a service principal to access the container.

» Automated Preparation

If you have an empty test subscription, you can create the required infrastructure resources with an example bootstrap Terraform module. This module only requires the following:

  • Access to the subscription
  • A DNS zone

The module will create the virtual network, the subnet, required firewalls, and an Azure key vault.

» Write the Terraform Configuration

  1. In your web browser, go to the hashicorp/terraform-enterprise/azurerm 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/azurerm 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: 37 added, 0 changed, 0 destroyed.
    
    Outputs:
    
    tfe_cluster = {
      application_endpoint = https://tfe-k6ad3oku.tfe.example.com
      application_health_check = http://tfe-k6ad3oku.tfe.example.com/_health_check
      installer_dashboard_endpoint = https://tfe-k6ad3oku.tfe.example.com:8800
      installer_dashboard_password = random-starting-password
      ssh_config_file = /path/to/ssh_config
    }
    

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