956 lines
58 KiB
Plaintext
956 lines
58 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Consul on Kubernetes CLI Reference
|
||
description: >-
|
||
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.
|
||
---
|
||
|
||
# Consul on Kubernetes CLI Reference
|
||
|
||
The Consul on Kubernetes CLI, `consul-k8s`, is a tool for managing Consul
|
||
that does not require direct interaction with Helm, the [Consul CLI](/consul/commands),
|
||
or `kubectl`.
|
||
|
||
For guidance on how to install `consul-k8s`, refer to the
|
||
[Installing the Consul K8s CLI](/consul/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 <COMMAND> <OPTIONS>
|
||
```
|
||
|
||
## 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.
|
||
- [`proxy log`](#proxy-log): Inspect and modify the Envoy logging configuration for a given Pod.
|
||
- [`status`](#status): Check the status of a Consul installation on Kubernetes.
|
||
- [`troubleshoot`](#troubleshoot): Troubleshoot Consul service mesh and networking issues from a given pod.
|
||
- [`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 on your Kubernetes cluster.
|
||
|
||
```shell-session
|
||
$ consul-k8s install <OPTIONS>
|
||
```
|
||
|
||
The following options are available.
|
||
|
||
| Flag | Description | Default |
|
||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------|
|
||
| <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 |
|
||
|
||
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 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 with proxies managed by
|
||
Consul in your Kubernetes Cluster.
|
||
|
||
- [`proxy list`](#proxy-list): List all Pods running proxies managed by Consul.
|
||
- [`proxy read`](#proxy-read): Inspect the Envoy configuration for a given Pod.
|
||
- [`proxy log`](#proxy-log): Inspect and modify the Envoy logging configuration for a given Pod.
|
||
|
||
### `proxy list`
|
||
|
||
```shell-session
|
||
$ consul-k8s proxy list <OPTIONS>
|
||
```
|
||
|
||
| Flag | Description | Default |
|
||
| ------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||
| <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. |
|
||
|
||
Refer to the [Global Options](#global-options) for additional options that you can use
|
||
when installing Consul on Kubernetes.
|
||
|
||
This command lists proxies and their `Type`. Types of proxies include:
|
||
|
||
- `Sidecar`: The majority of pods in the cluster are `Sidecar` types. They run the
|
||
proxy as a sidecar to connect 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](/consul/docs/api-gateway).
|
||
- `Ingress Gateway`: These pods run a proxy to manage ingress into the
|
||
Kubernetes cluster. Read more about [ingress gateways](/consul/docs/k8s/connect/ingress-gateways).
|
||
- `Terminating Gateway`: These pods run a proxy to control connections to
|
||
external services. Read more about [terminating gateways](/consul/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](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes).
|
||
|
||
#### Example Commands
|
||
|
||
Display all pods in the current Kubernetes namespace that 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 that 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 namespaces that run proxies managed by Consul.
|
||
|
||
```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 Envoy proxies running on a given Pod.
|
||
|
||
```shell-session
|
||
$ consul-k8s proxy read <PODNAME> <OPTIONS>
|
||
```
|
||
|
||
The command takes a required value, `<PODNAME>`. This should be the full name
|
||
of a Kubernetes Pod. If a Pod is running more than one Envoy proxy managed by
|
||
Consul, as in the [Multiport configuration](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports),
|
||
configuration for all proxies in the Pod will be displayed.
|
||
|
||
The following options are available.
|
||
|
||
| Flag | Description | Default |
|
||
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
|
||
| <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 |
|
||
|
||
#### 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 192.168.18.110:20000, 192.168.52.101:20000, 192.168.65.131:20000 EDS 2022-08-08T12:02:07.471Z
|
||
frontend frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 192.168.63.120:20000 EDS 2022-08-08T12:02:07.354Z
|
||
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 client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 1.00 HEALTHY
|
||
192.168.52.101:20000 client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 1.00 HEALTHY
|
||
192.168.65.131:20000 client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 1.00 HEALTHY
|
||
192.168.63.120:20000 frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 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 * to local_app/ 2022-08-08T12:02:22.261Z
|
||
outbound_listener 127.0.0.1:15001 OUTBOUND 10.100.134.173/32, 240.0.0.3/32 to 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 to frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul
|
||
Any to original-destination
|
||
|
||
==> Routes (1)
|
||
Name Destination Cluster Last Updated
|
||
public_listener local_app/ 2022-08-08T12:02:22.260Z
|
||
|
||
==> Secrets (0)
|
||
Name Type Last Updated
|
||
|
||
|
||
```
|
||
|
||
Get the Envoy configuration summary for all clusters with a fully qualified
|
||
domain name that includes `"default"`. Display only clusters and listeners.
|
||
|
||
```shell-session
|
||
$ consul-k8s proxy read backend-658b679b45-d5xlb -fqdn default -clusters -listeners
|
||
==> Filters applied
|
||
Fully qualified domain names containing: default
|
||
|
||
Envoy configuration for backend-658b679b45-d5xlb in namespace default:
|
||
|
||
==> Clusters (2)
|
||
Name FQDN Endpoints Type Last Updated
|
||
client client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 192.168.18.110:20000, 192.168.52.101:20000, 192.168.65.131:20000 EDS 2022-08-08T12:02:07.471Z
|
||
frontend frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul 192.168.63.120:20000 EDS 2022-08-08T12:02:07.354Z
|
||
|
||
|
||
==> Listeners (2)
|
||
Name Address:Port Direction Filter Chain Match Filters Last Updated
|
||
public_listener 192.168.69.179:20000 INBOUND Any * to local_app/ 2022-08-08T12:02:22.261Z
|
||
outbound_listener 127.0.0.1:15001 OUTBOUND 10.100.134.173/32, 240.0.0.3/32 to 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 to frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul
|
||
Any to original-destination
|
||
|
||
```
|
||
|
||
Get the Envoy configuration summary in a JSON format. Note that this is not the
|
||
same as the raw configuration dump from the admin API. This information is the
|
||
same as what is displayed in the table output above, but in a JSON format.
|
||
|
||
```shell-session
|
||
$ consul-k8s proxy read backend-658b679b45-d5xlb -o json
|
||
{
|
||
"backend-658b679b45-d5xlb": {
|
||
"clusters": [
|
||
{
|
||
"Name": "local_agent",
|
||
"FullyQualifiedDomainName": "local_agent",
|
||
"Endpoints": [
|
||
"192.168.79.187:8502"
|
||
],
|
||
"Type": "STATIC",
|
||
"LastUpdated": "2022-05-13T04:22:39.553Z"
|
||
},
|
||
{
|
||
"Name": "client",
|
||
"FullyQualifiedDomainName": "client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul",
|
||
"Endpoints": [
|
||
"192.168.18.110:20000",
|
||
"192.168.52.101:20000",
|
||
"192.168.65.131:20000"
|
||
],
|
||
"Type": "EDS",
|
||
"LastUpdated": "2022-08-08T12:02:07.471Z"
|
||
},
|
||
{
|
||
"Name": "frontend",
|
||
"FullyQualifiedDomainName": "frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul",
|
||
"Endpoints": [
|
||
"192.168.63.120:20000"
|
||
],
|
||
"Type": "EDS",
|
||
"LastUpdated": "2022-08-08T12:02:07.354Z"
|
||
},
|
||
{
|
||
"Name": "local_app",
|
||
"FullyQualifiedDomainName": "local_app",
|
||
"Endpoints": [
|
||
"127.0.0.1:8080"
|
||
],
|
||
"Type": "STATIC",
|
||
"LastUpdated": "2022-05-13T04:22:39.655Z"
|
||
},
|
||
{
|
||
"Name": "original-destination",
|
||
"FullyQualifiedDomainName": "original-destination",
|
||
"Endpoints": [],
|
||
"Type": "ORIGINAL_DST",
|
||
"LastUpdated": "2022-05-13T04:22:39.743Z"
|
||
}
|
||
],
|
||
"endpoints": [
|
||
{
|
||
"Address": "192.168.79.187:8502",
|
||
"Cluster": "local_agent",
|
||
"Weight": 1,
|
||
"Status": "HEALTHY"
|
||
},
|
||
{
|
||
"Address": "192.168.18.110:20000",
|
||
"Cluster": "client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul",
|
||
"Weight": 1,
|
||
"Status": "HEALTHY"
|
||
},
|
||
{
|
||
"Address": "192.168.52.101:20000",
|
||
"Cluster": "client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul",
|
||
"Weight": 1,
|
||
"Status": "HEALTHY"
|
||
},
|
||
{
|
||
"Address": "192.168.65.131:20000",
|
||
"Cluster": "client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul",
|
||
"Weight": 1,
|
||
"Status": "HEALTHY"
|
||
},
|
||
{
|
||
"Address": "192.168.63.120:20000",
|
||
"Cluster": "frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul",
|
||
"Weight": 1,
|
||
"Status": "HEALTHY"
|
||
},
|
||
{
|
||
"Address": "127.0.0.1:8080",
|
||
"Cluster": "local_app",
|
||
"Weight": 1,
|
||
"Status": "HEALTHY"
|
||
}
|
||
],
|
||
"listeners": [
|
||
{
|
||
"Name": "public_listener",
|
||
"Address": "192.168.69.179:20000",
|
||
"FilterChain": [
|
||
{
|
||
"Filters": [
|
||
"* to local_app/"
|
||
],
|
||
"FilterChainMatch": "Any"
|
||
}
|
||
],
|
||
"Direction": "INBOUND",
|
||
"LastUpdated": "2022-08-08T12:02:22.261Z"
|
||
},
|
||
{
|
||
"Name": "outbound_listener",
|
||
"Address": "127.0.0.1:15001",
|
||
"FilterChain": [
|
||
{
|
||
"Filters": [
|
||
"to client.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul"
|
||
],
|
||
"FilterChainMatch": "10.100.134.173/32, 240.0.0.3/32"
|
||
},
|
||
{
|
||
"Filters": [
|
||
"to frontend.default.dc1.internal.bc3815c2-1a0f-f3ff-a2e9-20d791f08d00.consul"
|
||
],
|
||
"FilterChainMatch": "10.100.31.2/32, 240.0.0.5/32"
|
||
},
|
||
{
|
||
"Filters": [
|
||
"to original-destination"
|
||
],
|
||
"FilterChainMatch": "Any"
|
||
}
|
||
],
|
||
"Direction": "OUTBOUND",
|
||
"LastUpdated": "2022-07-18T15:31:03.246Z"
|
||
}
|
||
],
|
||
"routes": [
|
||
{
|
||
"Name": "public_listener",
|
||
"DestinationCluster": "local_app/",
|
||
"LastUpdated": "2022-08-08T12:02:22.260Z"
|
||
}
|
||
],
|
||
"secrets": []
|
||
}
|
||
}
|
||
```
|
||
|
||
Get the raw Envoy configuration dump and clusters information for the Envoy
|
||
proxy running on the Pod `backend-658b679b45-d5xlb`. The example command returns
|
||
the raw configuration for each service as JSON. You can use the
|
||
[JQ command line tool](https://stedolan.github.io/jq/) to index into
|
||
the configuration for the service you want to inspect.
|
||
|
||
Refer to 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.
|
||
|
||
The following output is truncated for brevity.
|
||
|
||
```shell-session
|
||
$ consul-k8s proxy read backend-658b679b45-d5xlb -o raw
|
||
{
|
||
"backend-658b679b45-d5xlb": {
|
||
"clusters": {
|
||
// [-- snip 372 lines --] output from the Envoy admin interface's /clusters endpoint.
|
||
},
|
||
"config_dump": {
|
||
// [-- snip 1816 lines --] output from the Envoy admin interface's /config_dump?include_eds endpoint.
|
||
}
|
||
}
|
||
```
|
||
|
||
### `proxy log`
|
||
|
||
The `proxy log` command allows you to inspect and modify the logging configuration of Envoy proxies running on a given Pod.
|
||
|
||
```shell-session
|
||
$ consul-k8s proxy log <PODNAME> <OPTIONS>
|
||
```
|
||
|
||
The command takes a required value, `<PODNAME>`. This should be the full name
|
||
of a Kubernetes Pod. If a Pod is running more than one Envoy proxy managed by
|
||
Consul, as in the [Multiport configuration](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports),
|
||
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` |
|
||
|
||
#### 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`.
|
||
```shell-session
|
||
$ consul-k8s proxy log server-697458b9f8-4vr29 -update-level 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`
|
||
```shell-session
|
||
$ consul-k8s proxy log server-697458b9f8-4vr29 -update-level grpc:error,http:critical,runtime:debug
|
||
Envoy log configuration for server-697458b9f8-4vr29 in namespace default:
|
||
|
||
==> Log Levels for server-697458b9f8-4vr29
|
||
Name Level
|
||
assert info
|
||
dns info
|
||
http critical
|
||
pool info
|
||
thrift info
|
||
udp info
|
||
grpc error
|
||
hc info
|
||
stats info
|
||
wasm info
|
||
alternate_protocols_cache info
|
||
ext_authz info
|
||
filter info
|
||
http2 info
|
||
key_value_store info
|
||
tracing info
|
||
cache_filter info
|
||
quic_stream info
|
||
aws info
|
||
io info
|
||
matcher info
|
||
rbac info
|
||
tap info
|
||
connection info
|
||
conn_handler info
|
||
rocketmq info
|
||
hystrix info
|
||
oauth2 info
|
||
redis info
|
||
backtrace info
|
||
file info
|
||
forward_proxy info
|
||
kafka info
|
||
config info
|
||
router info
|
||
runtime debug
|
||
testing info
|
||
happy_eyeballs info
|
||
ext_proc info
|
||
init info
|
||
lua info
|
||
health_checker info
|
||
misc info
|
||
envoy_bug info
|
||
jwt info
|
||
main info
|
||
quic info
|
||
upstream info
|
||
websocket info
|
||
client info
|
||
decompression info
|
||
mongo info
|
||
multi_connection info
|
||
rds info
|
||
secret info
|
||
admin info
|
||
dubbo info
|
||
```
|
||
The following command resets the log levels for all loggers of an Envoy proxy in pod `server-697458b9f8-4vr29` to the default level of `info`.
|
||
```shell-session
|
||
$ consul-k8s proxy log server-697458b9f8-4vr29 -r
|
||
Envoy log configuration for server-697458b9f8-4vr29 in namespace default:
|
||
|
||
==> Log Levels for server-697458b9f8-4vr29
|
||
Name Level
|
||
ext_proc info
|
||
secret info
|
||
thrift info
|
||
tracing info
|
||
dns info
|
||
rocketmq info
|
||
happy_eyeballs info
|
||
hc info
|
||
io info
|
||
misc info
|
||
conn_handler info
|
||
key_value_store info
|
||
rbac info
|
||
hystrix info
|
||
wasm info
|
||
admin info
|
||
cache_filter info
|
||
client info
|
||
health_checker info
|
||
oauth2 info
|
||
runtime info
|
||
testing info
|
||
grpc info
|
||
upstream info
|
||
forward_proxy info
|
||
matcher info
|
||
pool info
|
||
aws info
|
||
decompression info
|
||
jwt info
|
||
tap info
|
||
assert info
|
||
redis info
|
||
http info
|
||
quic info
|
||
rds info
|
||
connection info
|
||
envoy_bug info
|
||
stats info
|
||
alternate_protocols_cache info
|
||
backtrace info
|
||
filter info
|
||
http2 info
|
||
init info
|
||
multi_connection info
|
||
quic_stream info
|
||
dubbo info
|
||
ext_authz info
|
||
main info
|
||
udp info
|
||
websocket info
|
||
config info
|
||
mongo info
|
||
router info
|
||
file info
|
||
kafka info
|
||
lua info
|
||
```
|
||
### `status`
|
||
|
||
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.
|
||
|
||
```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
|
||
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)
|
||
```
|
||
|
||
### `troubleshoot`
|
||
|
||
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.
|
||
|
||
### `troubleshoot upstreams`
|
||
|
||
```shell-session
|
||
$ consul-k8s troubleshoot upstreams -pod <pod> <OPTIONS>
|
||
```
|
||
|
||
| Flag | Description | Default |
|
||
| ------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||
| <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. |
|
||
|
||
#### Example Commands
|
||
|
||
The following example displays all transparent proxy upstreams in Consul service mesh from the given pod.
|
||
|
||
```shell-session
|
||
$ consul-k8s troubleshoot upstreams -pod frontend-767ccfc8f9-6f6gx
|
||
|
||
==> Upstreams (explicit upstreams only) (0)
|
||
|
||
==> Upstreams IPs (transparent proxy only) (1)
|
||
[10.4.6.160 240.0.0.3] true map[backend.default.dc1.internal.e08fa6d6-e91e-dfe0-f6e1-ba097a828e31.consul backend2.default.dc1.internal.e08fa6d6-e91e-dfe0-f6e1-ba097a828e31.consul]
|
||
|
||
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.
|
||
|
||
```shell-session
|
||
$ consul-k8s troubleshoot upstreams -pod client-767ccfc8f9-6f6gx
|
||
|
||
==> Upstreams (explicit upstreams only) (1)
|
||
server
|
||
counting
|
||
|
||
==> Upstreams IPs (transparent proxy only) (0)
|
||
|
||
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.
|
||
```
|
||
|
||
### `troubleshoot proxy`
|
||
|
||
```shell-session
|
||
$ consul-k8s troubleshoot proxy -pod <pod> -upstream-ip <ip> <OPTIONS>
|
||
$ consul-k8s troubleshoot proxy -pod <pod> -upstream-envoy-id <envoy-id> <OPTIONS>
|
||
```
|
||
|
||
| Flag | Description | Default |
|
||
| ------------------------------------ | ----------------------------------------------------------| ---------------------------------------------------------------------------------------------------------------------- |
|
||
| <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>`-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.
|
||
|
||
```shell-session
|
||
$ consul-k8s troubleshoot proxy -pod frontend-767ccfc8f9-6f6gx -upstream-ip 10.4.6.160
|
||
|
||
==> Validation
|
||
✓ certificates are valid
|
||
✓ Envoy has 0 rejected configurations
|
||
✓ Envoy has detected 0 connection failure(s)
|
||
✓ listener for upstream "backend" found
|
||
✓ route for upstream "backend" found
|
||
✓ cluster "backend.default.dc1.internal..consul" for upstream "backend" found
|
||
✓ healthy endpoints for cluster "backend.default.dc1.internal.e08fa6d6-e91e-dfe0-f6e1-ba097a828e31.consul" for upstream "backend" found
|
||
✓ cluster "backend2.default.dc1.internal..consul" for upstream "backend" found
|
||
! no healthy endpoints for cluster "backend2.default.dc1.internal.e08fa6d6-e91e-dfe0-f6e1-ba097a828e31.consul" for upstream "backend" found
|
||
```
|
||
|
||
The following example troubleshoots the Consul service mesh configuration and network issues between the given pod and the given upstream.
|
||
|
||
```shell-session
|
||
$ consul-k8s troubleshoot proxy -pod frontend-767ccfc8f9-6f6gx -upstream-envoy-id db
|
||
|
||
==> Validation
|
||
✓ certificates are valid
|
||
✓ Envoy has 0 rejected configurations
|
||
✓ Envoy has detected 0 connection failure(s)
|
||
! no listener for upstream "db" found
|
||
! no route for upstream "backend" found
|
||
! no cluster "db.default.dc1.internal.e08fa6d6-e91e-dfe0-f6e1-ba097a828e31.consul" for upstream "db" found
|
||
! no healthy endpoints for cluster "db.default.dc1.internal.e08fa6d6-e91e-dfe0-f6e1-ba097a828e31.consul" for upstream "db" found
|
||
```
|
||
|
||
### `uninstall`
|
||
|
||
The `uninstall` command removes Consul from Kubernetes.
|
||
|
||
```shell-session
|
||
$ consul-k8s uninstall <OPTIONS>
|
||
```
|
||
|
||
The following options are available.
|
||
|
||
| Flag | Description | Default |
|
||
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||
| <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:
|
||
|
||
```shell-session
|
||
$ consul-k8s uninstall -namespace=my-ns -name=my-consul -wipe-data=true -auto-approve=true
|
||
```
|
||
|
||
### `upgrade`
|
||
|
||
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 |
|
||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
|
||
| <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 |
|
||
|
||
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 |
|
||
| -------------------------------- | ----------------------------------------------------------------------------------- | ------- |
|
||
| <nobr>`-context`</nobr> | String value that sets the Kubernetes context to use for Consul K8s CLI operations. | none |
|
||
| <nobr>`-kubeconfig`, `-c`</nobr> | String value that specifies the path to the `kubeconfig` file. <br/> | none |
|