Skip to content

Add consul-k8s cli debug command docs #1308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add consul-k8s cli debug command docs #1308

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a837f86
add consul-k8s debug cli docs
LordAbhishek Nov 16, 2025
dc67e12
updated formatting
LordAbhishek Nov 17, 2025
869a3c4
Update suggested changes
LordAbhishek Nov 18, 2025
1e92479
minor change
LordAbhishek Nov 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 201 additions & 0 deletions content/consul/v1.22.x/content/docs/reference/cli/consul-k8s.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,7 @@ You can use the following commands with `consul-k8s`.

- [`config`](#config): Interact with helm configuration.
- [`config read`](#config-read): Read helm configuration of a Consul installation.
- [`debug`](#debug): Collect configs, logs, and other data from a Consul on Kubernetes deployment in an archive.
- [`install`](#install): Install Consul on Kubernetes.
- [`proxy`](#proxy): Inspect Envoy proxies managed by Consul.
- [`proxy list`](#proxy-list): List all Pods running proxies managed by Consul.
Expand Down Expand Up @@ -277,6 +278,206 @@ global:
name: consul
```

### `debug`

The debug command collect configs, logs, and other data from a Consul on Kubernetes deployment into an archive.

```shell-session
$ consul-k8s debug <OPTIONS>
```

The following Command options are available.

| Flag | Description | Default |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------|
| <nobr>`-duration`, `-d`</nobr> | `time.Duration` Sets the time duration to capture logs of the Consul cluster. For example, '5m' for the logs of next 5 minutes. <br/> Minimum time duration should be at least 10s. | `5m0s` |
| <nobr>`-since`, `-s`</nobr> | `time.Duration` Sets the time duration from which to start capturing logs from the Consul cluster. For example, '5m' for the logs of last 5 minutes. <br/> Minimum time duration should be at least 10s. | `0s` |
| <nobr>`-capture`, `-c`</nobr> | `String` Specifies the components to capture. Supported values are: `all`, `helm`, `crds`, `sidecar`, `pods`, `proxy`. Refer to [Capture Targets](#capture-targets) for details. <br/> You can also specify a comma-delimited list to capture component targets. <br/> For example: `consul-k8s debug -capture helm,crds` or `consul-k8s debug -capture helm -capture crds` | `all` |
| <nobr>`-output`, `-o`</nobr> | `String` Sets the full path of where to write the directory of collected data and resulting archive. <br/> Defaults to current working directory and default filename of `consul-k8s-debug-<current_timestamp>` | `<current_working_directory>/ consul-k8s-debug-<current_timestamp>`|
| <nobr>`-archive`, `-a`</nobr> | `Boolean` Enables you to archive the output debug directory into a compressed tar `.tar.gz` file. | `true` |
| <nobr>`-namespace`, `-n`</nobr> | `String` Specifies the namespace of the Consul installed components and resources. | `consul` |

The following Global options are available.

| Flag | Description | Default |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| <nobr>`-kubeconfig`</nobr> | `String` Sets the Kubernetes context to use for Consul K8s CLI operations. | none |
| <nobr>`-kubecontext`</nobr> | `String` Specifies the path to the kubeconfig file. | none |
Note: Aliases are not available for the `debug` command global options.


#### Capture Targets

You may specify the `-capture` flag multiple times to capture specific components before running the `debug` command.
Supported values are: `all`, `helm`, `crds`, `sidecar`, `pods`, `proxy`. By default, the `-capture` flag captures `all` components.

| Capture Targets | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <nobr>`helm`</nobr> | Captures the Helm release, which is an instance of a Helm chart running in your Kubernetes cluster. |
| <nobr>`crds`</nobr> | Captures both HashiCorp-specific and external CRDs installed by Consul, and list the applied resources for each CRD, such as servicerouters and apigateways. <br/> If multiple errors occur during capture, this target writes them to a single error file. |
| <nobr>`sidecar`</nobr> | Captures list of all pods across namespaces that have been injected with Consul sidecars using the label `consul.hashicorp.com/connect-inject-status=injected`. |
| <nobr>`pods`</nobr> | Captures logs from key Consul component pods: consul-server, consul-client, connect-injector, and gateways. <br/> It also records each pod’s log-capture status in an audit file. <br/> If multiple errors occur during capture, this target writes them to a single error file.|
| <nobr>`proxy`</nobr> | Captures envoy admin endpoint data (/stats, /clusters, /listeners, /config_dump) for all proxies within cluster. <br/> If multiple errors occur during capture, this target writes them to a single error file. |
| <nobr>`all`</nobr> | Captures all of the above targets. |


#### Example debug command

The following example captures everything for 10s and writes the debug bundle in `debugfile`.
Note: `-output` flag argument `debugfile` is not a complete path, so the command writes all data in the current working directory `<current_working_directory>/debugfile`.

```shell-session
$ consul-k8s debug -output debugfile -d 10s archive=false

Starting debugger:
- Output: debugfile
- Capture Targets: helm, crds, logs, sidecar, proxy
✓ Helm capture successful
✓ Crds capture successful
✓ Sidecar capture successful
✓ Proxy capture successful

Capturing pods logs.....
- Total Pods: 1x
- Total Containers: 2x
- Duration: 10s
✓ Logs capture successful
✓ Index capture successful
Saved debug directory: debugfile
```

#### Understanding debug archive directory structure

Since the `debug` command collects data from across the cluster, the archive can be large.
So, we've organized the debug bundle and its data using the following patterns
to help users navigate, read, and share different files more effectively.
Note that file structure patterns are only for `logs` and `proxy` target capture as they interact with multiple pods in a cluster.

| Capture targets | File structure patterns and naming conventions. |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <nobr>`helm`</nobr> | `debugfile/helm-config.json` |
| <nobr>`crds`</nobr> | `debugfile/CRDsResources.json` <br/> `debugfile/CRDsResourcesErrors.txt` |
| <nobr>`sidecar`</nobr> | `debugfile/sidecar-pods.json` |
| <nobr>`pods`</nobr> | pattern: <br/>`debugfile/logs/<componentType>/<componentName>/<podName>/<containerName.log>` <br/> example: <br/>`debugfile/logs/statefulsets/consul-server/consul-server-0/consul.log` <br/><br/>`debugfile/logCaptureAudit.txt` <br/> `debugfile/logCaptureErrors.txt` |
| <nobr>`proxy`</nobr> | pattern: <br/>`debugfile/proxy/<namespace>/<proxyType>/<proxyPod>/*` <br/> example: <br/> `debugfile/proxy/consul-ns/sidecar/app-sidecar/config_dumps.json` <br/> `debugfile/proxy/consul-ns/sidecar/app-sidecar/config.json`<br/> `debugfile/proxy/consul-ns/sidecar/app-sidecar/stats.json` <br/><br/>`debugfile/proxyList.json` <br/>`debugfile/proxy/proxyCaptureErrors.txt` |


#### High-level overview of the directory structure within the debug bundle

```shell-session
$ consul-k8s debug -output debugfile -d 10s archive=false
.... [ignore terminal outputs]
.... [assuming no error occured (so no error files)]
$ tree ./debugfile
.
├── CRDsResources.json
├── helm-config.json
├── index.json
├── logs
│ ├── daemonsets
│ │ └── consul-client
│ │ └── consul-client-wlcjf
│ │ ├── client-tls-init.log
│ │ └── consul.log
│ ├── deployments
│ │ ├── consul-connect-injector
│ │ │ └── consul-connect-injector-5d479ff84d-5pwqj
│ │ │ └── sidecar-injector.log
│ │ ├── consul-webhook-cert-manager
│ │ │ └── consul-webhook-cert-manager-56d6d7dd49-p2c8g
│ │ │ └── webhook-cert-manager.log
│ │ └── httpd-gateway
│ │ └── httpd-gateway-65b8ffb55c-hm8st
│ │ ├── consul-connect-inject-init.log
│ │ └── httpd-gateway.log
│ ├── logCaptureAudit.txt
│ ├── sidecars
│ │ └── sidecar
│ │ └── my-app-7bc65d4d49-smv2s
│ │ ├── consul-connect-inject-init.log
│ │ ├── consul-dataplane.log
│ │ └── my-app.log
│ └── statefulsets
│ └── consul-server
│ └── consul-server-0
│ ├── consul.log
│ └── locality-init.log
├── proxy
│ ├── consul
│ │ └── API Gateway
│ │ └── hell-gateway-b85b6644f-6wbcc
│ │ ├── config_dumps.json
│ │ ├── config.json
│ │ └── stats.json
│ ├── default
│ │ └── Sidecar
│ │ └── my-app-7bc65d4d49-smv2s
│ │ ├── config_dumps.json
│ │ ├── config.json
│ │ └── stats.json
│ └── proxyList.json
└── sidecar-pods.json
```

#### Signal interrupt

<Note>

If the debug run is interrupted, all collected data, including any partial captures, is cleaned up.
Re-run the command to collect all data, or use the `-capture` flag to specify which data to collect.

</Note>

```shell-session
$ consul-k8s debug -output debugfile -d 10s archive=false

Starting debugger:
.....
✓ Sidecar capture successful
^C !
Debug run interrupted (received signal interrupt)
- Cleaning up partial capture...
- Cleanup completed
--> Please re-run the debug command for complete capture
```

#### Example commands

The `consul-k8s debug` command collects all component data and logs for the next five minutes and writes the debug archive in the current working directory with a folder name of `consul-k8s-debug-<current_timestamp>`.
```shell-session
$ consul-k8s debug
```

This example collects all component data and logs for the next ten minutes and writes the debug archive in the current working directory with a folder name of `consul-k8s-debug-<current_timestamp>`.
```shell-session
$ consul-k8s debug -duration 10m
```

This example collects all component data and logs of the past ten minutes and writes the debug archive in the current working directory with a folder name of `consul-k8s-debug-<current_timestamp>`.
```shell-session
$ consul-k8s debug -since 10m
```

This example collects only Helm config and logs for the next five minutes and writes the debug archive in the current working directory with a folder name of `consul-k8s-debug-<current_timestamp>`.
```shell-session
$ consul-k8s debug -capture helm, logs
```

This example collects only Helm config and logs for the next five minutes and and writes the debug archive in the current working directory in a folder named `debugfile`.
```shell-session
$ consul-k8s debug -capture helm, logs -output debugfile
```

This example collects only Helm config and logs for next ten minutes and writes the debug archive to the specified output path.
```shell-session
$ consul-k8s debug -duration 10m -capture helm, logs -output ~/user/dev/desktop/consul/debugfile
```

This example collects all component data and logs for the next five minutes and writes the debug directory (not archive) in the current working directory in a folder named `consul-k8s-debug-<current_timestamp>`.
```shell-session
$ consul-k8s debug -archive=false
```

### `install`

The `install` command installs Consul on your Kubernetes cluster.
Expand Down
Loading