How to connect Terraform Operator for Kubernetes to an existing agent pool

Problem

When configuring the Terraform Operator for Kubernetes to manage an existing agent pool in Terraform Enterprise, the operator fails to reconcile the AgentPool resource. The operator logs show the following error, and no agents are started.

ERROR Reconcile Agent Pool {"agentpool": {"name":"example","namespace":"orange"}, "msg": "failed to create a new agent pool", "error": "invalid attribute\n\nName is already taken within the organization"}

This occurs after applying a Kubernetes manifest for the AgentPool resource similar to the following.

apiVersion: app.terraform.io/v1alpha2
kind: AgentPool
metadata:
  name: example
  namespace: orange
spec:
  organization: test
  token:
    secretKeyRef:
      name: terraformrc
      key: token
  name: example
  agentTokens:
    - name: example
  agentDeployment:
    replicas: 1
    spec:
      containers:
        - name: tfc-agent
          image: "hashicorp/tfc-agent:1.22.2"
  ## Enable autoscaling
  autoscaling:
    minReplicas: 2
    maxReplicas: 5
    targetWorkspaces:
      - wildcardName: test*
    cooldownPeriod:
      scaleUpSeconds: 30
      scaleDownSeconds: 30

Prerequisites

• You have configured the Terraform Operator for Kubernetes as described in the official documentation.
• You have an existing agent pool in your Terraform Enterprise organization.

Cause

The Terraform Operator attempts to create a new agent pool in Terraform Enterprise using the name specified in the manifest. Because an agent pool with that name already exists, Terraform Enterprise returns a Name is already taken error, causing the reconciliation to fail.

To resolve this, you must manually patch the AgentPool Kubernetes resource to instruct the operator to adopt the existing agent pool by providing its unique ID.

Solution

Follow these steps to find the existing agent pool ID and patch the Kubernetes resource.

1. Retrieve the agent pool ID from the Terraform Enterprise UI.

   • Navigate to your organization's Settings, then Agents.
   • Select the existing agent pool you want to manage.
   • The ID is the last part of the URL, which will look similar to apool-bN3GijECCj9YmVa8.

   

2. Get the metadata.generation value from the AgentPool resource in Kubernetes. This value ensures you are patching the correct version of the resource.

   $ kubectl -n <namespace> get agentpool <metadata.name> -o yaml | grep generation

   Example:

   $ kubectl -n orange get agentpool example -o yaml | grep generation
   generation: 2

3. Patch the AgentPool resource's status with the observedGeneration and agentPoolID values you retrieved.

   $ kubectl patch -n <namespace> agentpool <metadata.name> --type=merge --subresource status --patch 'status: {observedGeneration: <metadata.generation>, agentPoolID: <agentpool_id>}'

   Example:

   $ kubectl patch -n orange agentpool example --type=merge --subresource status --patch 'status: {observedGeneration: 2, agentPoolID: apool-WGaTSkPAnPtZWXR3}'

Outcome

After patching the resource, the Terraform Operator will successfully reconcile the AgentPool and begin managing the existing pool. The agents defined in the manifest will start and connect to Terraform Enterprise.

Additional Information

• The Terraform Operator for Kubernetes GitHub repository contains further details on its configuration and usage.
• Refer to the official documentation for the Terraform Operator for more information on Kubernetes integrations.