Terraform Enterprise FDO docker - External log forwarding - Amazon CloudWatch – HashiCorp Help Center

Introduction

By default, Docker uses the journald logging driver. This means that for a Flexible Deployment Options (FDO) installation of Terraform Enterprise, container logs are lost whenever the container stops, restarts, or crashes.

We strongly recommend using an external log forwarding solution that aligns with your existing observability tools. Depending on your deployment platform, you can use native or third-party solutions, such as host-level monitoring agents, for log aggregation and forwarding. HashiCorp does not provide support for third-party log forwarding solutions, as noted in the External Log Forwarding documentation.

This article provides an example of how to configure external log forwarding for a Terraform Enterprise FDO Docker installation to send logs to Amazon CloudWatch.

Expected Outcome

After completing this guide, your Terraform Enterprise container will be configured to forward its logs to a specified Amazon CloudWatch log group, ensuring log persistence across container restarts.

Prerequisites

A Terraform Enterprise FDO Docker installation hosted in an AWS environment.
Access to Amazon CloudWatch in your AWS account.
An AWS IAM Role attached to the host with permissions to write to AWS CloudWatch. For more details, refer to the Docker AWSLogs driver credentials documentation.
Terraform Enterprise is managed as a systemd service, as described in the Manage the Docker Service documentation.

Use Case

A log forwarding solution provides persistence for Terraform Enterprise logs. This allows administrators to maintain a centralized log repository, which can include TFE Audit logs. Persistent logs simplify troubleshooting by preserving critical information from before a container crash or restart.

Considerations

Using AWS services like CloudWatch incurs costs. As the Terraform Enterprise administrator, you are responsible for managing CloudWatch configuration, including setting appropriate log retention policies. This guide does not configure a retention policy, meaning logs will persist indefinitely unless you manually delete them or configure a policy in AWS.

Procedure

To forward logs, you will edit the Terraform Enterprise docker-compose.yml file to use the Amazon CloudWatch Logs logging driver. This change only affects the Terraform Enterprise container and does not alter the global Docker logging driver.

Connect to the Terraform Enterprise host using SSH and switch to the root user.
```
# sudo su -
```

Edit the docker-compose.yml file to add the logging driver configuration under the tfe service definition.

logging:
  driver: "awslogs"
  options:
    awslogs-region: "<YOUR-AWS-REGION>"
    awslogs-group: "<A-NAME-FOR-TFE-LOGS-GROUP>"
    awslogs-create-group: "true"
    tag: '{{- index (split .ImageName ":") 1 -}}_{{.Name}}_{{.ID}}'

For example, if your AWS region is eu-west-1 and you name the log group tfe-node-1, the docker-compose.yml file should look similar to this.

--- 
name: "terraform-enterprise"
services:
  tfe:
    image: "images.releases.hashicorp.com/hashicorp/terraform-enterprise:v202501-1"
    logging:
      driver: "awslogs"
      options:
        awslogs-region: "eu-west-1"
        awslogs-group: "tfe-node-1"
        awslogs-create-group: "true"
        tag: '{{- index (split .ImageName ":") 1 -}}_{{.Name}}_{{.ID}}'
    environment:
    ## ...

Save the file and restart the Terraform Enterprise service to apply the changes.
```
# systemctl restart terraform-enterprise.service
```
Terraform Enterprise should start normally without errors.
Verify that logs are appearing in AWS CloudWatch.
- Open the AWS Management Console and navigate to the CloudWatch service.
- In the left navigation pane, under Logs, select Log groups.
- You should see a new log group with the name you specified (e.g., tfe-node-1).
- Click the log group name to view its log streams.
You should see a log stream with a name matching the format: TFE_Version_TFE_container_name_TFE_container_id.

This naming format is determined by the tag value in your docker-compose.yml file. You can customize the log tags or omit them entirely.
```
tag: '{{- index (split .ImageName ":") 1 -}}_{{.Name}}_{{.ID}}'
```
With this tag format, a new log stream is created each time the Terraform Enterprise container is restarted or upgraded, which helps isolate logs from different container instances.

Additional Information