Skip to content

Update consul-k8s cli proxy command docs #1309

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 3 commits into
base: main
Choose a base branch
from
Open

Update consul-k8s cli proxy command docs #1309

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
22d9d69
update consul-k8s cli proxy command docs
LordAbhishek Nov 16, 2025
f154305
updated the docs
LordAbhishek Nov 17, 2025
1052cd1
Update suggested grammatical changes
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
95 changes: 89 additions & 6 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 @@ -335,7 +335,7 @@ $ consul-k8s install -set-string key=value-bool

### `proxy`

The `proxy` command exposes two subcommands for interacting with proxies managed by
The `proxy` command exposes four subcommands for interacting with proxies managed by
Consul in your Kubernetes Cluster.

- [`proxy list`](#proxy-list): List all Pods running proxies managed by Consul.
Expand Down Expand Up @@ -734,6 +734,8 @@ $ consul-k8s proxy read backend-658b679b45-d5xlb -o raw

The `proxy log` command allows you to inspect and modify the logging configuration of Envoy proxies running on a given Pod.

This command also lets you capture logs from the `control-dataplane` container of an Envoy proxy pod for the specified duration, according to existing or new logging configurations, and saves them to the `proxy` folder in `current working directory`.

```shell-session
$ consul-k8s proxy log <PODNAME> <OPTIONS>
```
Expand All @@ -745,11 +747,12 @@ the terminal displays configuration information for all proxies in the pod.

The following options are available.

| Flag | Description | Default |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| <nobr>`-namespace`, `-n`</nobr> | `String` Specifies the namespace containing the target Pod. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. |
| <nobr>`-update-level`, `-u`</nobr> | `String` Specifies the logger (optional) and the level to update. <p>Use the following format to configure the same level for loggers: `-update-level <LEVEL>`.</p> <p>You can also specify a comma-delineated list to configure levels for specific loggers, for example: `-update-level grpc:warning,http:info`.</p> | none |
| <nobr>`-reset`, `-r`</nobr> | `String` Reset the log levels for all loggers back to the default of `info` | `info` |
| Flag | Description | Default |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| <nobr>`-namespace`, `-n`</nobr> | `String` Specifies the namespace containing the target Pod. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. |
| <nobr>`-update-level`, `-u`</nobr> | `String` Specifies the logger (optional) and the level to update. <p>Use the following format to configure the same level for all loggers: `-update-level <LEVEL>`.</p> <p>You can also specify a comma-delimited list to configure levels for specific loggers, such as `-update-level grpc:warning,http:info`.</p> | none |
| <nobr>`-reset`, `-r`</nobr> | `String` Reset the log levels for all loggers back to the default of `info` | `info` |
| <nobr>`-capture`</nobr> | `time.Duration` Captures logs from the `control-dataplane` container inside the Envoy proxy pod for the specified duration, according to existing or new logging configurations, and saves them to the `proxy` folder in `current working directory`. <p> If you use the `-update-level` flag, the command temporarily applies new logging configurations, captures logs, and then reverts or restores log levels to the original levels. Otherwise, it captures logs using the existing log levels configuration.</p> <p>Saved filepath patten: `/proxy/<podname>.log`.</p> | 0s |

#### Example commands
In the following example, Consul returns the log levels for all of an Envoy proxy's loggers in a pod with the ID `server-697458b9f8-4vr29`:
Expand Down Expand Up @@ -1015,6 +1018,86 @@ kafka info
lua info
```

The following commands capture the logs of `control-dataplane` container of an Envoy proxy pod for `10s` at `existing logging configuration` and saves them to `proxy` folder in `current working directory`.

```shell-session
$ consul-k8s proxy log backend-5cc8d59bb5-ndn5j -capture 10s
Starting log capture...
Pod Name: backend-5cc8d59bb5-ndn5j
Container Name: consul-dataplane
Namespace: default
Log Capture Duration: 10s
Log File Path: proxy/proxy-log-backend-5cc8d59bb5-ndn5j.log
✓ Logs saved to 'proxy/proxy-log-backend-5cc8d59bb5-ndn5j.log'

$ cat proxy/proxy-log-backend-5cc8d59bb5-ndn5j.log
2025-09-28T22:14:11.888675010Z 2025-09-28T22:14:11.887Z+00:00 [debug] envoy.http(31) [Tags: "ConnectionId":"108425"] new stream
2025-09-28T22:14:11.888895343Z 2025-09-28T22:14:11.888Z+00:00 [debug] envoy.http(31) [Tags: "ConnectionId":"108425","StreamId":"1388978360429204234"] request headers complete (end_stream=true):
2025-09-28T22:14:11.888911552Z ':authority', '10.244.0.58:20200'
2025-09-28T22:14:11.888917093Z ':path', '/metrics'
2025-09-28T22:14:11.888920635Z ':method', 'GET'
....
2025-09-28T22:14:11.893417552Z
2025-09-28T22:14:11.893421927Z 2025-09-28T22:14:11.893Z+00:00 [debug] envoy.http(19) [Tags: "ConnectionId":"106890","StreamId":"3687233536774944639"] request headers complete (end_stream=true):
```

The following commands capture the logs of `control-dataplane` container of an Envoy proxy pod for `10s` at `new logging configuration` provided via `-update-level` flag and saves them to the `proxy` folder in the `current working directory`.

```shell-session
$ consul-k8s proxy log backend-5cc8d59bb5-ndn5j -capture 10s -update-level grpc:critical,http:warning,forward_proxy:trace,upstream:debug,rbac:error
Fetching existing log levels...
Setting new log levels...
Envoy log configuration for backend-5cc8d59bb5-ndn5j in namespace default:

==> Log Levels for backend-5cc8d59bb5-ndn5j
Name Level
config warning
envoy_bug warning
forward_proxy trace
init warning
mongo warning
rds warning
runtime debug
......
......
stats warning
rbac error
admin warning
compression info
grpc critical
udp warning
credential_injector info
ext_authz warning
jwt warning
pool warning
wasm warning
http2 warning
kafka warning
dynamic_modules info
aws error
basic_auth info
health_checker warning
upstream debug
decompression warning

Starting log capture...
Pod Name: backend-5cc8d59bb5-ndn5j
Container Name: consul-dataplane
Namespace: default
Log Capture Duration: 10s
Log File Path: proxy/proxy-log-backend-5cc8d59bb5-ndn5j.log
✓ Logs saved to 'proxy/proxy-log-backend-5cc8d59bb5-ndn5j.log'
Resetting log levels back to existing levels...
Reset completed successfully!

$ cat proxy/proxy-log-backend-5cc8d59bb5-ndn5j.log
2025-09-28T22:30:30.800474005Z 2025-09-28T22:30:30.800Z [ERROR] consul-dataplane.dns-proxy.udp: error resolving consul request: error="rpc error: code = Unavailable desc = name resolver error: produced zero addresses"
2025-09-28T22:30:30.800545838Z 2025-09-28T22:30:30.800Z [ERROR] consul-dataplane.dns-proxy.udp: error resolving consul request: error="rpc error: code = Unavailable desc = name resolver error: produced zero addresses"
.....
2025-09-28T22:30:35.803969757Z 2025-09-28T22:30:35.803Z [INFO] consul-dataplane.server-connection-manager: connected to Consul server: address=10.244.0.110:8502
2025-09-28T22:30:35.804500465Z 2025-09-28T22:30:35.804Z [INFO] consul-dataplane.server-connection-manager: updated known Consul servers from watch stream: addresses=[10.244.0.110:8502]
```

### `proxy stats`

The `proxy stats` command allows you to inspect the Envoy cluster stats for Envoy proxies running on a given Pod.
Expand Down
Loading