The Consul on Kubernetes CLI tool enables you to manage Consul with the `consul-k8s` command instead of direct interaction with Helm, kubectl, or Consul’s CLI. Learn about commands, their flags, and review examples in this reference guide.
| <nobr>`-auto-approve`</nobr> | Boolean value that enables you to skip the installation confirmation prompt. | `false` |
| <nobr>`-dry-run`</nobr> | Boolean value that validates the installation and returns a summary. | `false` |
| <nobr>`-config-file`</nobr> | String value that specifies the path to a file containing custom installation configurations, e.g., Consul Helm chart values file. <br/> You can use the `-config-file` flag multiple times to specify multiple files. | none |
| <nobr>`-namespace`</nobr> | String value that specifies the namespace of the Consul installation. | `consul` |
| <nobr>`-preset`</nobr> | String value that installs Consul based on a preset configuration. You can specify the following values: <br/> `demo`: Installs a single replica server with sidecar injection enabled; useful for testing service mesh functionality. <br/> `secure`: Installs a single replica server with sidecar injection, ACLs, and TLS enabled; useful for testing service mesh functionality. | Configuration of the Consul Helm chart. |
| <nobr>`-set`</nobr> | String value that enables you to set a customizable value. This flag is comparable to the `helm install --set` flag. <br/> You can use the `-set` flag multiple times to set multiple values. <br/> Consul Helm chart values are supported. | none |
| <nobr>`-set-file`</nobr> | String value that specifies the name of an arbitrary config file. This flag is comparable to the `helm install --set-file` <br/> flag. The contents of the file will be used to set a customizable value. You can use the `-set-file` flag multiple times to specify multiple files. <br/> Consul Helm chart values are supported. | none |
| <nobr>`-set-string`</nobr> | String value that enables you to set a customizable string value. This flag is comparable to the `helm install --set-string` <br/> flag. You can use the `-set-string` flag multiple times to specify multiple strings. <br/> Consul Helm chart values are supported. | none |
| <nobr>`-timeout`</nobr> | Specifies how long to wait for the installation process to complete before timing out. The value is specified with an integer and string value indicating a unit of time. <br/> The following units are supported: <br/> `ms` (milliseconds)<br/>`s` (seconds)<br/>`m` (minutes) <br/>In the following example, installation will timeout after one minute:<br/> `consul-k8s install -timeout 1m` | `10m` |
| <nobr>`-wait`</nobr> | Boolean value that determines if Consul should wait for resources in the installation to be ready before exiting the command. | `true` |
| <nobr>`-verbose`, `-v`</nobr> | Boolean value that specifies whether to output verbose logs from the install command with the status of resources being installed. | `false` |
| <nobr>`-help`, `-h`</nobr> | Prints usage information for this option. | none |
The following example commands install Consul on Kubernetes using custom values, files, or strings that are set via flags. The underlying Consul-on-Kubernetes Helm chart uses the flags to customize the installation. The flags are comparable to the `helm install` [flags](https://helm.sh/docs/helm/helm_install/#helm-install).
| <nobr>`-all-namespaces`, `-A`</nobr> | `Boolean` List pods in all Kubernetes namespaces. | `false` |
| <nobr>`-namespace`, `-n`</nobr> | `String` The Kubernetes namespace to list proxies in. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. |
Consul clusters connected using mesh federation. Read more about [Consul Mesh Federation](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes).
| <nobr>`-namespace`, `-n`</nobr> | `String` The namespace where the target Pod can be found. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. |
| <nobr>`-output`, `-o`</nobr> | `String` Output the Envoy configuration as 'table', 'json', or 'raw'. | `'table'` |
| <nobr>`-clusters`</nobr> | `Boolean` Filter output to only show clusters. | `false` |
| <nobr>`-endpoints`</nobr> | `Boolean` Filter output to only show endpoints. | `false` |
| <nobr>`-listeners`</nobr> | `Boolean` Filter output to only show listeners. | `false` |
| <nobr>`-routes`</nobr> | `Boolean` Filter output to only show routes. | `false` |
| <nobr>`-secrets`</nobr> | `Boolean` Filter output to only show secrets. | `false` |
| <nobr>`-address`</nobr> | `String` Filter clusters, endpoints, and listeners output to only those with endpoint addresses which contain the given value. | `""` |
| <nobr>`-fqdn`</nobr> | `String` Filter cluster output to only clusters with a fully qualified domain name which contains the given value. | `""` |
| <nobr>`-port`</nobr> | `Int` Filter endpoints output to only endpoints with the given port number. | `-1` which does not filter by port |
| <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` |
#### 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`:
```shell-session
$ consul-k8s proxy log server-697458b9f8-4vr29
Envoy log configuration for server-697458b9f8-4vr29 in namespace default:
==> Log Levels for server-697458b9f8-4vr29
Name Level
rds info
backtrace info
hc info
http info
io info
jwt info
rocketmq info
matcher info
runtime info
redis info
stats info
tap info
alternate_protocols_cache info
grpc info
init info
quic info
thrift info
wasm info
aws info
conn_handler info
ext_proc info
hystrix info
tracing info
dns info
oauth2 info
connection info
health_checker info
kafka info
mongo info
config info
admin info
forward_proxy info
misc info
websocket info
dubbo info
happy_eyeballs info
main info
client info
lua info
udp info
cache_filter info
filter info
multi_connection info
quic_stream info
router info
http2 info
key_value_store info
secret info
testing info
upstream info
assert info
ext_authz info
rbac info
decompression info
envoy_bug info
file info
pool info
```
The following command updates the log levels for all loggers of an Envoy proxy to `warning`.
Envoy log configuration for server-697458b9f8-4vr29 in namespace default:
==> Log Levels for server-697458b9f8-4vr29
Name Level
pool warning
rbac warning
tracing warning
aws warning
cache_filter warning
decompression warning
init warning
assert warning
client warning
misc warning
udp warning
config warning
hystrix warning
key_value_store warning
runtime warning
admin warning
dns warning
jwt warning
redis warning
quic warning
alternate_protocols_cache warning
conn_handler warning
ext_proc warning
http warning
oauth2 warning
ext_authz warning
http2 warning
kafka warning
mongo warning
router warning
thrift warning
grpc warning
matcher warning
hc warning
multi_connection warning
wasm warning
dubbo warning
filter warning
upstream warning
backtrace warning
connection warning
io warning
main warning
happy_eyeballs warning
rds warning
tap warning
envoy_bug warning
rocketmq warning
file warning
forward_proxy warning
stats warning
health_checker warning
lua warning
secret warning
quic_stream warning
testing warning
websocket warning
```
The following command updates the `grpc` log level to `error`, the `http` log level to `critical`, and the `runtime` log level to `debug` for pod ID `server-697458b9f8-4vr29`
The `status` command provides an overall status summary of the Consul on Kubernetes installation. It also provides the configuration that was used to deploy Consul K8s and information about the health of Consul servers and clients. This command does not take in any flags.
The `troubleshoot` command exposes two subcommands for troubleshooting Consul
service mesh and network issues from a given pod.
- [`troubleshoot upstreams`](#troubleshoot-upstreams): List all Envoy upstreams in Consul service mesh from the given pod.
- [`troubleshoot proxy`](#troubleshoot-proxy): Troubleshoot Consul service mesh configuration and network issues between the given pod and the given upstream.
| <nobr>`-namespace`, `-n`</nobr> | `String` The Kubernetes namespace to list proxies in. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. |
| <nobr>`-envoy-admin-endpoint`</nobr> | `String` Envoy sidecar address and port | `127.0.0.1:19000` |
#### Example Commands
The following example displays all transparent proxy upstreams in Consul service mesh from the given pod.
If you cannot find the upstream address or cluster for a transparent proxy upstream:
- Check intentions: Tproxy upstreams are configured based on intentions. Make sure you have configured intentions to allow traffic to your upstream.
- To check that the right cluster is being dialed, run a DNS lookup for the upstream you are dialing. For example, run `dig backend.svc.consul` to return the IP address for the `backend` service. If the address you get from that is missing from the upstream IPs, it means that your proxy may be misconfigured.
```
The following example displays all explicit upstreams from the given pod in the Consul service mesh.
If you cannot find the upstream address or cluster for a transparent proxy upstream:
- Check intentions: Tproxy upstreams are configured based on intentions. Make sure you have configured intentions to allow traffic to your upstream.
- To check that the right cluster is being dialed, run a DNS lookup for the upstream you are dialing. For example, run `dig backend.svc.consul` to return the IP address for the `backend` service. If the address you get from that is missing from the upstream IPs, it means that your proxy may be misconfigured.
| <nobr>`-namespace`, `-n`</nobr> | `String` The Kubernetes namespace to list proxies in. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. |
| <nobr>`-envoy-admin-endpoint`</nobr> | `String` Envoy sidecar address and port | `127.0.0.1:19000` |
| <nobr>`-upstream-ip`</nobr> | `String` The IP address of the upstream transparent proxy | |
| <nobr>`-upstream-envoy-id`</nobr> | `String` The Envoy identifier of the upstream | |
#### Example Commands
The following example troubleshoots the Consul service mesh configuration and network issues between the given pod and the given upstream IP.
| <nobr>`-auto-approve`</nobr> | Boolean value that enables you to skip the removal confirmation prompt. | `false` |
| <nobr>`-name`</nobr> | String value for the name of the installation to remove. | none |
| <nobr>`-namespace`</nobr> | String value that specifies the namespace of the Consul installation to remove. | `consul` |
| <nobr>`-timeout`</nobr> | Specifies how long to wait for the removal process to complete before timing out. The value is specified with an integer and string value indicating a unit of time. <br/> The following units are supported: <br/> `ms` (milliseconds)<br/>`s` (seconds)<br/>`m` (minutes) <br/>`h` (hours) <br/>In the following example, removal will timeout after one minute:<br/> `consul-k8s uninstall -timeout 1m` | `10m` |
| <nobr>`-wipe-data`</nobr> | Boolean value that deletes PVCs and secrets associated with the Consul installation during installation. <br/> Data will be removed without a verification prompt if the `-auto-approve` flag is set to `true`. | `false` <br/> Instructions for removing data will be printed to the console. |
| <nobr>`--help`</nobr> | Prints usage information for this option. | none |
See [Global Options](#global-options) for additional commands that you can use when uninstalling Consul from Kubernetes.
#### Example Command
The following example command immediately uninstalls Consul from the `my-ns` namespace with the name `my-consul` and removes PVCs and secrets associated with the installation without asking for verification:
The `upgrade` command upgrades the Consul on Kubernetes components to the current version of the `consul-k8s` cli. Prior to running `consul-k8s upgrade`, the `consul-k8s` CLI should first be upgraded to the latest version as described [Upgrade the Consul K8s CLI](#upgrade-the-consul-k8s-cli)
| <nobr>`-auto-approve`</nobr> | Boolean value that enables you to skip the upgrade confirmation prompt. | `false` |
| <nobr>`-dry-run`</nobr> | Boolean value that allows you to run pre-upgrade checks and returns a summary of the upgrade. | `false` |
| <nobr>`-config-file`</nobr> | String value that specifies the path to a file containing custom upgrade configurations, e.g., Consul Helm chart values file. <br/> You can use the `-config-file` flag multiple times to specify multiple files. | none |
| <nobr>`-namespace`</nobr> | String value that specifies the namespace of the Consul installation. | `consul` |
| <nobr>`-preset`</nobr> | String value that upgrades Consul based on a preset configuration. | Configuration of the Consul Helm chart. |
| <nobr>`-set`</nobr> | String value that enables you to set a customizable value. This flag is comparable to the `helm upgrade --set` flag. <br/> You can use the `-set` flag multiple times to set multiple values. <br/> Consul Helm chart values are supported. | none |
| <nobr>`-set-file`</nobr> | String value that specifies the name of an arbitrary config file. This flag is comparable to the `helm upgrade --set-file` <br/> flag. The contents of the file will be used to set a customizable value. You can use the `-set-file` flag multiple times to specify multiple files. <br/> Consul Helm chart values are supported. | none |
| <nobr>`-set-string`</nobr> | String value that enables you to set a customizable string value. This flag is comparable to the `helm upgrade --set-string` <br/> flag. You can use the `-set-string` flag multiple times to specify multiple strings. <br/> Consul Helm chart values are supported. | none |
| <nobr>`-timeout`</nobr> | Specifies how long to wait for the upgrade process to complete before timing out. The value is specified with an integer and string value indicating a unit of time. <br/> The following units are supported: <br/> `ms` (milliseconds)<br/>`s` (seconds)<br/>`m` (minutes) <br/>In the following example, the upgrade will timeout after one minute:<br/> `consul-k8s upgrade -timeout 1m` | `10m` |
| <nobr>`-wait`</nobr> | Boolean value that determines if Consul should wait for resources in the upgrade to be ready before exiting the command. | `true` |
| <nobr>`-verbose`, `-v`</nobr> | Boolean value that specifies whether to output verbose logs from the upgrade command with the status of resources being upgraded. | `false` |
| <nobr>`--help`</nobr> | Prints usage information for this option. | none |
