diff --git a/website/content/commands/troubleshoot/index.mdx b/website/content/commands/troubleshoot/index.mdx new file mode 100644 index 0000000000..6daf7b4a90 --- /dev/null +++ b/website/content/commands/troubleshoot/index.mdx @@ -0,0 +1,33 @@ +--- +layout: commands +page_title: 'Commands: Troubleshoot' +description: | +The `consul troubleshoot` provides tools to troubleshoot Consul's service mesh configuration. +--- + +# Consul Troubleshooting + +Command: `consul troubleshoot` + +Use the `troubleshoot` command to diagnose Consul service mesh configuration or network issues. + +## Usage + +```text +Usage: consul troubleshoot [options] + + # ... + +Subcommands: + +Subcommands: + + proxy Troubleshoots service mesh issues from the current envoy instance + upstreams Get upstream envoy identifiers for the current envoy instance +``` + +For more information, examples, and usage about a subcommand, click on the name +of the subcommand in the sidebar or one of the links below: + +- [proxy](/consul/commands/troubleshoot/proxy) +- [upstreams](/consul/commands/troubleshoot/upstreams) diff --git a/website/content/commands/troubleshoot/proxy.mdx b/website/content/commands/troubleshoot/proxy.mdx new file mode 100644 index 0000000000..470f6fb3d9 --- /dev/null +++ b/website/content/commands/troubleshoot/proxy.mdx @@ -0,0 +1,59 @@ +--- +layout: commands +page_title: 'Commands: Troubleshoot Proxy' +description: | +The `consul troubleshoot proxy` diagnoses Consul service mesh configuration and network issues to an upstream. +--- + +# Consul Troubleshoot Proxy + +Command: `consul troubleshoot proxy` + +## Usage + +Usage: `consul troubleshoot proxy (-upstream-ip |-upstream-envoy-id ) [options] + +#### Command Options + +- `-envoy-admin-endpoint=` - Envoy Admin endpoint address for the local Envoy instance. +Defaults to `127.0.0.1:19000`. + +- `-upstream-ip=` - The IP address of the upstream transparent proxy. + +- `-upstream-envoy-id=` - The Envoy identifier of the upstream service to be troubleshooted. + +## Examples + +Troubleshoot Consul service mesh configuration and network issues from the current Envoy instance. + +```shell-session hideClipboard +$ consul troubleshoot proxy -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 +``` + +Troubleshoot Consul service mesh configuration and network issues from the current Envoy instance to the given upstream Envoy identifier. + +```shell-session +$ consul-k8s troubleshoot proxy -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 +``` diff --git a/website/content/commands/troubleshoot/upstreams.mdx b/website/content/commands/troubleshoot/upstreams.mdx new file mode 100644 index 0000000000..ed8083eeec --- /dev/null +++ b/website/content/commands/troubleshoot/upstreams.mdx @@ -0,0 +1,36 @@ +--- +layout: commands +page_title: 'Commands: Troubleshoot Upstreams' +description: | +The `consul troubleshoot upstream` lists the available upstreams in the Consul service mesh from the current service. +--- + +# Consul Troubleshoot Upstreams + +Command: `consul troubleshoot upstreams` + +## Usage + +Usage: `consul troubleshoot upstreams [options] + +#### Command Options + +- `-envoy-admin-endpoint=` - Envoy Admin endpoint address for the local Envoy instance. + Defaults to `127.0.0.1:19000`. + +## Examples + +Display all transparent proxy upstreams in Consul service mesh from the current Envoy instance. + +```shell-session hideClipboard +$ consul troubleshoot upstreams + +==> 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 don't see your 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. +- You can also check that the right cluster is being dialed by running a DNS lookup for the upstream you are dialing (i.e dig backend.svc.consul). If the address you get from that is missing from the Upstream IPs your proxy may be misconfigured. +``` diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 402d2327b7..d3fec8e17f 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -33,6 +33,7 @@ You can use the following commands with `consul-k8s`. - [`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. + - [`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. @@ -490,6 +491,115 @@ $ consul-k8s status ✓ Consul clients healthy (3/3) ``` +### `troubleshoot` + +The `troubleshoot` command exposes two subcommand 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 from the given pod to the given upstream. + +### `troubleshoot upstreams` + +```shell-session +$ consul-k8s troubleshoot upstreams -pod +``` + +| Flag | Description | Default | +| ------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `-namespace`, `-n` | `String` The Kubernetes namespace to list proxies in. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. | +| `-envoy-admin-endpoint` | `String` Envoy sidecar address and port | `127.0.0.1:19000` | + + +#### Example Commands + +Display 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 don't see your 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. +- You can also check that the right cluster is being dialed by running a DNS lookup for the upstream you are dialing (i.e dig backend.svc.consul). If the address you get from that is missing from the Upstream IPs your proxy may be misconfigured. +``` + +Display all explicit upstreams in Consul service mesh from the given pod. + +```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 don't see your 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. +- You can also check that the right cluster is being dialed by running a DNS lookup for the upstream you are dialing (i.e dig backend.svc.consul). If the address you get from that is missing from the Upstream IPs your proxy may be misconfigured. +``` + +### `troubleshoot proxy` + +```shell-session +$ consul-k8s troubleshoot proxy -pod -upstream-ip +$ consul-k8s troubleshoot proxy -pod -upstream-envoy-id +``` + +| Flag | Description | Default | +| ------------------------------------ | ----------------------------------------------------------| ---------------------------------------------------------------------------------------------------------------------- | +| `-namespace`, `-n` | `String` The Kubernetes namespace to list proxies in. | Current [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) namespace. | +| `-envoy-admin-endpoint` | `String` Envoy sidecar address and port | `127.0.0.1:19000` | +| `-upstream-ip` | `String` The IP address of the upstream transparent proxy | | +| `-upstream-envoy-id` | `String` The Envoy identifier of the upstream | | + +#### Example Commands + +Troubleshoot Consul service mesh configuration and network issues from the given pod to 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 +``` + +Troubleshoot Consul service mesh configuration and network issues from the given pod to the given upstream Envoy identifier. + +```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.