How to map an Agent pod to a specific Run

Introduction

When troubleshooting stuck runs in a Terraform Enterprise deployment on Kubernetes or OpenShift, you may need to locate the specific Agent pod associated with a run to investigate its logs and events.

Prerequisites

• A Terraform Enterprise instance deployed on Kubernetes or OpenShift.
• kubectl access to the cluster where the Terraform Enterprise agents are running.

Procedure

Follow these steps to identify the agent pod for a specific run.

1. From the Terraform Enterprise UI, retrieve the Run ID for the run you wish to investigate.

2. Authenticate to your cluster and use the kubectl get pods command to find the pod associated with the Run ID. Replace <agent_namespace> and <run_id> with your specific values.

   $ kubectl get pods -n <agent_namespace> --show-labels | grep <run_id>

   An example command and its output are shown below.

   $ kubectl get pods -n terraform-enterprise-agents --show-labels | grep run-V1QUQ4o12HG1evbK

   The output will include the pod name, which is the first value on the line.

   tfe-task-65aee913-5194-4b78-8715-8bdae5becc52-k5fkh   1/1   Running   0   4m4s   app=terraform-enterprise,run_id=run-V1QUQ4o12HG1evbK,...

3. Use the pod name from the previous step with the kubectl describe pod command to view detailed information and events for the pod.

   $ kubectl describe pod <pod_name> -n <agent_namespace>

   An example command and its output are shown below.

   $ kubectl describe pod tfe-task-65aee913-5194-4b78-8715-8bdae5becc52-k5fkh -n terraform-enterprise-agents

   The output may reveal scheduling issues or other problems in the Events section.

   ## ...
   Labels: app=terraform-enterprise
           ## ...
           organization_name=test_organization
           run_id=run-V1QUQ4o12HG1evbK
           run_type=Apply
           workspace_name=test_workspace
   ## ...
   Events:
     Type     Reason           Age                From               Message
     ----     ------           ----               ----               -------
     Warning  FailedScheduling 1s (x2 over 5m8s) default-scheduler  0/1 nodes are available: 1 Insufficient memory. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod.

4. Alternatively, use the kubectl logs command to view the standard output from the pod's containers.

   $ kubectl logs <pod_name> -n <agent_namespace>

Additional Information

• For more details on managing Terraform Enterprise, please refer to the official Terraform Enterprise documentation.
• For more information on kubectl commands, consult the official Kubernetes documentation.