Terraform Enterprise Pod Fails to Start on OpenShift with Puma::DSL::Settings NameError

Troubleshooting

Problem

This article addresses an issue where the Terraform Enterprise application pod fails to start during a new deployment on OpenShift or other Kubernetes platforms using the official Helm chart. The pod may appear to pass initial startup checks but then enters a failed state, preventing the application from becoming operational.

Symptom

When deploying Terraform Enterprise, the main application pod does not start successfully. Reviewing the pod logs reveals that the initial startup checks pass, but are immediately followed by a repeating NameError related to Puma::DSL::Settings.

The logs display output similar to the following example, where the application status check hangs indefinitely.

$ tfectl app startup-check
startup check passed: check=cloud-sdk duration=26.939µs 
startup check passed: check=config duration=31.499µs 
startup check passed: check=database duration=112.291897ms 
startup check passed: check=disk duration=12.99µs 
startup check passed: check=license duration=419.72µs 
startup check passed: check=redis duration=124.786024ms 
startup check passed: check=tls duration=19.226µs 
startup check passed: check=upgrade duration=134.641675ms 
all startup checks passed

WARNING hook before_worker_boot failed with exception (NameError) uninitialized constant Puma::DSL::Settings
WARNING hook before_worker_boot failed with exception (NameError) uninitialized constant Puma::DSL::Settings
WARNING hook before_worker_boot failed with exception (NameError) uninitialized constant Puma::DSL::Settings

waiting for command to finish execution on node <node_name>
retrieving TFE app status
waiting for command to finish execution on node <node_name>
retrieving TFE app status

Cause

The root cause of this issue is insufficient compute resources (CPU and memory) allocated to the Terraform Enterprise pod. The official Helm chart specifies minimum resource requests and limits required for the application to boot and operate correctly. If the values in your configuration are set below these minimums, the application services, including the Puma web server, may fail to initialize, leading to the observed NameError.

The minimum requirements are 4 CPUs and 8Gi of memory.

Environment

Terraform Enterprise deployed on a Kubernetes platform, such as OpenShift.
Deployment managed using the official terraform-enterprise-helm chart.

Resolving The Problem

Solutions

The solution is to update your Helm chart configuration to allocate at least the minimum required CPU and memory resources to the Terraform Enterprise pod.

Solution 1: Increase Pod Resource Allocation

Follow these steps to review and update the resource allocation for your deployment.

Locate your Helm values.yaml file. This file contains the configuration for your Terraform Enterprise Helm release.
Review the resources section. Find the resources block in your values.yaml file. It defines the CPU and memory requests and limits for the pod.
Update the resource values. Ensure that both requests and limits for cpu and memory meet or exceed the minimum requirements. The default values in the official chart serve as a valid baseline.
```
# -- Pod resource requests and limits.
resources:
  limits:
    cpu: 4
    memory: 8Gi
  requests:
    cpu: 4
    memory: 8Gi
```
Apply the updated configuration. Use the helm upgrade command to apply the changes to your Terraform Enterprise release. Replace tfe with the name of your Helm release and hashicorp with the name of your Helm repository if they are different.
```
$ helm upgrade tfe hashicorp/terraform-enterprise -f values.yaml
```

Outcome

After you apply the updated configuration, Helm will trigger a new deployment of the Terraform Enterprise pod with the corrected resource allocation. The pod should now start successfully without the Puma::DSL::Settings error.

To verify the solution, check the status of the pod. It should transition to a Running state.

$ kubectl get pods
## NAME                               READY   STATUS    RESTARTS   AGE
## tfe-terraform-enterprise-0         1/1     Running   0          2m

You can also inspect the logs of the new pod to confirm that the application has started without any errors.

$ kubectl logs tfe-terraform-enterprise-0

Related Information

terraform-enterprise-helm

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSGH5YK","label":"IBM Terraform Self-Managed"},"ARM Category":[{"code":"a8mgJ0000000DuzQAE","label":"Terraform-\u003ETFE Infrastructure"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"1.0.0;1.0.2;1.1.0;1.2.0;2025.03;2025.04;2025.05;2025.06;2025.07"}]

Tips