Resolving Unauthorized Errors in Terraform Enterprise Agent Pools

Problem

When you attempt to configure agent pools and agents to trigger Terraform runs in your self-hosted Terraform Enterprise instance, you may encounter an "unauthorized" status with the error message "Failed to create a new agent pool".

Cause

This error typically occurs because the HCP Terraform Operator, by default, is configured to communicate with the HCP Terraform endpoint at app.terraform.io. If you are using a self-hosted Terraform Enterprise (TFE) instance, the agent pool manifest does not have an explicit attribute to specify your custom TFE address.

For example, the manifest below is configured for the default endpoint, not a custom TFE instance.

apiVersion: app.terraform.io/v1alpha2
kind: AgentPool
metadata:
  name: agent-pool-demo
spec:
  organization: ORGANIZATION_NAME
  token:
    secretKeyRef:
      name: terraformrc
      key: token
  name: agent-pool-demo
  agentTokens:
  - name: agent-pool-demo-token
  agentDeployment:
    replicas: 1
    spec:
      containers:
      - name: tfc-agent
        image: "hashicorp/tfc-agent:1.13.1"

Solution

To resolve this issue, you must configure the HCP Terraform Operator to recognize your TFE instance by specifying the TFE address during the Helm installation.

1. Install the HCP Terraform Operator using Helm. Include the operator.tfeAddress flag to point to your TFE instance and the customCAcertificates flag if you use a custom certificate authority.

   $ helm install tfe-operator hashicorp/hcp-terraform-operator \
       --version 2.7.0 \
       --namespace ns-tfe-operator \
       --set operator.tfeAddress="https://your-tfe-domain.com" \
       --set customCAcertificates="$(cat /path/to/your/cert/ca_cert.crt)"

   Replace https://your-tfe-domain.com with your TFE domain and /path/to/your/cert/ca_cert.crt with the path to your certificate file.

2. Ensure your certificate file (PEM or CRT) includes the full certificate chain, including the CA certificate and the leaf certificate.
3. After the operator is installed successfully, apply your agent pool YAML manifest in the same namespace where you created the token.

Additional Information

For a detailed guide on using the operator, refer to the Kubernetes Operator for HCP Terraform tutorial.