Skip to content

Commit a837f86

Browse files
LordAbhishekLordAbhishek
committed
add consul-k8s debug cli docs
1 parent e5400eb commit a837f86

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

‎content/consul/v1.22.x/content/docs/reference/cli/consul-k8s.mdx‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,7 @@ You can use the following commands with `consul-k8s`.
220220

221221
- [`config`](#config): Interact with helm configuration.
222222
- [`config read`](#config-read): Read helm configuration of a Consul installation.
223+
- [`debug`](#debug): Collect configs, logs, and other data from a Consul on Kubernetes deployment in a archive/dir.
223224
- [`install`](#install): Install Consul on Kubernetes.
224225
- [`proxy`](#proxy): Inspect Envoy proxies managed by Consul.
225226
- [`proxy list`](#proxy-list): List all Pods running proxies managed by Consul.
@@ -277,6 +278,205 @@ global:
277278
name: consul
278279
```
279280

281+
### `debug`
282+
283+
The debug command collect configs, logs, and other data from a Consul on Kubernetes deployment in a archive/dir.
284+
285+
```shell-session
286+
$ consul-k8s debug <OPTIONS>
287+
```
288+
289+
The following Command options are available.
290+
291+
| Flag | Description | Default |
292+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------|
293+
| <nobr>`-duration`, `-d`</nobr> | `time.Duration` Sets the time duration to capture logs of consul cluster. (e.g., '5m' for the logs of next 5 minutes). <br/> Minimum time duration should be atleast 10s. | `5m0s` |
294+
| <nobr>`-since`, `-s`</nobr> | `time.Duration` Sets the time duration from which to start capturing logs from consul cluster. (e.g., '5m' for the logs of last 5 minutes). <br/> Minimum time duration should be atleast 10s. | none |
295+
| <nobr>`-capture`, `-c`</nobr> | `String` Specifies the components to capture. Supported values are: all, helm, crds, sidecar, pods, proxy. See [Capture Targets](#capture-targets) for more. <br/> You can also specify a comma-delineated list to capture components (capture targets). <br/> e.g., `consul-k8s debug -capture helm,crds` or `consul-k8s debug -capture helm -capture crds` | all |
296+
| <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 will be consul-k8s-debug-'current-timestamp' | current working directory |
297+
| <nobr>`-archive`, `-a`</nobr> | `Boolean` Enables you to archive the output debug directory into a compressed tar `.tar.gz` file. | `true` |
298+
| <nobr>`-namespace`, `-n`</nobr> | `String` Specifies the namespace of the Consul installed components and resources. | `consul` |
299+
300+
The following Global options are available.
301+
302+
| Flag | Description | Default |
303+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
304+
| <nobr>`-kubeconfig`</nobr> | `String` Sets the Kubernetes context to use for Consul K8s CLI operations. | none |
305+
| <nobr>`-kubecontext`</nobr> | `String` Specifies the path to the kubeconfig file. | none |
306+
307+
308+
#### Capture Targets
309+
310+
The -capture flag can be specified multiple times to capture specific components when debug is running.
311+
Supported values are: all, helm, crds, sidecar, pods, proxy. By default, it captures all components.
312+
313+
| Capture Targets | Description |
314+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
315+
| <nobr>`helm`</nobr> | Captures the Helm release, which is an instance of a Helm chart running in your Kubernetes cluster. |
316+
| <nobr>`crds`</nobr> | Captures both HashiCorp-specific and external CRDs installed by Consul, and list the applied resources for each CRD (e.g., servicerouters, apigateways). <br/> If multiple errors occured, they are captured in a single file. |
317+
| <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. |
318+
| <nobr>`pods`</nobr> | Captures logs from key Consul components: consul-server, consul-client, connect-injector & gateways. <br/> Captures 'log capture status' in an audit file. <br/> If multiple errors occured, they are captured in a single file. |
319+
| <nobr>`proxy`</nobr> | Captures envoy admin endpoint data (/stats, /clusters, /listeners, /config_dump) for all proxies within cluster. <br/> If multiple errors occured, they are captured in a single file. |
320+
| <nobr>`all`</nobr> | Captures all of the above targets. |
321+
322+
323+
#### Sample Debug command
324+
325+
Below command will capture everything for 10s and write the debug bundle in `debugfile`.
326+
Please Note: `-output` `debugfile` is not a complete path, so command will write all data in current working dir `cwd/debugfile`.
327+
328+
```shell-session
329+
$ consul-k8s debug -output debugfile -d 10s archive=false
330+
331+
Starting debugger:
332+
- Output: debugfile
333+
- Capture Targets: helm, crds, logs, sidecar, proxy
334+
✓ Helm capture successful
335+
✓ Crds capture successful
336+
✓ Sidecar capture successful
337+
✓ Proxy capture successful
338+
339+
Capturing pods logs.....
340+
- Total Pods: 1x
341+
- Total Containers: 2x
342+
- Duration: 10s
343+
✓ Logs capture successful
344+
✓ Index capture successful
345+
Saved debug directory: debugfile
346+
```
347+
348+
#### Understanding debug Archive/Directory structure
349+
350+
Since the debug command collects data from across the cluster, it can be very big archive. So, we've organized the debug bundle and its data using the following patterns
351+
to help users navigate, read, and share different files more effectively.
352+
Please note that file structure pattern are for logs and proxy target capture as they interact will multiple pods.
353+
354+
| Capture Targets | File structure patterns and naming conventions. |
355+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
356+
| <nobr>`helm`</nobr> | `debugfile/helm-config.json` |
357+
| <nobr>`crds`</nobr> | `debugfile/CRDsResources.json` <br/> `debugfile/CRDsResourcesErrors.txt` |
358+
| <nobr>`sidecar`</nobr> | `debugfile/sidecar-pods.json` |
359+
| <nobr>`pods`</nobr> | pattern: `debugfile/logs/<componentType>/<componentName>/<podName>/<containerName.log>`, <br/> e.g., `debugfile/logs/statefulsets/consul-server/consul-server-0/consul.log` <br/><br/>`debugfile/logCaptureAudit.txt` <br/> `debugfile/logCaptureErrors.txt` |
360+
| <nobr>`proxy`</nobr> | pattern: `debugfile/proxy/<namespace>/<proxyType>/<proxyPod>/*`, <br/><br/>`debugfile/proxyList.json` <br/>`debugfile/proxy/proxyCaptureErrors.txt` |
361+
362+
363+
#### High-level overview of the directory structure within the debug bundle
364+
365+
```shell-session
366+
$ consul-k8s debug -output debugfile -d 10s archive=false
367+
.... [ignore terminal output]
368+
$ tree ./debugfile
369+
.
370+
├── CRDsResources.json
371+
├── helm-config.json
372+
├── index.json
373+
├── logs
374+
│ ├── daemonsets
375+
│ │ └── consul-client
376+
│ │ └── consul-client-wlcjf
377+
│ │ ├── client-tls-init.log
378+
│ │ └── consul.log
379+
│ ├── deployments
380+
│ │ ├── consul-connect-injector
381+
│ │ │ └── consul-connect-injector-5d479ff84d-5pwqj
382+
│ │ │ └── sidecar-injector.log
383+
│ │ ├── consul-webhook-cert-manager
384+
│ │ │ └── consul-webhook-cert-manager-56d6d7dd49-p2c8g
385+
│ │ │ └── webhook-cert-manager.log
386+
│ │ ├── httpd-gateway
387+
│ │ │ └── httpd-gateway-65b8ffb55c-hm8st
388+
│ │ │ ├── consul-connect-inject-init.log
389+
│ │ │ └── httpd-gateway.log
390+
│ │ └── prometheus-server
391+
│ │ └── prometheus-server-cbb6db47d-mjb4z
392+
│ │ ├── prometheus-server-configmap-reload.log
393+
│ │ └── prometheus-server.log
394+
│ ├── logCaptureAudit.txt
395+
│ ├── sidecars
396+
│ │ └── sidecar
397+
│ │ └── my-app-7bc65d4d49-smv2s
398+
│ │ ├── consul-connect-inject-init.log
399+
│ │ ├── consul-dataplane.log
400+
│ │ └── my-app.log
401+
│ └── statefulsets
402+
│ └── consul-server
403+
│ └── consul-server-0
404+
│ ├── consul.log
405+
│ └── locality-init.log
406+
├── proxy
407+
│ ├── consul
408+
│ │ └── API Gateway
409+
│ │ └── hell-gateway-b85b6644f-6wbcc
410+
│ │ ├── config_dumps.json
411+
│ │ ├── config.json
412+
│ │ └── stats.json
413+
│ ├── default
414+
│ │ └── Sidecar
415+
│ │ └── my-app-7bc65d4d49-smv2s
416+
│ │ ├── config_dumps.json
417+
│ │ ├── config.json
418+
│ │ └── stats.json
419+
│ └── proxyList.json
420+
└── sidecar-pods.json
421+
```
422+
423+
#### Signal Interrupt
424+
425+
<Note>
426+
If the debug run is interrupted, all collected data—including any partial captures—will be cleaned up.
427+
Please re-run the command to collect all data, or use the `-capture` flag to specify which data to collect.
428+
</Note>
429+
430+
```shell-session
431+
$ consul-k8s debug -output debugfile -d 10s archive=false
432+
433+
Starting debugger:
434+
.....
435+
✓ Sidecar capture successful
436+
^C !
437+
Debug run interrupted (received signal interrupt)
438+
- Cleaning up partial capture...
439+
- Cleanup completed
440+
--> Please re-run the debug command for complete capture
441+
```
442+
443+
#### Example Commands
444+
445+
Below command collects every component data and logs for next 5 miunutes and writes the debug archive in current working directory with foldername as consul-k8s-debug-currentTimestamp.
446+
```shell-session
447+
$ consul-k8s debug
448+
```
449+
450+
Below command collects every component data and logs for next 10 minutes and writes the debug archive in current working directory with foldername as consul-k8s-debug-currentTimestamp.
451+
```shell-session
452+
$ consul-k8s debug -duration 10m
453+
```
454+
455+
Below command collects every component data and logs of past 10 minutes and writes the debug archive in current working directory with foldername as consul-k8s-debug-currentTimestamp.
456+
```shell-session
457+
$ consul-k8s debug -since 10m
458+
```
459+
460+
Below command collects only helm data and logs for next 5 minutes and writes the debug archive in current working directory with foldername as consul-k8s-debug-currentTimestamp.
461+
```shell-session
462+
$ consul-k8s debug -capture helm, logs
463+
```
464+
465+
Below command collects only helm data and logs for next 10 minutes and and writes the debug archive in current working directory with foldername as debugfile
466+
```shell-session
467+
$ consul-k8s debug -capture helm, logs -output debugfile
468+
```
469+
470+
Below command collects only helm data and logs for next 10 minutes and and writes the debug archive at the given path with foldername as debugfile
471+
```shell-session
472+
$ consul-k8s debug -capture helm, logs -output ~/user/dev/desktop/consul/debugfile
473+
```
474+
475+
Below command collects every component data and logs for next 5 miunutes and writes the debug directory (not archive) in current working directory with foldername as consul-k8s-debug-currentTimestamp
476+
```shell-session
477+
$ consul-k8s debug -archive=false
478+
```
479+
280480
### `install`
281481

282482
The `install` command installs Consul on your Kubernetes cluster.

0 commit comments

Comments
 (0)