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.jsonfile contains information describing thehcdiagrun, including configuration options used, run duration, and a count of any errors encountered. - The
Results.jsonfile contains information about the environment and the output from thereplicatedctl support-bundlecommand. - The
replicated-*.tar.gzfile contains the output from thereplicatedctl support-bundlecommand
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
hcdiagrepository 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
hcdiagbundle on this page. Visit this Support Article to learn how to add bundles and files to support tickets through the support portal.
