Terraform Enterprise HVD on GCP GCE

Terraform module aligned with HashiCorp Validated Designs (HVD) to deploy Terraform Enterprise (TFE) on Google Cloud Platform (GCP) using Compute Engine instances with a container runtime. This module defaults to deploying TFE in the active-active operational mode, but external is also supported. Docker is currently the only supported container runtime, but Podman support is being added.

Prerequisites

General

• TFE license file (e.g. terraform.hclic)
• Terraform CLI >= 1.9 installed on clients/workstations that will be used to deploy TFE
• General understanding of how to use Terraform (Community Edition)
• General understanding of how to use GCP
• git CLI and Visual Studio Code editor installed on workstations are strongly recommended
• GCP projeect that TFE will be deployed in with permissions to provision these resources via Terraform CLI
• (Optional) GCP GCS bucket for GCS remote state backend that will be used to manage the Terraform state of this TFE deployment (out-of-band from the TFE application) via Terraform CLI (Community Edition)

Networking

• GCP network VPC and the following subnets:
  • Load balancer subnetwork IDS (can be the same as Compute Engine (CE) subnets if desirable).
• (Optional) GCS VPC Endpoint configured within VPC.
• (Optional) GCS Hosted Zone for TFE DNS record creation.
• Security groups. This module will create the:
  • necessary security groups and attach them to the applicable resources.
  • service accounts and assign them access to the provided secrets
  • firewall entries.
  • Ensure the TFE ingress requirements are met.
  • Ensure the TFE egress requirements are met.

Secrets Manager

GCP Secrets Manager "TFE bootstrap" secrets:

• TFE license file - raw contents of file stored as a plaintext secret.
• TFE encryption password - random characters stored as plaintext secret.
• RDS (PostgreSQL) database password - random characters stored as plaintext secret.
• (Optional) Redis password - random characters stored as a plaintext secret.
• TFE TLS certificate - file in PEM format, base64-encoded into a string, and stored as a plaintext secret.
• TFE TLS certificate private key - file in PEM format, base64-encoded into a string, and stored as a plaintext secret.
• TLS CA bundle - file in PEM format, base64-encoded into a string, and stored as a plaintext secret.

Compute

One of the following mechanisms for shell access to TFE GC instances:

• Ability to enable GCP IAP (this module supports this via a boolean input variable).
• GC SSH Key Pair

Log Forwarding (optional)

One of the following logging destinations:

• Stackdriver
• A custom fluent bit configuration that will forward logs to custom destination.

Usage

1. Create/configure/validate the applicable prerequisites.

2. Nested within the examples directory are subdirectories containing ready-made Terraform configurations for example scenarios on how to call and deploy this module. To get started, choose the example scenario that most closely matches your requirements. You can customize your deployment later by adding additional module inputs as you see fit (see the Deployment-Customizations doc for more details).

3. Copy all of the Terraform files from your example scenario of choice into a new destination directory to create your Terraform configuration that will manage your TFE deployment. This is a common directory structure for managing multiple TFE deployments:

   .
   └── environments
       ├── production
       │   ├── backend.tf
       │   ├── main.tf
       │   ├── outputs.tf
       │   ├── terraform.tfvars
       │   └── variables.tf
       └── sandbox
           ├── backend.tf
           ├── main.tf
           ├── outputs.tf
           ├── terraform.tfvars
           └── variables.tf
   

   📝 Note: in this example, the user will have two separate TFE deployments; one for their sandbox environment, and one for their production environment. This is recommended, but not required.

4. (Optional) Uncomment and update the GCS remote state backend configuration provided in the backend.tf file with your own custom values. While this step is highly recommended, it is technically not required to use a remote backend config for your TFE deployment.

5. Populate your own custom values into the terraform.tfvars.example file that was provided, and remove the .example file extension such that the file is now named terraform.tfvars.

6. Navigate to the directory of your newly created Terraform configuration for your TFE deployment, and run terraform init, terraform plan, and terraform apply.

7. After your terraform apply finishes successfully, you can monitor the installation progress by connecting to your TFE gcp instance shell via SSH or gcp IAP and observing the meta data script(user_data) logs:

   Higher-level logs:

   tail -f /var/log/tfe-cloud-init.log
   

   Lower-level logs:

   sudo journalctl -u google-startup-scripts.service -f
   

   📝 Note: the -f argument is to follow the logs as they append in real-time, and is optional. You may remove the -f for a static view.

   The log files should display the following message after the cloud-init (user_data) script finishes successfully:

   [INFO] tfe_user_data script finished successfully!
   

8. After the cloud-init (user_data) script finishes successfully, while still connected to the TFE CE instance shell, you can check the health status of TFE:

   cd /etc/tfe
   sudo docker compose exec terraform-enterprise tfe-health-check-status
   

9. Follow the steps to here to create the TFE initial admin user.

• the module includes outputs for the initial admin user token retrieval.

Docs

Below are links to docs pages related to deployment customizations as well as managing day 2 operations of your TFE instance.

• deployment-customizations.md
• operations.md
• tfe-tls-cert-rotation.md
• tfe-config-settings.md
• tfe-version-upgrades.md
• troubleshooting.md

Requirements

Providers

Resources

Inputs

Outputs