Podman installation

These instructions cover installing and running Terraform Enterprise on Podman on a RHEL 8 or RHEL 9 host using a Kubernetes pod specification. This workflow sets up rootful Podman with a non-root user, meaning that the Podman service runs as root while processes within the container run as non-root. Using a Kubernetes pod specification is our recommended workflow. However, you can deploy Terraform Enterprise on Podman using Docker Compose or other tools that integrate with Podman.

Requirements

Before you begin, ensure you meet the requirements for installing Terraform Enterprise on Podman.

Set up

1. Connect to the instance where you want to run Terraform Enterprise.

2. Create a new directory with a name of your choice. Our documentation uses /opt/fdo as our example directory.

3. For mounted disk installations, navigate into the /opt/fdo/ directory and create a data directory. Later, you will use this directory as a volume mount to store Terraform Enterprise application data.

4. From the /opt/fdo/ directory, create a certs directory and place your TLS certificate (cert.pem), TLS private key (key.pem), and CA certificates bundle (bundle.pem) inside. If you don’t have a CA certificates bundle, place your TLS certificate (cert.pem) inside bundle.pem instead. When finished, the certs directory should look like this:

   certs
   ├── cert.pem
   ├── key.pem
   └── bundle.pem
   

   Copy

5. Alongside the certs and optional data directories, create a kube.yaml file in the /opt/fdo/ directory and populate it with your desired pod configuration. Be sure to replace values enclosed in <> with your installation's values. For example, set TFE_HOSTNAME to the DNS hostname you use to access Terraform Enterprise.

   • Mounted disk kube.yaml example

6. We recommend automating the Podman requirements listed in this section. These must be in place before downloading and installing Terraform Enterprise.

Download and install image

1. Log in to the Terraform Enterprise container image registry, using terraform as the username, and your Hashicorp Terraform Enterprise license as the password:

   $ echo "<HASHICORP_LICENSE>" |  podman login --username terraform images.releases.hashicorp.com --password-stdin
   

   Copy

2. Pull the Terraform Enterprise image from the registry.

   $ podman pull images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
   

   Copy

Run

1. Create a Terraform Enterprise pod by running the following command:

   $ podman play kube /opt/fdo/kube.yaml
   

   Copy

2. In a separate terminal session, you can monitor the logs by running the following command:

   $ podman logs -f <container_name>
   

   Copy

3. Monitor the health of the application until it starts reporting healthy with the following command:

   $ podman exec <container_name> tfe-health-check-status
   

   Copy

Create initial admin user

Provision your first administrative user and start using Terraform Enterprise.

Service Management

To learn more about managing the lifecycle of Podman pods, refer to the Podman docs for more information about pods. We have included possible options for managing a pod's lifecycle on a RHEL host for convenience.

Systemd

Complete the following steps to create a systemd service that automatically starts your pod and its containers. We recommend using Quadlet, which is an opinionated tool for running Podman containers, to deploy systemd. Quadlet generates a systemd service that manages the Terraform Enterprise pod and all containers, including the internal infrastructure container.

1. Ensure the Terraform Enterprise pod is not running.

2. Navigate to /etc/containers/systemd/. Define the service files in this directory.

3. Create a Quadlet unit file for the Terraform Enterprise pod and container at /etc/containers/systemd/terraform-enterprise.kube:

     [Install]
     WantedBy=default.target
     [Service]
     Restart=always
     [Kube]
     Yaml=kube.yaml
   

   Copy

4. Copy the kube.yaml file to /etc/containers/systemd/kube.yaml:

   $ cp /opt/fdo/kube.yaml /etc/containers/systemd/kube.yaml
   

   Copy

5. Reload the systemd daemon and enable the service:

   $ systemctl reload-daemon
   $ systemctl start-service terraform-enterprise.service
   

   Copy

