Deploying and operating Terraform Enterprise on OpenShift requires precise coordination between Helm-based application delivery and OpenShift primitives that the chart intentionally leaves to the operator. Managing OpenShift itself with Terraform, particularly on Azure Red Hat OpenShift, adds another layer where infrastructure provisioning meets Kubernetes-native configuration. Both patterns rely on explicit prerequisites, security context constraints, and manual route and storage wiring that cannot be assumed from a generic Kubernetes install.

Deploying Terraform Enterprise on OpenShift

Terraform Enterprise Helm Chart is intended to meet the needs of the majority of users. Many OpenShift primitives, such as routing, are absent in the terraform-enterprise Helm chart. You can fork the Helm chart and adapt it to your organization’s requirements. Alternatively, you can use the terraform-enterprise Helm chart as a sub-chart, thus relegating OpenShift primitives to the parent chart to be deployed around the terraform-enterprise chart contents.

When Terraform Enterprise is deployed to OpenShift, the Helm chart does not create an OpenShift route by default. Provisioning a route creates a public-facing URL at which users can access the Terraform Enterprise UI and API.

The route can be provisioned with oc expose:

oc expose svc/terraform-enterprise --hostname terraform-enterprise.apps.<openshift cluster base domain> --name terraform-enterprise -n <TFE_PROJECT>

Note: Use the options on the oc expose command to tailor the route to the needs of your environment.

The newly created route can then be retrieved from the cluster:

oc get routes

Example output:

NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD terraform-enterprise terraform-enterprise.apps.<openshift cluster base domain> terraform-enterprise https-port reencrypt/Redirect None

Provision your first administrative user and start using Terraform Enterprise after the route is available.

Complete the following steps to install Terraform Enterprise:

• Complete the prerequisites.
• Create a custom HCP Terraform agent.
• Enable the OpenShift configuration your overrides values file.
• Install the Helm chart and apply your override values.
• Complete post installation tasks.

The requirements for deploying Terraform Enterprise depend on the version you want to deploy, as well as the environment you plan to operate the software in, such as operating system, runtime, and storage systems. Check the software product compatibility report page for details.

Prerequisites and Host Preparation

You should have a deep understanding of OpenShift before deploying Terraform Enterprise to a production environment.

Deploy external service dependencies outside the OpenShift cluster and scale as necessary to accommodate Terraform Enterprise workloads. The following diagram shows the Terraform Enterprise architecture when deployed to OpenShift-orchestrated containers.

Complete the following tasks before attempting to install Terraform Enterprise.

Provide a DNS hostname for Terraform Enterprise and the associated TLS certificate. Additionally, you must configure your network so that your host can receive and send traffic. Refer to Prepare the host environment for details about preparing the host environment.

Deploy the database and other storage devices so that Terraform can connect to them when the application starts.

The example configuration deploys Terraform Enterprise to OpenShift in Azure with hosted external services. The configuration is based on cloud native hosted PostgreSQL, storage, or Redis cache services. You can copy the example configuration and modify the values to per your environment. Refer to Configuration Reference for a list of all configuration options.

The example also depends on the following conditions:

• Values under .env.variables are set as a ConfigMap and mounted as Terraform Enterprise environment variables
• Values under .env.secrets are set as Kubernetes secrets and mounted as Terraform Enterprise environment variables
• Extend the env.configMapRefs[] or env.secretRefs[] with your own resources to add additional ConfigMap or Secret resources within your environment configuration
• Values marked BASE64ENCODED* indicate that the value given must be base 64 encoded

Security Context and Custom Agent Image

Refer to the OpenShift documentation for additional information about the security context constraints.

Create a custom tfc-agent image in order to perform Terraform operations in Terraform Enterprise workspaces in compliance with the security context constraints. The image creates the default working directory for the tfc-agent and assigns permissions to the root group.

Place the following tfc-agent image configuration in a container registry that is accessible to the OpenShift nodes hosting Terraform Enterprise:

FROM hashicorp/tfc-agent USER root RUN mkdir /.tfc-agent && \ chmod og+rw /.tfc-agent && \ chmod o+rx /home/tfc-agent USER tfc-agent

Note that custom images sourced from tfc-agent cannot use automatic CA certificate injection.

As a result, you may need to add CA certificate injection configuration to the Dockerfile.

In your deployment configuration file, configure the following environment variables to enable Terraform Enterprise to use the custom image.

Refer to the deployment configuration reference for information about all configuration settings.

In your overrides YAML file, set the openshift.enabled value to true so that Terraform Enterprise starts each Terraform Enterprise service as the OpenShift-assigned container entry user ID.

openshift: enabled: true

By default, the Terraform Enterprise Helm chart applies the following security context configuration so that Terraform Enterprise complies with OpenShift's restricted security context constraint:

securityContext: seccompProfile: type: RuntimeDefault allowPrivilegeEscalation: false capabilities: drop: - ALL runAsNonRoot: true

