Prepare the Terraform Enterprise host environment

This topic describes how to prepare a Linux instance on your cloud provider to host a non-Replicated Terraform Enterprise deployment. For information about deploying to Replicated, refer to Deploy to Replicated.

Overview

Complete the following steps to set up your Terraform Enterprise host environment:

Determine which runtime is most suitable for your architecture.
Provide a DNS hostname for Terraform Enterprise and the associated TLS certificate.
Configure your network so that your host can receive and send traffic.

Requirements

The requirements depend on the runtime platform you intend to use.

Docker

Terraform Enterprise supports the following versions of Docker Engine that can run amd64 containers. We do not publish arm64 images:

23.0.x
24.0.x
25.0.x
26.0.x
26.1.x

Kubernetes

You can create a host for your Terraform Enterprise Kubernetes cluster on the following cloud service providers:

Amazon Elastic Kubernetes Service (EKS)
Google Cloud Google Kubernetes Engine (GKE)
Azure Kubernetes Service (AKS)

You can install Terraform Enterprise using the Helm CLI version 3.0 or later. Refer to the Helm documentation for instructions on installing Helm.

Nomad

Nomad v1.5.0 and newer.

OpenShift

You can create a host for your Terraform Enterprise OpenShift cluster on the following cloud service providers:

AWS Elastic Kubernetes Service (EKS)
Google Cloud Google Kubernetes Engine (GKE)
Azure Azure Kubernetes Service (AKS)

You can install Terraform Enterprise using the Helm CLI version 3.0 or later. Refer to the Helm documentation for instructions on installing Helm.

Podman

Podman v4.3.0 or later.
If installing on Red Hat Enterprise Linux (RHEL), RHEL 8 or later is required.

Install the runtime

Refer to the documentation for your runtime for installation instructions:

Install Docker Engine for your operating system.
Install Kubernetes
Install OpenShift
Install Podman
Install Nomad

Enable the Podman socket

If you are deploying to Podman, set up Podman’s docker-compatible REST API that runs as a systemd socket-activated service:

$ systemctl enable --now podman.socket

Set the security context for Podman on RHEL and SELinux

We recommend adding type: spc_t to the kube.yaml file when using volumes for an unprivileged Podman container on an SELinux-enabled system. This setting ensures the correct permissions are in place to access the volume when Terraform Enterprise creates the pod/container.

Specify the value in the Kubernetes pod specification's security context:

"securityContext":
  "seLinuxOptions":
    "type": "spc_t"

Assign a DNS hostname

Terraform Enterprise requires a DNS hostname so that it is accessible to users and services. Refer to the documentation for your cloud provider for instructions.

Create TLS certificates

Generate the following TLS certificates:

cert.pem: The end-entity certificate for your DNS hostname with any intermediate certificates appended to it.
key.pem: The private key for the end-entity certificate. Must not be protected by a passphrase.
bundle.pem: Additional certificates to be added to the Certificate Authority (CA) bundle.

If your certificate files are from Let’s Encrypt, the file names map to the following Terraform Enterprise files:

Terraform Enterprise	Let's Encrypt
key.pem	privkey.pem
cert.pem	fullchain.pem
bundle.pem	fullchain.pem

If you do not have a certificate, you can generate a self-signed certificate. The following example uses the openssl command to generate an RSA key and certificate. The -nodes option is required because Terraform Enterprise cannot use a private key that is protected by a passphrase.

$ openssl req -x509 -nodes -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365

When generating the key, replace <terraform.example.com> with the Terraform Enterprise hostname:

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:San Francisco
Organization Name (eg, company) [Internet Widgits Pty Ltd]:HashiCorp, Inc.
Organizational Unit Name (eg, section) []:Engineering
Common Name (e.g. server FQDN or YOUR name) []:<terraform.example.com>
Email Address []:

Copy the cert.pem file to a new file named bundle.pem:

$ cp cert.pem bundle.pem

Security context for Podman

We recommend adding type: spc_t to the Kubernetes pod specification's security context when using volumes for an unprivileged Podman container on an SELinux-enabled system. This setting ensures the correct permissions are in place to access the volume when Terraform Enterprise creates the pod and container.

Set the security context in the kube.yaml:

"securityContext":
  "seLinuxOptions":
    "type": "spc_t"

Configure network access

You must configure the host to allow traffic to and from the Linux instance that Terraform Enterprise runs in. Refer to Configure network access for instructions.