Problem
When running a custom Bash script from an HCP Terraform agent, the script may fail to authenticate with external services like Microsoft Azure. This can occur even if the required credentials (e.g., ARM_CLIENT_ID, ARM_CLIENT_SECRET) are correctly configured as environment variables in the HCP Terraform workspace.
Prerequisites
- An active HCP Terraform organization with a configured agent pool.
- A self-hosted HCP Terraform agent running in your environment.
- An Azure Service Principal with the necessary permissions for the script's tasks.
- The Azure CLI (
az) installed in the agent's execution environment.
Cause
HCP Terraform agents use a specific API token to communicate with the HCP Terraform platform. This token is scoped to the agent's organization and cannot be used to authenticate directly with external APIs, such as the Azure API. The script execution environment is distinct from the workspace's variable context, so authentication must be explicitly performed within the script itself.
Solution
To resolve this issue, you must explicitly authenticate with Azure from within your Bash script.
-
Verify Script Permissions
Ensure the Bash script has the necessary executable permissions. The HCP Terraform Agent runs as the non-root
tfc-agentuser inside its container. You may need to adjust file permissions to allow this user to execute your script. For more details, refer to the agent launch documentation. -
Authenticate within the Script
Modify your script to perform an explicit login to Azure using the service principal credentials provided by the HCP Terraform workspace as environment variables. Add the following command to the beginning of your script.
$ az login --service-principal -u $ARM_CLIENT_ID -p $ARM_CLIENT_SECRET --tenant $ARM_TENANT_ID
After this command successfully executes, subsequent commands in your script will be authenticated to interact with Azure resources.