Nomad requirements

This topic describes the requirements for deploying Terraform Enterprise to Nomad-orchestrated containers. Refer to the shared requirements for requirements common to all Terraform Enterprise deployments.

You must meet the following requirements before installing Terraform Enterprise on Nomad. Refer to the Nomad clusters on the cloud tutorial for instructions on how to setup a Nomad cluster.

Versions

• We recommend Nomad v1.5.0 and newer.
• You can deploy to Nomad v1.4.x and older by modifying the Terraform Enterprise job specification. Refer to Configure Terraform Enterprise Nomad job specification for additional information.

External services

Terraform Enterprise requires the following external services to be present and accessible from the Nomad cluster:

1. A PostgreSQL database. Refer to PostgreSQL Requirements for Terraform Enterprise for additional information.
2. An S3-compatible storage service, such as AWS S3, Azure Cloud Storage, and Google Cloud Storage. Refer to External Services Mode for additional information.
3. Redis version 6 or 7. Redis Cluster is not supported.

Nomad requirements

You must provide the following Nomad items.

ACL Policy

Create a token that grants access to the namespace where the Terraform Enterprise agents will run. The Terraform Enterprise job must present the token to the Terraform Enterprise agent so that it can run the agent job that performs Terraform operations. Refer to the Nomad ACL system fundamentals tutorial for instructions on how to create ACL policies linked to tokens.

Apply the following ACL policy to the terraform-enterprise namespace so that Terraform Enterprise has permission to run and manage agent jobs:

namespace "tfe-agents" {
    capabilities = [
        "submit-job",
        "dispatch-job",
        "list-jobs",
        "read-job",
        "read-logs" 
    ]
}

Workload identity

A workload identity must be enabled on the Nomad cluster so that Nomad can inject the Nomad ACL token. The workload identity passes the token using the NOMAD_TOKEN environment variable. Refer to Workload Identity for additional information.

Terraform Enterprise does not use workload identities on Nomad v1.4 and older. Instead, you must pass the NOMAD_TOKEN directly in the Terraform Enterprise job specification. Refer to Configure Terraform Enterprise Nomad job specification for additional information.

Terraform Enterprise requirements

• You must meet the shared requirements for all deployments.

• A DNS hostname for accessing Terraform Enterprise.

• A TLS certificate and private key for your DNS hostname.

• A HashiCorp-issued Terraform Enterprise license.

• Two separate Nomad namespaces. One namespace is for the Terraform Enterprise job and the second is for the Terraform Enterprise agent job. This provides better isolation, security and control over Nomad workloads. Refer to the Namespaces tutorial in the Nomad documentation for instructions on how to create a namespace.

Network

Refer to the Network requirements.

TLS certificate requirements

You must have the following TLS certificate files:

• 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:

If you do not have a certificate, you can generate a self-signed certificate using the openssl command. You must including the -nodes option because Terraform Enterprise cannot use a private key that is protected by a passphrase.

The following example command generates an RSA-encrypted TLS certificate that expires in one year:

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

Provide the necessary information for the certificate when prompted. The following example generates a certificate for HashiCorp at the fully-qualified domain name (FQDN) terraform.example.com. The FQDN specifies the hostname you use to access your Terraform Enterprise instances.

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 []:

OpenSSL generates the cert.pem and key.pem files, but not the bundle.pem file. Use the cp command to create the bundle.pem file:

$ cp cert.pem bundle.pem