Podman installation

Podman in beta

Note: Running Terraform Enterprise on Podman is still in beta. You should not deploy beta features in production environments! Provision a dedicated test environment before installing Terraform Enterprise on Podman. If you have questions or feedback about the Podman beta, contact your HashiCorp account representative.

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

Connect to the instance where you want to run Terraform Enterprise.
Create a new directory with a name of your choice. Our documentation uses /opt/fdo as our example directory.
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.
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
```
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
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

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
```
Pull the Terraform Enterprise image from the registry. Refer to Terraform Enterprise Releases for a list of versions and replace <vYYYYMM-#> with the version you wish to install; latest is not a valid tag.
```
$ podman pull images.releases.hashicorp.com/hashicorp/terraform-enterprise:<vYYYYMM-#>
```

Run

Create a Terraform Enterprise pod by running the following command:
```
$ podman play kube /opt/fdo/kube.yaml
```
In a separate terminal session, you can monitor the logs by running the following command:
```
$ podman logs -f <container_name>
```
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

You can create a systemd service to automatically start your pod and its containers using the commands below. Only use systemctl on the pod unit, not to start or stop containers individually. The pod service manages all the containers including the internal infrastructure container.

Ensure the Terraform Enterprise pod is up and running.
Navigate to /etc/systemd/system/. You will define the service files in this directory.

Create systemd service files for the Terraform Enterprise pod and container:

$ podman generate systemd --files --name terraform-enterprise

Your pod service definition will resemble the following autogenerated block:

  # autogenerated by Podman 4.6.1

  [Unit]
  Description=Podman pod-terraform-enterprise.service
  Documentation=man:podman-generate-systemd(1)
  Wants=network-online.target
  After=network-online.target
  RequiresMountsFor=/run/containers/storage
  Wants=container-terraform-enterprise-terraform-enterprise.service
  Before=container-terraform-enterprise-terraform-enterprise.service

  [Service]
  Environment=PODMAN_SYSTEMD_UNIT=%n
  Restart=on-failure
  TimeoutStopSec=70
  ExecStart=/usr/bin/podman start 3085f37511a9-infra
  ExecStop=/usr/bin/podman stop  \
          -t 10 3085f37511a9-infra
  ExecStopPost=/usr/bin/podman stop  \
          -t 10 3085f37511a9-infra
  PIDFile=/run/containers/storage/overlay-containers/e3bd0deae7ecfa4ebab25b0a876faaf23806ac1f81385ba621c1d22d426e45d0/userdata/conmon.pid
  Type=forking

  [Install]
  WantedBy=default.target

The container service definition will resemble the following autogenerated block:

  # autogenerated by Podman 4.6.1

  [Unit]
  Description=Podman container-terraform-enterprise-terraform-enterprise.service
  Documentation=man:podman-generate-systemd(1)
  Wants=network-online.target
  After=network-online.target
  RequiresMountsFor=/run/containers/storage
  BindsTo=pod-terraform-enterprise.service
  After=pod-terraform-enterprise.service

  [Service]
  Environment=PODMAN_SYSTEMD_UNIT=%n
  Restart=on-failure
  TimeoutStopSec=70
  ExecStart=/usr/bin/podman start terraform-enterprise-terraform-enterprise
  ExecStop=/usr/bin/podman stop  \
          -t 10 terraform-enterprise-terraform-enterprise
  ExecStopPost=/usr/bin/podman stop  \
          -t 10 terraform-enterprise-terraform-enterprise
  PIDFile=/run/containers/storage/overlay-containers/1fa0e7a42ca1cef5e966a2061b3c76ba9c62ccacbf80709eb42ea4e37adac753/userdata/conmon.pid
  Type=forking

  [Install]
  WantedBy=default.target

Enable the service:

$ systemctl enable pod-terraform-enterprise.service

Test the service:

$ systemctl is-enabled pod-terraform-enterprise.service

Check the status of your service:

$ systemctl status pod-terraform-enterprise.service

● pod-terraform-enterprise.service - Podman pod-terraform-enterprise.service
   Loaded: loaded (/etc/systemd/system/pod-terraform-enterprise.service; enabled; preset: disabled)
   Active: active (running)
     Docs: man:podman-generate-systemd(1)
  Process: 955 ExecStart=/usr/bin/podman start d8a8dd21d869-infra (code=exited, status=0/SUCCESS)
 Main PID: 1400 (conmon)
    Tasks: 0 (limit: 46812)
   Memory: 14.2M
      CPU: 71ms
   CGroup: /system.slice/pod-terraform-enterprise.service

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"