How to Stop and Start the Docker Deployed Terraform Agents to Avoid Orphan Agents in the Agent Pool

Introduction

This guide describes the procedure for gracefully stopping and starting Docker-deployed Terraform agents to prevent orphaned agents from appearing in the agent pool.

Use Case

Terraform Enterprise (TFE) or HCP Terraform agents have limited management capabilities within the UI once deployed. Agents cannot be stopped or started directly from the UI. Abruptly killing the shell where an agent is running or shutting down its host instance may cause an orphan agent to remain in the agent pool. To stop agents gracefully, you must access the instance where the agent process is running.

Prerequisites

• You have agents deployed using Docker, as described in the Run an Agent Using Docker documentation.

Procedure

Follow these steps to control agent stop and start operations on the host instance.

1. Connect to the instance running the Terraform agent.

2. List the active agent containers to find the container name.

   $ docker ps

3. Stop the agent container using its name. Verify in the HCP Terraform or Terraform Enterprise UI at https://$tfe-url-name/app/$orgname/settings/agents that the agent is no longer reporting.

   $ docker stop <container-name>

4. Start the agent container.

   $ docker start <container-name>

5. Confirm the agent is running locally and reporting back to the UI. Check that the container is listed as active and then verify its status in the agent pool settings at https://$tfe-url-name/app/$orgname/settings/agents.

   $ docker ps