6. Check the status of your service:

   $ systemctl status terraform-enterprise.service
   
     ● terraform-enterprise.service
       Loaded: loaded (/etc/containers/systemd/terraform-enterprise.kube; generated)
       Active: active (running) since Sun 2024-02-25 21:15:55 UTC; 15min ago
     Main PID: 35893 (conmon)
         Tasks: 4 (limit: 404901)
       Memory: 5.2M
       CGroup: /system.slice/terraform-enterprise.service
               ├─35893 /usr/bin/conmon --api-version 1 -c 74f1271d9a481711950c62b509f126c3fdf8678a9d552c5ccc692eb6ed5cf4d1 -u 74f1271d9a481711950c62b509f126c3fdf8678a9d552c5ccc692eb6ed5cf4d1 ->
               ├─36028 /usr/sbin/dnsmasq -u root --conf-file=/run/containers/cni/dnsname/podman-default-kube-network/dnsmasq.conf
               ├─36030 /usr/bin/conmon --api-version 1 -c 973d3ff4f7ada5880a9947be4d90b3d556c7ce841037de34c7eaa07c044a3ec0 -u 973d3ff4f7ada5880a9947be4d90b3d556c7ce841037de34c7eaa07c044a3ec0 ->
               └─36083 /usr/bin/conmon --api-version 1 -c 435ea68e87dbef3c0965ffdfb9fe1fc36c5500a63eb00dc0fe2499aaa560a563 -u 435ea68e87dbef3c0965ffdfb9fe1fc36c5500a63eb00dc0fe2499aaa560a563 ->
   

   Copy

Kubernetes pod specification reference

Mounted disk

This Kubernetes YAML deploys Terraform Enterprise in mounted disk mode as a pod composed of a Terraform Enterprise container.

This is not an exhaustive list of configuration options. Refer to Configuration Reference for a list of all the configuration options.

This configuration uses a volume mount to store Terraform Enterprise application data. The path you specify as the source of the volume mount must exist on the instance running Terraform Enterprise. This path must be backed by durable storage as provided by your cloud provider.

---
apiVersion: "v1"
kind: "Pod"
metadata:
  labels:
    app: "terraform-enterprise"
  name: "terraform-enterprise"
spec:
  restartPolicy: "Never"
  containers:
  - env:
    - name: "TFE_OPERATIONAL_MODE"
      value: "disk"
    - name: "TFE_LICENSE"
      value: "<Hashicorp license>"
    - name: "TFE_HTTP_PORT"
      value: "8080"
    - name: "TFE_HTTPS_PORT"
      value: "8443"
    - name: "TFE_HOSTNAME"
      value: "<Hostname>"
    - name: "TFE_TLS_CERT_FILE"
      value: "/etc/ssl/private/terraform-enterprise/cert.pem"
    - name: "TFE_TLS_KEY_FILE"
      value: "/etc/ssl/private/terraform-enterprise/key.pem"
    - name: "TFE_TLS_CA_BUNDLE_FILE"
      value: "/etc/ssl/private/terraform-enterprise/bundle.pem"
    - name: "TFE_DISK_CACHE_VOLUME_NAME"
      value: "terraform-enterprise_terraform-enterprise-cache"
    - name: "TFE_LICENSE_REPORTING_OPT_OUT"
      value: "true"
    - name: "TFE_ENCRYPTION_PASSWORD"
      value: "<Encryption password>"
    image: "images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>"
    name: "terraform-enterprise"
    ports:
    - containerPort: 8080
      hostPort: 80
    - containerPort: 8443
      hostPort: 443
    - containerPort: 9090
      hostPort: 9090
    securityContext:
      capabilities:
        add:
        - "CAP_IPC_LOCK"
      readOnlyRootFilesystem: true
      seLinuxOptions:
        type: "spc_t"
    volumeMounts:
    - mountPath: "/etc/ssl/private/terraform-enterprise"
      name: "certs"
    - mountPath: "/var/log/terraform-enterprise"
      name: "log"
    - mountPath: "/run"
      name: "run"
    - mountPath: "/tmp"
      name: "tmp"
    - mountPath: "/var/lib/terraform-enterprise"
      name: "data"
    - mountPath: "/run/docker.sock"
      name: "docker-sock"
    - mountPath: "/var/cache/tfe-task-worker/terraform"
      name: "terraform-enterprise_terraform-enterprise-cache-pvc"
  volumes:
  - hostPath:
      path: "/opt/fdo/certs"
      type: "Directory"
    name: "certs"
  - emptyDir:
      medium: "Memory"
    name: "log"
  - emptyDir:
      medium: "Memory"
    name: "run"
  - emptyDir:
      medium: "Memory"
    name: "tmp"
  - hostPath:
      path: "/opt/fdo/data"
      type: "Directory"
    name: "data"
  - hostPath:
      path: "/var/run/docker.sock"
      type: "File"
    name: "docker-sock"
  - name: "terraform-enterprise_terraform-enterprise-cache-pvc"
    persistentVolumeClaim:
      claimName: "terraform-enterprise_terraform-enterprise-cache"