--- layout: docs page_title: Consul K8s CLI Reference description: >- Consul K8s CLI is a tool for quickly installing and interacting with Consul on Kubernetes. --- # Consul on Kubernetes CLI Reference The Consul on Kubernetes CLI, `consul-k8s`, is a tool for managing Consul without requiring `Helm`, the [Consul CLI](/commands/index), or `kubectl`. -> **Note**: For guidance on how to install `consul-k8s`, visit the [Installing the Consul K8s CLI](/docs/k8s/installation/install-cli) documentation. This topic describes the commands and available options for using `consul-k8s`. ## Usage The Consul on Kubernetes CLI uses the following syntax: ```shell-session $ consul-k8s ``` ## Commands You can use the following commands with `consul-k8s`. - [`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. - [`proxy read`](#proxy-read): Inspect the Envoy configuration for a given Pod. - [`status`](#status): Check the status of a Consul installation on Kubernetes. - [`uninstall`](#uninstall): Uninstall Consul deployment. - [`upgrade`](#upgrade): Upgrade Consul on Kubernetes from an existing installation. - [`version`](#version): Print the version of the Consul on Kubernetes CLI. ### `install` The `install` command installs Consul to your Kubernetes cluster. ```shell-session $ consul-k8s install ``` The following options are available. | Flag | Description | Default | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `-auto-approve` | Boolean value that enables you to skip the installation confirmation prompt. | `false` | | `-dry-run` | Boolean value that validates the installation and returns a summary. | `false` | | `-config-file` | String value that specifies the path to a file containing custom installation configurations, e.g., Consul Helm chart values file.
You can use the `-config-file` flag multiple times to specify multiple files. | none | | `-namespace` | String value that specifies the namespace of the Consul installation. | `consul` | | `-preset` | String value that installs Consul based on a preset configuration. You can specify the following values:
`demo`: Installs a single replica server with sidecar injection enabled; useful for testing service mesh functionality.
`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. | | `-set` | String value that enables you to set a customizable value. This flag is comparable to the `helm install --set` flag.
You can use the `-set` flag multiple times to set multiple values.
Consul Helm chart values are supported. | none | | `-set-file` | String value that specifies the name of an arbitrary config file. This flag is comparable to the `helm install --set-file`
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.
Consul Helm chart values are supported. | none | | `-set-string` | String value that enables you to set a customizable string value. This flag is comparable to the `helm install --set-string`
flag. You can use the `-set-string` flag multiple times to specify multiple strings.
Consul Helm chart values are supported. | none | | `-timeout` | 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.
The following units are supported:
`ms` (milliseconds)
`s` (seconds)
`m` (minutes)
In the following example, installation will timeout after one minute:
`consul-k8s install -timeout 1m` | `10m` | | `-wait` | Boolean value that determines if Consul should wait for resources in the installation to be ready before exiting the command. | `true` | | `-verbose`, `-v` | Boolean value that specifies whether to output verbose logs from the install command with the status of resources being installed. | `false` | | `-help`, `-h` | Prints usage information for this option. | none | See [Global Options](#global-options) for additional commands that you can use when installing Consul on Kubernetes. #### Example Commands The following example command installs Consul according in the `myNS` namespace according to the `secure` preset. ```shell-session $ consul-k8s install -preset=secure -namespace=myNS ``` 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). ```shell-session $ consul-k8s install -set key=value ``` ```shell-session $ consul-k8s install -set key1=value1 -set key2=value2 ``` ```shell-session $ consul-k8s install -set-file config1=value1.conf ``` ```shell-session $ consul-k8s install -set-file config1=value1.conf -set-file config2=value2.conf ``` ```shell-session $ consul-k8s install -set-string key=value-bool ``` ### `proxy` The `proxy` command exposes two subcommands for interacting proxies managed by Consul in your Kubernetes Cluster. - [`proxy list`](#proxy-list) List all Kubernetes pods running proxies managed by Consul. - [`proxy read`](#proxy-read) Inspect the Envoy configuration for a given Pod. ### `proxy list` ```shell-session $ consul-k8s proxy list ``` | Flag | Description | Default | | -------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `-all-namespaces`, `-A` | `Boolean` List pods in all Kubernetes namespaces. | `false` | | `-namespace`, `-n` | `String` The Kubernetes namespace to list proxies in. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. | See [Global Options](#global-options) for additional commands that you can use when installing Consul on Kubernetes. This command will list proxies alongside their `Type`. Types of proxies include - `Sidecar`: these will be the majority of pods in the cluster. They run the proxy in a sidecar pattern to network the pod as a service in the mesh. - `API Gateway`: these pods run a proxy to manage connections with networks outside of the Consul cluster. [Read more about API gateways](/docs/api-gateway) - `Ingress Gateway`: these pods run a proxy to manage ingress into the Kubernetes cluster. [Read more about ingress gateways](/docs/k8s/connect/ingress-gateways) - `Terminating Gateway`: these pods run a proxy to control connections to external services. [Read more about terminating gateways](/docs/k8s/connect/terminating-gateways) - `Mesh Gateway`: these pods run a proxy to manage connections between Consul clusters connected using mesh federation. [Read more about Consul Mesh Federation](/docs/k8s/installation/multi-cluster/kubernetes) #### Example Commands Display all pods in the current Kubernetes namespace which run proxies managed by Consul. ```shell-session $ consul-k8s proxy list ``` ``` Namespace: default Name Type backend-658b679b45-d5xlb Sidecar client-767ccfc8f9-6f6gx Sidecar client-767ccfc8f9-f8nsn Sidecar client-767ccfc8f9-ggrtx Sidecar frontend-676564547c-v2mfq Sidecar ``` Display all pods in the `consul` Kubernetes namespace which run proxies managed by Consul. ```shell-session $ consul-k8s proxy list -n consul ``` ``` Namespace: consul Name Type consul-ingress-gateway-6fb5544485-br6fl Ingress Gateway consul-ingress-gateway-6fb5544485-m54sp Ingress Gateway ``` Display all pods across all ```shell-session $ consul-k8s proxy list -A ``` ``` Namespace: All Namespaces Namespace Name Type consul consul-ingress-gateway-6fb5544485-br6fl Ingress Gateway consul consul-ingress-gateway-6fb5544485-m54sp Ingress Gateway default backend-658b679b45-d5xlb Sidecar default client-767ccfc8f9-6f6gx Sidecar default client-767ccfc8f9-f8nsn Sidecar default client-767ccfc8f9-ggrtx Sidecar default frontend-676564547c-v2mfq Sidecar ``` ### `proxy read` The `proxy read` command allows you to inspect the configuration of any Envoy proxies running on a given Pod. ```shell-session $ consul-k8s proxy read ``` The command takes a required value, ``. This should be the full name of a Kubernetes Pod. The following options are available. | Flag | Description | Default | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `-namespace`, `-n` | `String` The namespace where the target Pod can be found. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. | | `-output`, `-o` | `String` Output the Envoy configuration as 'table', 'json', or 'raw'. | `'table'` | | `-clusters` | `Boolean` Filter output to only show clusters. | `false` | | `-endpoints` | `Boolean` Filter output to only show endpoints. | `false` | | `-listeners` | `Boolean` Filter output to only show listeners. | `false` | | `-routes` | `Boolean` Filter output to only show routes. | `false` | | `-secrets` | `Boolean` Filter output to only show secrets. | `false` | | `-address` | `String` Filter clusters, endpoints, and listeners output to only those with endpoint addresses which contain the given value. | `""` | | `-fqdn` | `String` Filter cluster output to only clusters with a fully qualified domain name which contains the given value. | `""` | | `-port` | `Int` Filter endpoints output to only endpoints with the given port number. | `-1` which does not filter by port | #### Example commands Get the configuration summary for the Envoy proxy running on the Pod `backend-658b679b45-d5xlb`. ```shell-session $ consul-k8s proxy read backend-658b679b45-d5xlb ``` ``` Envoy configuration for backend-658b679b45-d5xlb in namespace default: ==> Clusters (5) Name FQDN Endpoints Type Last Updated local_agent local_agent 192.168.79.187:8502 STATIC 2022-05-13T04:22:39.553Z client client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul EDS 2022-07-21T12:12:27.335Z frontend frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul EDS 2022-07-21T12:12:27.242Z local_app local_app 127.0.0.1:8080 STATIC 2022-05-13T04:22:39.655Z original-destination original-destination ORIGINAL_DST 2022-05-13T04:22:39.743Z ==> Endpoints (6) Address:Port Cluster Weight Status 192.168.79.187:8502 local_agent 1.00 HEALTHY 192.168.18.110:20000 1.00 HEALTHY 192.168.52.101:20000 1.00 HEALTHY 192.168.65.131:20000 1.00 HEALTHY 192.168.63.120:20000 1.00 HEALTHY 127.0.0.1:8080 local_app 1.00 HEALTHY ==> Listeners (2) Name Address:Port Direction Filter Chain Match Filters Last Updated public_listener 192.168.69.179:20000 INBOUND Any * -> local_app/ 2022-07-21T12:12:42.148Z outbound_listener 127.0.0.1:15001 OUTBOUND 10.100.134.173/32, 240.0.0.3/32 -> client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 2022-07-18T15:31:03.246Z 10.100.31.2/32, 240.0.0.5/32 -> frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul Any -> original-destination ==> Routes (1) Name Destination Cluster Last Updated public_listener local_app/ 2022-07-21T12:12:42.147Z ==> Secrets (0) Name Type Last Updated ``` Get the Envoy configuration summary for all clusters with a fully qualified domain name which includes `"default"`. Display only clusters and listeners. ```shell-session $ consul-k8s proxy read backend-658b679b45-d5xlb -fqdn default -clusters -listeners ``` ``` Envoy configuration for backend-658b679b45-d5xlb in namespace default: ==> Filters applied Fully qualified domain names containing: default ==> Clusters (2) Name FQDN Endpoints Type Last Updated client client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul EDS 2022-07-21T12:12:27.335Z frontend frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul EDS 2022-07-21T12:12:27.242Z ==> Listeners (2) Name Address:Port Direction Filter Chain Match Filters Last Updated public_listener 192.168.69.179:20000 INBOUND Any * -> local_app/ 2022-07-21T12:12:42.148Z outbound_listener 127.0.0.1:15001 OUTBOUND 10.100.134.173/32, 240.0.0.3/32 -> client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 2022-07-18T15:31:03.246Z 10.100.31.2/32, 240.0.0.5/32 -> frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul Any -> original-destination ``` Get the raw Envoy configuration dump for the Envoy proxy running on the Pod `backend-658b679b45-d5xlb`. The raw configuration will be output for each service as a JSON map. The [JQ command line tool](https://stedolan.github.io/jq/) can be used to index into the configuration for the service you want to inspect. See the [Envoy config dump documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/admin/v3/config_dump.proto) for more information on the structure of the config dump. ```shell-session $ consul-k8s proxy read backend-658b679b45-d5xlb -o raw ``` ``` { "backend-658b679b45-d5xlb": { "configs": [ { "@type": "type.googleapis.com/envoy.admin.v3.BootstrapConfigDump", "bootstrap": { // [-- snip 1201 lines --] }, "last_updated": "2022-05-13T04:22:39.488Z" }, { "@type": "type.googleapis.com/envoy.admin.v3.ClustersConfigDump", "static_clusters": [ // [-- snip 42 lines --] ], "dynamic_active_clusters": [ // [-- snip 144 lines --] ] }, { "@type": "type.googleapis.com/envoy.admin.v3.EndpointsConfigDump", "static_endpoint_configs": [ // [-- snip 29 lines --] ], "dynamic_endpoint_configs": [ // [-- snip 120 lines --] ] }, { "@type": "type.googleapis.com/envoy.admin.v3.ListenersConfigDump", "dynamic_listeners": [ // [-- snip 216 lines --] ] }, { "@type": "type.googleapis.com/envoy.admin.v3.ScopedRoutesConfigDump" }, { "@type": "type.googleapis.com/envoy.admin.v3.RoutesConfigDump", "static_route_configs": [ // [-- snip 25 lines --] ] }, { "@type": "type.googleapis.com/envoy.admin.v3.SecretsConfigDump" } ] } } ``` ### `status` The `status` command provides an overall status summary of the Consul on Kubernetes installation. It also provides the config that was used to deploy Consul K8s and provides a quick glance at the health of both Consul servers and clients. This command does not take in any flags. ```shell-session $ consul-k8s status ``` #### Example Command ```shell-session $ consul-k8s status ==> Consul-K8s Status Summary NAME | NAMESPACE | STATUS | CHARTVERSION | APPVERSION | REVISION | LAST UPDATED ---------+-----------+----------+--------------+------------+----------+-------------------------- consul | consul | deployed | 0.41.1 | 1.11.4 | 1 | 2022/03/10 07:48:58 MST ==> Config: connectInject: enabled: true metrics: defaultEnableMerging: true defaultEnabled: true enableGatewayMetrics: true controller: enabled: true global: metrics: enableAgentMetrics: true enabled: true name: consul prometheus: enabled: true server: replicas: 1 ui: enabled: true service: enabled: true ✓ Consul servers healthy (1/1) ✓ Consul clients healthy (3/3) ``` ### `uninstall` The `uninstall` command removes Consul from Kubernetes. ```shell-session $ consul-k8s uninstall ``` The following options are available. | Flag | Description | Default | | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `-auto-approve` | Boolean value that enables you to skip the removal confirmation prompt. | `false` | | `-name` | String value for the name of the installation to remove. | none | | `-namespace` | String value that specifies the namespace of the Consul installation to remove. | `consul` | | `-timeout` | 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.
The following units are supported:
`ms` (milliseconds)
`s` (seconds)
`m` (minutes)
`h` (hours)
In the following example, removal will timeout after one minute:
`consul-k8s uninstall -timeout 1m` | `10m` | | `-wipe-data` | Boolean value that deletes PVCs and secrets associated with the Consul installation during installation.
Data will be removed without a verification prompt if the `-auto-approve` flag is set to `true`. | `false`
Instructions for removing data will be printed to the console. | | `--help` | 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: ```shell-session $ consul-k8s uninstall -namespace=my-ns -name=my-consul -wipe-data=true -auto-approve=true ``` ### `upgrade` -> The `consul-k8s upgrade` **subcommand is currently in beta**: This subcommand is not recommended for production environments. 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) ```shell-session $ consul-k8s upgrade ``` The following options are available. | Flag | Description | Default | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `-auto-approve` | Boolean value that enables you to skip the upgrade confirmation prompt. | `false` | | `-dry-run` | Boolean value that allows you to run pre-upgrade checks and returns a summary of the upgrade. | `false` | | `-config-file` | String value that specifies the path to a file containing custom upgrade configurations, e.g., Consul Helm chart values file.
You can use the `-config-file` flag multiple times to specify multiple files. | none | | `-namespace` | String value that specifies the namespace of the Consul installation. | `consul` | | `-preset` | String value that upgrades Consul based on a preset configuration. | Configuration of the Consul Helm chart. | | `-set` | String value that enables you to set a customizable value. This flag is comparable to the `helm upgrade --set` flag.
You can use the `-set` flag multiple times to set multiple values.
Consul Helm chart values are supported. | none | | `-set-file` | String value that specifies the name of an arbitrary config file. This flag is comparable to the `helm upgrade --set-file`
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.
Consul Helm chart values are supported. | none | | `-set-string` | String value that enables you to set a customizable string value. This flag is comparable to the `helm upgrade --set-string`
flag. You can use the `-set-string` flag multiple times to specify multiple strings.
Consul Helm chart values are supported. | none | | `-timeout` | 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.
The following units are supported:
`ms` (milliseconds)
`s` (seconds)
`m` (minutes)
In the following example, the upgrade will timeout after one minute:
`consul-k8s upgrade -timeout 1m` | `10m` | | `-wait` | Boolean value that determines if Consul should wait for resources in the upgrade to be ready before exiting the command. | `true` | | `-verbose`, `-v` | Boolean value that specifies whether to output verbose logs from the upgrade command with the status of resources being upgraded. | `false` | | `--help` | Prints usage information for this option. | none | See [Global Options](#global-options) for additional commands that you can use when installing Consul on Kubernetes. ### `version` The `version` command prints the Consul on Kubernetes version. This command does not take any options. ```shell-session $ consul-k8s version ``` You can also print the version with the `--version` flag. ```shell-session $ consul-k8s --version ``` ## Global Options The following global options are available. | Flag | Description | Default | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- | | `-context` | String value that sets the Kubernetes context to use for Consul K8s CLI operations. | none | | `-kubeconfig`
Alias: `-c` | String value that specifies the path to the `kubeconfig` file.
| none |