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

• Nomad version v1.5.0 and newer.

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.

Please make sure you have the following environment variables set before running Nomad commands from CLI:

export NOMAD_ADDR=http://<nomad-server-ip>:4646
export NOMAD_TOKEN=<nomad-token>
export NOMAD_CLIENT_CERT=<path-to-client-cert>
export NOMAD_CLIENT_KEY=<path-to-client-key>
export NOMAD_CA_CERT=<path-to-ca-cert>

You can read more about the Nomad environment variables here.

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:

Create a policy file named terraform-enterprise-policy.hcl with the following content:

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

To apply the policy run following bash command:

$ nomad acl policy apply \
 -namespace terraform-enterprise -job <tfe-job-name> \
 -group <tfe-job-group> -task <tfe-job-task> \
 terraform-enterprise-policy ./terraform-enterprise-policy.hcl

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. Refer to the Nomad version requirements.

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. To create a namespace, run the following command:

    $ nomad namespace apply <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