The information contained in this article has been verified as up-to-date on the date of the original publication of the article.  HashiCorp endeavors to keep this information up-to-date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only.  Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction

The consul-k8s-gather.sh script automates the process of gathering common troubleshooting information for HashiCorp Consul on Kubernetes or OpenShift. It also checks for (and optionally installs) the consul-k8s CLI if it is missing. This script captures various details such as:

• Consul-K8s CLI status
• Proxy list in a target namespace
• Proxy configuration, stats, and logs for each discovered proxy

Once complete, it compiles all the gathered data into a compressed .tar.gz archive for easy sharing and review.

Expected Outcome

Upon successful execution of the consul-k8s-gather.sh script, you can expect the following outcomes:

1. Consul-K8s CLI Verification/Installation:

   • The script will first check if the consul-k8s command-line interface is present in your system's PATH.
   • If the CLI is not found, the script will attempt to automatically download and install it for macOS or common Linux distributions (Ubuntu/Debian/CentOS/RHEL).
   • If automatic installation fails, the script will halt and provide clear instructions on how to manually install the consul-k8s CLI.

2. Data Collection:

   • The script will gather various troubleshooting data related to Consul on Kubernetes within the specified namespace (defaulting to default if not provided).
   • This data will include:
     • The output of consul-k8s status.
     • A list of all Consul proxies running in the target namespace (consul-k8s proxy list).
     • For each discovered proxy (or proxies matching the --service filter):
       • Its configuration in tabular, JSON, and raw formats.
       • Real-time statistics.
       • The current log levels.
       • Details for troubleshooting upstream connections.

3. Organized Output Directory:

   • All the collected data will be organized and stored in a newly created directory named following the pattern: consul_k8s_support_<namespace>_<timestamp>. The <namespace> will reflect the target namespace, and <timestamp> will indicate when the script was run.

4. Compressed Archive:

   • In addition to the raw data directory, the script will create a compressed archive file in the .tar.gz format. This archive will contain all the contents of the aforementioned directory. The filename of the archive will also follow a similar pattern: consul_k8s_support_<namespace>_<timestamp>.tar.gz.

5. Actionable Archive:

   • The resulting .tar.gz archive will be readily available for sharing. This single file will contain a comprehensive snapshot of your Consul-K8s environment's proxy status, configuration, and logs, making it easy to provide to HashiCorp Support for analysis and troubleshooting.

In summary, the expected outcome is a neatly packaged .tar.gz archive containing detailed information about your Consul-K8s deployment, facilitating efficient troubleshooting and support interactions.

Prerequisites

1. Kubernetes/OpenShift cluster running HashiCorp Consul.
2. kubectl or oc CLI configured and authorized to access the cluster.
3. Access to a Unix-like environment (Linux/macOS or WSL for Windows).
4. (Optional) consul-k8s CLI installed. If you don’t have it installed, the script will attempt to install it for you.

Procedure

Script Usage

Below is the usage text embedded within the script:

Usage: consul-k8s-gather.sh [--namespace <NAMESPACE>] [--context <CONTEXT>] [--service <NAME>] [--help]

Ensures consul-k8s CLI is installed, then collects data for proxies in a namespace.

Options:
  --namespace <NAMESPACE>      Kubernetes namespace (default: "default").
  --context <CONTEXT>          Kube context to use (default: current context).
  --service <NAME>             Only collect data for pods whose names contain <NAME>.
  --help                       Show usage info.

Examples:
  # Collect data from the default namespace, using current context:
  ./consul-k8s-gather.sh

  # Collect data from namespace 'consul' using an alternate kube context:
  ./consul-k8s-gather.sh --namespace consul --context my-context

  # Collect data only for a specific service substring match (e.g. "frontend"):
  ./consul-k8s-gather.sh --namespace production --service frontend

Step-by-Step Instructions

1. Download the Script
   Save the consul-k8s-gather.sh script to your local machine:

   curl -sSfL -o consul-k8s-gather.sh https://gist.githubusercontent.com/natemollica-nm/f27a084ac5173c08b605c28463ecc913/raw/284dcf646755e7e736f35206fd92822b0d05bc39/consul-k8s-gather.sh

2. Make sure it is executable by running:

   chmod +x consul-k8s-gather.sh
   

3. Run the Script
   In a terminal, navigate to the directory containing the script and run (as an example):

   ./consul-k8s-gather.sh --namespace my-consul-ns
   

   • If you need to specify a particular kube context (e.g., my-context), add --context my-context.
   • To filter by proxy name, add --service <substring> (e.g., --service payment).

4. Review the Output

   • The script creates a folder named consul_k8s_support_<namespace>_<timestamp> containing the raw troubleshooting data.
   • It also creates a .tar.gz archive containing the same information, which you can upload or email for support.

5. Share the Archive
   If requested by support, share the .tar.gz file. This will provide HashiCorp Support with a comprehensive snapshot of your environment’s Consul-K8s proxies.

Common Questions

How do I know if consul-k8s was successfully installed?

When the script runs, it either:

• Detects an existing consul-k8s installation, or
• Installs it automatically (if your OS is recognized and sudo/Homebrew is available).

If installation fails, the script will inform you, and you can follow HashiCorp’s official CLI installation instructions to install manually.

What if I see “No proxies found in namespace”?

This generally means no Consul proxies are running in the specified namespace (or none match your --service substring).

Double-check:

• That you’re using the correct namespace.
• The proxy pods exist and are running.

What about Windows?

If you’re on Windows, you can run this script under Windows Subsystem for Linux (WSL) or in a container-based environment that has Linux utilities. The script relies on Bash and common Linux/macOS commands, so it isn’t directly compatible with Windows Command Prompt or PowerShell.

That’s it! You should now have everything needed to gather Consul-K8s cluster information quickly using the consul-k8s-gather.sh script. If you run into any issues or have additional questions, please reach out to our support team for further assistance.

Additional Information

• Script location: scripts/consul-k8s-gather.sh
• Install consul-k8s CLI