How to recreate the default legacy worker or tfe agent docker image without restarting Terraform Enterprise – HashiCorp Help Center

Expected Outcome

This guide explains how to recreate the default legacy worker or tfe-agent Docker image on a running Terraform Enterprise instance without requiring a full application restart.

Prerequisites

Terraform Enterprise version v202308-1 or older.
The default legacy worker image hashicorp/build-worker:now is missing.
The default agent image hashicorp/tfe-agent:latest is missing, and the tfe-agent-setup container exists.
Access to the Terraform Enterprise instance via SSH with sufficient privileges to manage Docker containers.

Use Case

If the default worker or tfe-agent images are accidentally deleted, for example by running docker system prune or docker rmi, Terraform Enterprise runs may fail. The following procedure allows you to restore these images without service interruption. Note that this process does not apply to custom worker or agent images.

Procedure

First, connect to the Terraform Enterprise host instance using SSH.

Step 1: Recreate the Default Legacy Worker Image

To recreate the hashicorp/build-worker:now image, you must restart its corresponding container.

Restart the tfe-build-worker container. This action triggers the image build process.
```
# docker restart tfe-build-worker
```

Check the container logs to monitor the image build.

# docker logs tfe-build-worker

The output confirms that the image was successfully built and tagged.

## ...
{"@level":"info","@message":"Graceful shutdown complete, exiting.","@module":"terraform-build-worker","git_commit":"94c75da","isolation_type":"docker"}
Building build-worker image from 192.168.78.181:9874/hashicorp-ptfe-base:cd80a4e
Sending build context to Docker daemon 232.4kB
Step 1/3 : FROM 192.168.78.181:9874/hashicorp-ptfe-base:cd80a4e
---> 68c65ebd2b97
Step 2/3 : LABEL com.hashicorp.container-type=per-build
---> Using cache
---> 0c65594190ac
Step 3/3 : ADD ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
---> Using cache
---> b6fff3a5837b
Successfully built b6fff3a5837b
Successfully tagged hashicorp/build-worker:now

Verify that the hashicorp/build-worker:now image is now available locally.

# docker images --filter=reference='hashicorp/build-worker:now'

The output should list the recreated image.

REPOSITORY              TAG    IMAGE ID      CREATED       SIZE
hashicorp/build-worker  now    b6fff3a5837b  11 days ago   316MB

Step 2: Recreate the Default TFE Agent Image

To recreate the hashicorp/tfe-agent:latest image, you must start the tfe-agent-setup container.

Start the tfe-agent-setup container to initiate the image build.
```
# docker start tfe-agent-setup
```

Check the container logs to view the build progress.

# docker logs tfe-agent-setup

The output shows the image being built and tagged.

Building tfe-agent image from hashicorp/tfe-agent:latest
Sending build context to Docker daemon 225.3kB
Step 1/2 : FROM hashicorp/tfe-agent:latest
---> 7b82ae64e913
Step 2/2 : ADD ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
---> 9739e72914e1
Successfully built 9739e72914e1
Successfully tagged hashicorp/tfe-agent:latest
## ...

Verify that the hashicorp/tfe-agent:latest image is now available.

# docker images --filter=reference='hashicorp/tfe-agent:latest'

The output should list the recreated agent image.

REPOSITORY             TAG      IMAGE ID      CREATED          SIZE
hashicorp/tfe-agent    latest   e8d7202a1877  2 minutes ago    349MB

Important Considerations

For Terraform Enterprise versions v202309-1 and later, this procedure is not applicable. You must restart the Terraform Enterprise application to recreate these images.

Additional Information