HashiCorp Diagnostic, hcdiag
, is a universal troubleshooting data gathering tool for HashiCorp products that helps you collect and archive important data from Terraform Enterprise instances. You can share the information that hcdiag
gathers with your, or HashiCorp's, teams during incident response and troubleshooting.
For Terraform Enterprise, the hcdiag
tool executes a series of commands to collect system and production information by querying replicatedctl
and the Terraform Enterprise API. We recommend installing hcdiag
when you are experiencing an incident. By default, hcdiag
will gather up to 72 hours of server logs. This ensures that you have the latest version of hcdiag
.
In this tutorial, you will connect to your Terraform Enterprise application to install, configure, and use hcdiag
. You will gather troubleshooting information about your Terraform Enterprise application. In the process, you will learn the basic hcdiag
commands and understand the contents of files created by the tool.
»Prerequisites
To perform the steps in this tutorial, you need a Terraform Enterprise
application (Standalone or Active/Active deployment). In addition, you must also have write permissions in the directory you plan to run hcdiag
in.
»Create TFE API token
The hcdiag
tool requires an user API token to authenticate and query information from the Terraform Enterprise API. Go to the "Tokens" page of your Terraform Enterprise application and create an API token named hcdiag
.
Save this token in a safe place, you will use it later in the tutorial to authenticate hcdiag
to the Terraform Enterprise API.
»Connect to your TFE application
Open a shell session to the server your Terraform Enterprise application is running on to use hcdiag
. Use SSH or your cloud provider's session manager to connect to the Terraform Enterprise application's instances.
Once you have connected to an instance of your Terraform Enterprise application, switch to the root
user. Several commands in this tutorial are only available to the root
user.
»Configure the environment
Before you download and run hcdiag
, you must first configure your environment so that the tool knows how to communicate with and authenticate to Terraform Enterprise.
First, set the TFE_HTTP_ADDR
environment variable to your Terraform Enterprise URL. This tells hcdiag
where to query the API.
Then, set the TFE_TOKEN
environment variable to the API token you created earlier. This allows hcdiag
to authenticate to the API and query it for information.
»Install dependencies and hcdiag
Before you can download hcdiag
, you need to install the curl and unzip tools. First, update package sources.
Then, install curl
and unzip
.
You are now ready to download hcdiag
from the HashiCorp releases repository. Download the binary with curl.
Unzip and remove the archive.
Finally, add the hcdiag
executable directory to the PATH
so that you can invoke the command using just its name.
»Gather troubleshooting data
Use hcdiag
to gather all troubleshooting data for your Terraform Enterprise application. This may take several minutes.
If you invoke hcdiag
with no flags, it will gather all available environment and product information.
For a full list of options supported by hcdiag
, run hcdiag -h
.
Note: If you are concerned about impacting performance of your Terraform Enterprise instances, you can specify that the seekers to not run concurrently, and instead be invoked serially with the -serial
flag.
»Explore troubleshooting data
Notice that hcdiag
generates an archive with troubleshooting data about the Terraform Enterprise application. First, list the tar+gzip
archive files to discover the file that hcdiag
created.
The filename contains a support prefix, followed by a timestamp. Unpack the archive to further examine its contents. The --force-local
flag tells tar
to interpret the filename as a file name rather than a remote host.
The archive extracts three files into a temporary directory.
- The
Manifest.json
file contains information describing thehcdiag
run, including configuration options used, run duration, and a count of any errors encountered. - The
Results.json
file contains information about the environment and the output from thereplicatedctl support-bundle
command. - The
replicated-*.tar.gz
file contains the output from thereplicatedctl support-bundle
command
You can further explore the replicated-*.tar.gz
archive by unpacking it and examining its contents. Remember to use the --force-local
flag.
Warning: We encourage you to inspect the bundle to ensure it contains only information that is appropriate to share. The hcdiag
tool makes no attempts to obscure secrets or sensitive information.
When creating a support request for Terraform Enterprise, you can attach the artifacts the hcdiag
tool generates to reduce the time it takes to traditionally gather troubleshooting data.
The hcdiag
tool only works locally and does not export or share the diagnostic bundle with anyone. You must use other tools to transfer it to a secure location so you can share it with specific support staff who need to view it.
»Configure hcdiag behavior
You can configure hcdiag
behavior with a HashiCorp Configuration Language (HCL) formatted file.
Create a file named diag.hcl
with the following contents. This configuration instructs hcdiag
to skip the replicatedctl support-bundle
command. Ensure that the configuration file is readable by the user running hcdiag
.
Run the following command to gather troubleshooting data from your Terraform Enterprise application, skipping the CLI
gathering step.
Alternatively, you can limit what hcdiag
gathers with the -includes
flag. For example, -includes /var/log/terraform-*,
instructs hcdiag
to only gather logs matching the specified Terraform filename patterns.
In addition, use the -dryrun
flag to observe what hcdiag
will do without anything actually being done for testing configuration and options.
»Next steps
In this tutorial, you installed, configured, and used hcdiag
to gather troubleshooting information about your Terraform Enterprise application.
- Visit the
hcdiag
repository to learn more abouthcdiag
. This repository contains additional configuration options and instructions. - If you are using Terraform Enterprise and are experiencing an incident, you can submit a request with your
hcdiag
bundle on this page. Visit this Support Article to learn how to add bundles and files to support tickets through the support portal.