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

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

2. Pull the Terraform Enterprise image from the registry.

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

Run

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

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

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

   $ podman logs -f <container_name>

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

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

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

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

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

5. Reload the systemd daemon and enable the service:

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

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

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"