Podman installation
This guide describes how to install and run Terraform Enterprise on Podman. These instructions are specific to Red Hat Enterprise Linux (RHEL) 8 and 9 hosts and use a Kubernetes YAML to define Podman resources. This workflow sets up rootful Podman with a non-root user. As a result, the Podman service runs as root while processes within the container run as non-root.
Requirements
Before you begin, ensure you meet the Podman requirements for installing Terraform Enterprise on Podman.
Mounted Disk operational mode
- Durable storage from the cloud provider of your choice. 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.
External Services operational mode
- PostgreSQL database server
- Blob storage (AWS S3, Azure Cloud Storage, Google Cloud Storage, or any S3-compatible storage service)
Active/Active operational mode
- PostgreSQL database server.
- Object-based storage, such as AWS S3, Azure Cloud Storage, Google Cloud Storage, or any S3-compatible storage service.
- Redis version 6 or 7. Redis Cluster is not currently supported.
Set up
Connect to the instance where you want to run Terraform Enterprise.
Log in as the root user.
For Mounted Disk installations, create a directory to be used for TFE data storage. Terraform Enterprise uses this directory as a volume mount to store application data.
Create a directory for your TLS certificate (
cert.pem
), TLS private key (key.pem
), and CA certificates bundle (bundle.pem
). If you do not have a CA certificates bundle, place your TLS certificate (cert.pem
) insidebundle.pem
instead. When finished, this directory resembles the following tree:Create a YAML file and populate it with your desired pod configuration. If you use one of the following example configurations, replace values enclosed in
<>
with your installation's values. For example, setTFE_HOSTNAME
to the DNS hostname you use to access Terraform Enterprise.
Active/Active operational mode Kubernetes YAML example
Refer to Operation Modes for additional information.
- 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:Pull the Terraform Enterprise image from the registry.
Run
Create a Terraform Enterprise pod by running the following command:
In a separate terminal session, you can monitor the logs by running the following command:
Monitor the health of the application until it starts reporting healthy with the following command:
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.
Ensure the Terraform Enterprise pod is not running.
Navigate to
/etc/containers/systemd/
. Define the service files in this directory.Create a Quadlet unit file for the Terraform Enterprise pod and container at
/etc/containers/systemd/terraform-enterprise.kube
:Copy your Kubernetes YAML file to
/etc/containers/systemd/tfe.yaml
:Reload the
systemd
daemon and enable the service:Check the status of your service:
Kubernetes pod specification reference
This is not an exhaustive list of configuration options. Refer to Configuration Reference for a list of all the configuration options.
Mounted Disk
This Kubernetes YAML deploys Terraform Enterprise in Mounted Disk mode as a pod composed of a Terraform Enterprise container.
External Services
The following Kubernetes YAML configuration deploys Terraform Enterprise in External Services mode as a pod composed of a Terraform Enterprise container.
Active/Active
The following Kubernetes YAML configuration deploys Terraform Enterprise in Active/Active mode. In Active/Active mode, each node runs a Podman pod composed of a TFE container.