TFC Agent Fails to Start with Error: "permission denied"

Introduction

Starting with tfc-agent version 1.19.0, the base operating system was upgraded from Ubuntu 20.04.6 LTS (Focal Fossa) to Ubuntu 24.04.1 LTS (Noble Numbat).

As part of this update, the default permissions on the /home/tfc-agent/ directory changed. Previously, the directory was accessible by other users. Access is now restricted, as shown by the following permissions:

drwxr-x--- 1 tfc-agent tfc-agent 4.0K Feb 5 20:23 tfc-agent

This change may cause issues when you use the TFC Agent in Terraform Enterprise (TFE) on OpenShift, particularly during terraform plan or terraform apply operations. You may encounter a permissions error when the agent container is launched.

Problem

If you build custom tfc-agent Docker images and run them in OpenShift, you may encounter an error similar to this:

Warning Failed pod/tfe-task-xxxxxx Error: container create failed:
time="2025-05-02T12:31:14Z" level=error msg="runc create failed:
unable to start container process: exec: \"/home/tfc-agent/bin/tfc-agent\":
stat /home/tfc-agent/bin/tfc-agent: permission denied"

Prerequisites

This issue only impacts tfc-agent version 1.19.0 and newer.

Cause

The updated permissions on /home/tfc-agent restrict access to users who are not part of the tfc-agent group. This prevents the container runtime from executing the tfc-agent binary located at /home/tfc-agent/bin/tfc-agent.

Solution

To resolve the issue, update your custom tfc-agent Dockerfile to grant read and execute permissions to others on the /home/tfc-agent directory.

Update your Dockerfile with the following command.

FROM hashicorp/tfc-agent

USER root

RUN mkdir /.tfc-agent && \
    chmod 770 /.tfc-agent && \
    chmod o+rx /home/tfc-agent ## Grants necessary permissions for container runtime

USER tfc-agent

This change ensures the container runtime can successfully execute the agent binary.

Outcome

After applying this change, the TFC Agent container should start successfully, and terraform plan and terraform apply operations will run without permission-related errors.