Problem
When using a custom HCP Terraform agent image with hooks in a Kubernetes environment, the hooks execute as expected. However, when deploying the same custom image on OpenShift, the hooks fail to execute.
Prerequisites
- A custom HCP Terraform agent image designed to run on OpenShift.
Cause
OpenShift manages container permissions and security contexts more strictly than standard Kubernetes environments. It often runs containers with a random user ID, which can prevent the tfc-agent process from accessing the hooks directory if it is created in a standard user's home directory.
For more details on OpenShift's security model, refer to the OpenShift Container Platform documentation.
A Dockerfile that works on Kubernetes but fails on OpenShift may resemble the following, as it places hooks in the tfc-agent user's home directory.
FROM hashicorp/tfc-agent:latest USER root RUN mkdir -p /home/tfc-agent/.tfc-agent ADD --chown=tfc-agent:tfc-agent hooks /home/tfc-agent/.tfc-agent/hooks USER tfc-agent
Solutions
To resolve this issue, you must modify the Dockerfile to create the hooks directory in a location accessible to the user ID assigned by OpenShift at runtime.
Solution 1: Modify the Dockerfile for OpenShift Permissions
Alter the custom HCP Terraform agent Dockerfile to create the .tfc-agent directory at the root level and set permissive ownership and permissions. This ensures the agent can access the hooks regardless of the user ID it runs as.
Update your Dockerfile with the following content.
FROM hashicorp/tfc-agent:latest
USER root
RUN mkdir /.tfc-agent && \
chmod 770 /.tfc-agent
ADD hooks /.tfc-agent/hooks
USER tfc-agentAfter building and deploying the agent with this new image, the hooks will execute correctly on OpenShift.
Additional Information
- For more information on agent customization, refer to the official HCP Terraform agent hooks documentation.