Connect to the host instance.

Log in to the Terraform Enterprise container image registry:

cat <PATH_TO_HASHICORP_LICENSE_FILE> | docker login --username terraform images.releases.hashicorp.com --password-stdin

Pull the Terraform Enterprise image from the registry.

If you contact HashiCorp support, include your custom Helm chart alongside your support bundle to ensure support has all the information they need.

Helm Chart Customization and Overrides

Many OpenShift primitives, such as routing, are absent in the terraform-enterprise Helm chart. You can fork our Helm chart and adapt it to your organization’s requirements.

Refer to the startup checks reference for additional information.

Managing OpenShift Clusters with Terraform

This article will teach you how to create and manage OpenShift clusters with Terraform. For the purpose of this exercise, we will run OpenShift on Azure using the managed service called ARO. Cluster creation is the first part of the exercise. After that, we are going to install several operators on OpenShift and some apps that use features provided by those operators. Of course, our main goal is to do all the required steps in the single Terraform command.

In this article, I’m not promoting or recommending Terraform as the best tool for managing OpenShift or Kubernetes clusters at scale. Usually, I prefer the GitOps approach for that. If you are interested in how to leverage such tools like ACM and Argo CD for managing multiple clusters with the GitOps approach read that article. It describes the idea of a cluster continuous management. From my perspective, Terraform fits better for one-time actions, like for example, creating and configuring OpenShift for the demo or PoC and then removing it. We can also use Terraform to install Argo CD and then delegate all the next steps there.

Anyway, let’s focus on our scenario. We will widely use those two Terraform providers: Azure and Kubernetes.

ARO Provisioning and Service Mesh Automation

Here’s the aro-with-servicemesh.sh script responsible for running required Terraform commands. It is placed in the repository root directory. In the first step, we go to the aro directory to apply the script responsible for creating the Openshift cluster. The domain name is automatically generated by Terraform, so we will export it using the terraform output command. After that, we may apply the scripts with operators and Istio configuration. In order to do everything automatically we pass the location of the kubeconfig file and the generated domain name as variables.

```

! /bin/bash

cd aro
terraform init
terraform apply -auto-approve
domain="apps.$(terraform output -raw domain).eastus.aroapp.io"
cd ../servicemesh
terraform init
terraform apply -auto-approve -var kubeconfig=../aro/kubeconfig -var domain=$domain
```

Let’s run the aro-with-service-mesh.sh script. Once you will do it you should have a similar output as visible below. In the beginning, Terraform creates several objects required by the ARO cluster like a virtual network or service principal. Once those resources are ready, it starts the main part – ARO installation.

Let’s switch to Azure Portal. As you see the installation is in progress. There are several other newly created resources. Of course, there is also the resource representing the OpenShift cluster.

Now, arm yourself with patience. You can easily go get a coffee…

You can verify the progress, e.g. by displaying a list of virtual machines.

The workflow demonstrates that Terraform can orchestrate one-time creation of ARO infrastructure and subsequently feed the generated domain and kubeconfig into downstream Kubernetes provider configurations for operator and service mesh installation.

Post-Installation and Operational Considerations

After installation, the Terraform Enterprise Helm Chart is intended to meet the needs of the majority of our users. Many OpenShift primitives, such as routing, are absent in the terraform-enterprise Helm chart. You can fork our Helm chart and adapt it to your organization’s requirements.

Enable the OpenShift configuration your overrides values file so that Terraform Enterprise starts each service as the OpenShift-assigned container entry user ID.

Complete post installation tasks after the Helm chart and override values are applied.

If you contact HashiCorp support, include your custom Helm chart alongside your support bundle to ensure support has all the information they need.

Conclusion

Terraform Enterprise on OpenShift requires explicit handling of routing, security context constraints, and external dependencies that the Helm chart deliberately omits. Route exposure via oc expose, custom tfc-agent images for restricted SCC compliance, and openshift.enabled overrides are mandatory for a production-ready deployment. The chart’s reliance on external PostgreSQL, storage, and Redis services means operators must provision and scale those dependencies outside the OpenShift cluster and wire them through ConfigMaps and Secrets with correct base64 encoding.

On the infrastructure side, using Terraform to create and configure ARO clusters demonstrates a pragmatic fit for one-time demos, PoCs, and initial bootstrapping. The Azure and Kubernetes providers together allow creation of virtual networks, service principals, and the ARO control plane, followed by operator and service mesh installation driven by the generated kubeconfig and domain name. This approach aligns with the view that Terraform excels at initial provisioning and Argo CD or ACM can take over continuous cluster management thereafter. Both patterns emphasize explicit configuration, manual steps left out of upstream charts, and the need for deep OpenShift knowledge before operating Terraform Enterprise in production.

Sources

1. HashiCorp Developer
2. piotrminkowski.com