From 9a9da49222ccce97af2d89d39601a6a0db9babbe Mon Sep 17 00:00:00 2001 From: Travis Beckham Date: Fri, 26 Apr 2024 13:47:37 -0500 Subject: [PATCH] Fix checks redirect in 2.15 docs (#1769) * Fixed checks redirect Signed-off-by: Travis Beckham * Fixed redirect in older docs to point to the latest troubleshooting doc Signed-off-by: Travis Beckham * improve versioncheck troubleshooting language Signed-off-by: William Morgan * Fixed header anchor links Signed-off-by: Travis Beckham * Added unsupported version channel error to cli check Signed-off-by: Travis Beckham * Bypass markdownlint due to styling of headers Signed-off-by: Travis Beckham --------- Signed-off-by: Travis Beckham Signed-off-by: William Morgan Co-authored-by: William Morgan --- linkerd.io/content/2.10/checks/index.html | 2 +- linkerd.io/content/2.11/checks/index.html | 2 +- linkerd.io/content/2.12/checks/index.html | 2 +- linkerd.io/content/2.13/checks/index.html | 2 +- linkerd.io/content/2.14/checks/index.html | 2 +- linkerd.io/content/2.15/checks/index.html | 2 +- .../content/2.15/tasks/troubleshooting.md | 270 +++++++++++------- 7 files changed, 170 insertions(+), 112 deletions(-) diff --git a/linkerd.io/content/2.10/checks/index.html b/linkerd.io/content/2.10/checks/index.html index 02f72f8874..d13700ee78 100644 --- a/linkerd.io/content/2.10/checks/index.html +++ b/linkerd.io/content/2.10/checks/index.html @@ -6,7 +6,7 @@ Linkerd Check Redirection diff --git a/linkerd.io/content/2.11/checks/index.html b/linkerd.io/content/2.11/checks/index.html index 01ca8a947c..d13700ee78 100644 --- a/linkerd.io/content/2.11/checks/index.html +++ b/linkerd.io/content/2.11/checks/index.html @@ -6,7 +6,7 @@ Linkerd Check Redirection diff --git a/linkerd.io/content/2.12/checks/index.html b/linkerd.io/content/2.12/checks/index.html index bd0396fff6..d13700ee78 100644 --- a/linkerd.io/content/2.12/checks/index.html +++ b/linkerd.io/content/2.12/checks/index.html @@ -6,7 +6,7 @@ Linkerd Check Redirection diff --git a/linkerd.io/content/2.13/checks/index.html b/linkerd.io/content/2.13/checks/index.html index 8addaa3cc8..d13700ee78 100644 --- a/linkerd.io/content/2.13/checks/index.html +++ b/linkerd.io/content/2.13/checks/index.html @@ -6,7 +6,7 @@ Linkerd Check Redirection diff --git a/linkerd.io/content/2.14/checks/index.html b/linkerd.io/content/2.14/checks/index.html index 2642385152..d13700ee78 100644 --- a/linkerd.io/content/2.14/checks/index.html +++ b/linkerd.io/content/2.14/checks/index.html @@ -6,7 +6,7 @@ Linkerd Check Redirection diff --git a/linkerd.io/content/2.15/checks/index.html b/linkerd.io/content/2.15/checks/index.html index 238c542fc6..d13700ee78 100644 --- a/linkerd.io/content/2.15/checks/index.html +++ b/linkerd.io/content/2.15/checks/index.html @@ -6,7 +6,7 @@ Linkerd Check Redirection diff --git a/linkerd.io/content/2.15/tasks/troubleshooting.md b/linkerd.io/content/2.15/tasks/troubleshooting.md index 9b3072f6e2..202921f18d 100644 --- a/linkerd.io/content/2.15/tasks/troubleshooting.md +++ b/linkerd.io/content/2.15/tasks/troubleshooting.md @@ -385,8 +385,9 @@ try installing linkerd via --set proxyInit.runAsRoot=true see https://linkerd.io/2.11/checks/#l5d-proxy-init-run-as-root for hints ``` -Kubernetes nodes running with docker as the container runtime ([CRI](https://kubernetes.io/docs/concepts/architecture/cri/)) -require the init container to run as root for iptables. +Kubernetes nodes running with docker as the container runtime +([CRI](https://kubernetes.io/docs/concepts/architecture/cri/)) require the init +container to run as root for iptables. Newer distributions of managed k8s use containerd where this is not an issue. @@ -399,8 +400,8 @@ time="2021-11-15T04:41:31Z" level=info msg="iptables-save v1.8.7 (legacy): Canno ``` See [linkerd/linkerd2#7283](https://github.com/linkerd/linkerd2/issues/7283) and -[linkerd/linkerd2#7308](https://github.com/linkerd/linkerd2/issues/7308) -for further details. +[linkerd/linkerd2#7308](https://github.com/linkerd/linkerd2/issues/7308) for +further details. ## The "linkerd-existence" checks {#l5d-existence} @@ -501,8 +502,8 @@ Example failure: Failures of such nature indicate that your roots have expired. If that is the case you will have to update both the root and issuer certificates at once. You can follow the process outlined in -[Replacing Expired Certificates](../replacing_expired_certificates/) to -get your cluster back to a stable state. +[Replacing Expired Certificates](../replacing_expired_certificates/) to get your +cluster back to a stable state. ### √ trust roots are valid for at least 60 days {#l5d-identity-trustAnchors-not-expiring-soon} @@ -646,9 +647,9 @@ Example failure: see https://linkerd.io/checks/#l5d-proxy-injector-webhook-cert-not-expiring-soon for hints ``` -This warning indicates that the expiry of proxy-injnector webhook -cert is approaching. In order to address this -problem without incurring downtime, you can follow the process outlined in +This warning indicates that the expiry of proxy-injnector webhook cert is +approaching. In order to address this problem without incurring downtime, you +can follow the process outlined in [Automatically Rotating your webhook TLS Credentials](../automatically-rotating-webhook-tls-credentials/). ### √ sp-validator webhook has valid cert {#l5d-sp-validator-webhook-cert-valid} @@ -685,9 +686,9 @@ Example failure: see https://linkerd.io/checks/#l5d-sp-validator-webhook-cert-not-expiring-soon for hints ``` -This warning indicates that the expiry of sp-validator webhook -cert is approaching. In order to address this -problem without incurring downtime, you can follow the process outlined in +This warning indicates that the expiry of sp-validator webhook cert is +approaching. In order to address this problem without incurring downtime, you +can follow the process outlined in [Automatically Rotating your webhook TLS Credentials](../automatically-rotating-webhook-tls-credentials/). ### √ policy-validator webhook has valid cert {#l5d-policy-validator-webhook-cert-valid} @@ -700,8 +701,8 @@ Example failure: see https://linkerd.io/checks/#l5d-policy-validator-webhook-cert-valid for hints ``` -Ensure that the `linkerd-policy-validator-k8s-tls` secret exists and contains the -appropriate `tls.crt` and `tls.key` data entries. +Ensure that the `linkerd-policy-validator-k8s-tls` secret exists and contains +the appropriate `tls.crt` and `tls.key` data entries. ```bash × policy-validator webhook has valid cert @@ -722,9 +723,9 @@ Example failure: see https://linkerd.io/checks/#l5d-policy-validator-webhook-cert-not-expiring-soon for hints ``` -This warning indicates that the expiry of policy-validator webhook -cert is approaching. In order to address this -problem without incurring downtime, you can follow the process outlined in +This warning indicates that the expiry of policy-validator webhook cert is +approaching. In order to address this problem without incurring downtime, you +can follow the process outlined in [Automatically Rotating your webhook TLS Credentials](../automatically-rotating-webhook-tls-credentials/). ## The "linkerd-identity-data-plane" checks {#l5d-identity-data-plane} @@ -820,9 +821,9 @@ Example failure: ``` Linkerd has a `clusterNetworks` setting which allows it to differentiate between -intra-cluster and egress traffic. This warning indicates that the cluster has -a podCIDR which is not included in Linkerd's `clusterNetworks`. Traffic to pods -in this network may not be meshed properly. To remedy this, update the +intra-cluster and egress traffic. This warning indicates that the cluster has a +podCIDR which is not included in Linkerd's `clusterNetworks`. Traffic to pods in +this network may not be meshed properly. To remedy this, update the `clusterNetworks` setting to include all pod networks in the cluster. ### √ cluster networks contains all pods {#l5d-cluster-networks-pods} @@ -840,8 +841,8 @@ Example failures: ``` Linkerd has a `clusterNetworks` setting which allows it to differentiate between -intra-cluster and egress traffic. This warning indicates that the cluster has -a pod or ClusterIP service which is not included in Linkerd's `clusterNetworks`. +intra-cluster and egress traffic. This warning indicates that the cluster has a +pod or ClusterIP service which is not included in Linkerd's `clusterNetworks`. Traffic to pods or services in this network may not be meshed properly. To remedy this, update the `clusterNetworks` setting to include all pod and service networks in the cluster. @@ -867,27 +868,89 @@ $ curl "https://versioncheck.linkerd.io/version.json?version=edge-19.1.2&uuid=te ### √ cli is up-to-date {#l5d-version-cli} -Example failure: +Example failures: + + + +**unsupported version channel** + + + +```bash +‼ cli is up-to-date + unsupported version channel: stable-2.14.10 +``` + +As of February 2024, the Linkerd project is no longer producing open source +stable release artifacts. Please read the +[2.15 announcement](/2024/02/21/announcing-linkerd-2.15/#a-new-model-for-stable-releases) +for details. + +See [the full list of Linkerd releases](/releases/) for ways to get Linkerd. + + + +**is running version X but the latest version is Y** + + ```bash ‼ cli is up-to-date is running version 19.1.1 but the latest edge version is 19.1.2 ``` -See the page on [Upgrading Linkerd](../../upgrade/). +There is a newer version of the `linkerd` cli. See the page on +[Upgrading Linkerd](../../upgrade/). ## The "control-plane-version" checks {#l5d-version-control} +### √ control plane is up-to-date {#l5d-version-control-up-to-date} + Example failures: + + +**unsupported version channel** + + + +```bash +‼ control plane is up-to-date + unsupported version channel: stable-2.14.10 +``` + +As of February 2024, the Linkerd project is no longer producing open source +stable release artifacts. Please read the +[2.15 announcement](/2024/02/21/announcing-linkerd-2.15/#a-new-model-for-stable-releases) +for details. + +See [the full list of Linkerd releases](/releases/) for ways to get Linkerd. + + + +**is running version X but the latest version is Y** + + + ```bash ‼ control plane is up-to-date is running version 19.1.1 but the latest edge version is 19.1.2 +``` + +There is a newer version of the control plane. See the page on +[Upgrading Linkerd](../../upgrade/). + +### √ control plane and cli versions match {#l5d-version-control-mismatched} + +Example failure: + +```bash ‼ control plane and cli versions match mismatched channels: running stable-2.1.0 but retrieved edge-19.1.2 ``` -See the page on [Upgrading Linkerd](../../upgrade/). +Your CLI and your control plane are running different types of releases. This +may cause issues. ## The "linkerd-control-plane-proxy" checks {#linkerd-control-plane-proxy} @@ -900,8 +963,8 @@ setting or re-install Linkerd as necessary. ### √ control plane proxies are up-to-date {#l5d-cp-proxy-version} This warning indicates the proxies running in the Linkerd control plane are -running an old version. We recommend downloading the latest Linkerd release -and [Upgrading Linkerd](../../upgrade/). +running an old version. We recommend downloading the latest Linkerd release and +[Upgrading Linkerd](../../upgrade/). ### √ control plane proxies and cli versions match {#l5d-cp-proxy-cli-version} @@ -990,8 +1053,8 @@ Example failure: config.linkerd.io/control-port ``` -`config.linkerd.io/*` or `config.alpha.linkerd.io/*` should -be annotations in order to take effect. +`config.linkerd.io/*` or `config.alpha.linkerd.io/*` should be annotations in +order to take effect. ### √ data plane service annotations are configured correctly {#l5d-data-plane-services-annotations} @@ -1004,8 +1067,7 @@ Example failure: mirror.linkerd.io/exported ``` -`mirror.linkerd.io/exported` should -be a label in order to take effect. +`mirror.linkerd.io/exported` should be a label in order to take effect. ### √ opaque ports are properly annotated {#linkerd-opaque-ports-definition} @@ -1020,11 +1082,11 @@ Example failure: If a Pod marks a port as opaque by using the `config.linkerd.io/opaque-ports` annotation, then any Service which targets that port must also use the `config.linkerd.io/opaque-ports` annotation to mark that port as opaque. Having -a port marked as opaque on the Pod but not the Service (or vice versa) can -cause inconsistent behavior depending on if traffic is sent to the Pod directly -(for example with a headless Service) or through a ClusterIP Service. This -error can be remedied by adding the `config.linkerd.io/opaque-ports` annotation -to both the Pod and Service. See +a port marked as opaque on the Pod but not the Service (or vice versa) can cause +inconsistent behavior depending on if traffic is sent to the Pod directly (for +example with a headless Service) or through a ClusterIP Service. This error can +be remedied by adding the `config.linkerd.io/opaque-ports` annotation to both +the Pod and Service. See [Protocol Detection](../../features/protocol-detection/) for more information. ## The "linkerd-ha-checks" checks {#l5d-ha} @@ -1071,11 +1133,10 @@ replicas running. This is likely caused by insufficient node resources. ### The "extensions" checks {#extensions} -When any [Extensions](../extensions/) are installed, The Linkerd binary -tries to invoke `check --output json` on the extension binaries. -It is important that the extension binaries implement it. -For more information, See [Extension -developer docs](https://github.com/linkerd/linkerd2/blob/main/EXTENSIONS.md) +When any [Extensions](../extensions/) are installed, The Linkerd binary tries to +invoke `check --output json` on the extension binaries. It is important that the +extension binaries implement it. For more information, See +[Extension developer docs](https://github.com/linkerd/linkerd2/blob/main/EXTENSIONS.md) Example error: @@ -1083,8 +1144,9 @@ Example error: invalid extension check output from \"jaeger\" (JSON object expected) ``` -Make sure that the extension binary implements `check --output json` -which returns the healthchecks in the [expected json format](https://github.com/linkerd/linkerd2/blob/main/EXTENSIONS.md#linkerd-name-check). +Make sure that the extension binary implements `check --output json` which +returns the healthchecks in the +[expected json format](https://github.com/linkerd/linkerd2/blob/main/EXTENSIONS.md#linkerd-name-check). Example error: @@ -1262,10 +1324,10 @@ Done configuring CNI. Sleep=true ## The "linkerd-multicluster checks {#l5d-multicluster} These checks run if the service mirroring controller has been installed. -Additionally they can be ran with `linkerd multicluster check`. -Most of these checks verify that the service mirroring controllers are working -correctly along with remote gateways. Furthermore the checks ensure that -end to end TLS is possible between paired clusters. +Additionally they can be ran with `linkerd multicluster check`. Most of these +checks verify that the service mirroring controllers are working correctly along +with remote gateways. Furthermore the checks ensure that end to end TLS is +possible between paired clusters. ### √ Link CRD exists {#l5d-multicluster-link-crd-exists} @@ -1308,8 +1370,8 @@ Example error: see https://linkerd.io/checks/#l5d-smc-target-clusters-access for hints ``` -Make sure the relevant Kube-config with relevant permissions. -for the specific target cluster is present as a secret correctly +Make sure the relevant Kube-config with relevant permissions. for the specific +target cluster is present as a secret correctly ### √ clusters share trust anchors {#l5d-multicluster-clusters-share-anchors} @@ -1483,12 +1545,11 @@ Example errors: ``` The error above indicates that some mirror services in the source cluster do not -have associated link. These mirror services are created by the Linkerd -service mirror controller when a remote service is marked to be -mirrored. +have associated link. These mirror services are created by the Linkerd service +mirror controller when a remote service is marked to be mirrored. -Make sure services are marked to be mirrored correctly at remote, and delete -if there are any unnecessary ones. +Make sure services are marked to be mirrored correctly at remote, and delete if +there are any unnecessary ones. ### √ multicluster extension proxies are healthy {#l5d-multicluster-proxy-healthy} @@ -1499,37 +1560,37 @@ correct setting or re-install as necessary. ### √ multicluster extension proxies are up-to-date {#l5d-multicluster-proxy-cp-version} This warning indicates the proxies running in the multicluster extension are -running an old version. We recommend downloading the latest linkerd-multicluster +running an old version. We recommend downloading the latest linkerd-multicluster and upgrading. ### √ multicluster extension proxies and cli versions match {#l5d-multicluster-proxy-cli-version} -This warning indicates that the proxies running in the multicluster extension are -running a different version from the Linkerd CLI. We recommend keeping this -versions in sync by updating either the CLI or linkerd-multicluster as necessary. +This warning indicates that the proxies running in the multicluster extension +are running a different version from the Linkerd CLI. We recommend keeping this +versions in sync by updating either the CLI or linkerd-multicluster as +necessary. ## The "linkerd-viz" checks {#l5d-viz} -These checks only run when the `linkerd-viz` extension is installed. -This check is intended to verify the installation of linkerd-viz -extension which comprises of `tap`, `web`, -`metrics-api` and optional `grafana` and `prometheus` instances -along with `tap-injector` which injects the specific -tap configuration to the proxies. +These checks only run when the `linkerd-viz` extension is installed. This check +is intended to verify the installation of linkerd-viz extension which comprises +of `tap`, `web`, `metrics-api` and optional `grafana` and `prometheus` instances +along with `tap-injector` which injects the specific tap configuration to the +proxies. ### √ linkerd-viz Namespace exists {#l5d-viz-ns-exists} -This is the basic check used to verify if the linkerd-viz extension -namespace is installed or not. The extension can be installed by running -the following command: +This is the basic check used to verify if the linkerd-viz extension namespace is +installed or not. The extension can be installed by running the following +command: ```bash linkerd viz install | kubectl apply -f - ``` -The installation can be configured by using the -`--set`, `--values`, `--set-string` and `--set-file` flags. -See [Linkerd Viz Readme](https://www.github.com/linkerd/linkerd2/tree/main/viz/charts/linkerd-viz/README.md) +The installation can be configured by using the `--set`, `--values`, +`--set-string` and `--set-file` flags. See +[Linkerd Viz Readme](https://www.github.com/linkerd/linkerd2/tree/main/viz/charts/linkerd-viz/README.md) for a full list of configurable fields. ### √ linkerd-viz ClusterRoles exist {#l5d-viz-cr-exists} @@ -1591,21 +1652,20 @@ yes ### √ viz extension proxies are healthy {#l5d-viz-proxy-healthy} -This error indicates that the proxies running in the viz extension are -not healthy. Ensure that linkerd-viz has been installed with all of the -correct setting or re-install as necessary. +This error indicates that the proxies running in the viz extension are not +healthy. Ensure that linkerd-viz has been installed with all of the correct +setting or re-install as necessary. ### √ viz extension proxies are up-to-date {#l5d-viz-proxy-cp-version} -This warning indicates the proxies running in the viz extension are -running an old version. We recommend downloading the latest linkerd-viz -and upgrading. +This warning indicates the proxies running in the viz extension are running an +old version. We recommend downloading the latest linkerd-viz and upgrading. ### √ viz extension proxies and cli versions match {#l5d-viz-proxy-cli-version} -This warning indicates that the proxies running in the viz extension are -running a different version from the Linkerd CLI. We recommend keeping this -versions in sync by updating either the CLI or linkerd-viz as necessary. +This warning indicates that the proxies running in the viz extension are running +a different version from the Linkerd CLI. We recommend keeping this versions in +sync by updating either the CLI or linkerd-viz as necessary. ### √ tap API server has valid cert {#l5d-tap-cert-valid} @@ -1641,9 +1701,9 @@ Example failure: see https://linkerd.io/checks/#l5d-webhook-cert-not-expiring-soon for hints ``` -This warning indicates that the expiry of the tap API Server webhook -cert is approaching. In order to address this -problem without incurring downtime, you can follow the process outlined in +This warning indicates that the expiry of the tap API Server webhook cert is +approaching. In order to address this problem without incurring downtime, you +can follow the process outlined in [Automatically Rotating your webhook TLS Credentials](../automatically-rotating-webhook-tls-credentials/). ### √ tap api service is running {#l5d-tap-api} @@ -1720,8 +1780,7 @@ Make sure that the `proxy-injector` is working correctly by running see https://linkerd.io/checks/#l5d-viz-cr-exists for hints ``` -Ensure all the prometheus related resources are present and running -correctly. +Ensure all the prometheus related resources are present and running correctly. ```bash ❯ kubectl -n linkerd-viz get deploy,cm | grep prometheus @@ -1800,7 +1859,7 @@ Prometheus to scrape the data plane proxies in a namespace: linkerd viz allow-scrapes --namespace emojivoto | kubectl apply -f - ``` -Note that this warning *only* checks for the existence of the policy resources +Note that this warning _only_ checks for the existence of the policy resources generated by `linkerd viz allow-scrapes` in namespaces that contain pods with the `deny` default inbound policy. In some cases, Prometheus scrapes may also be authorized by other, user-generated authorization policies. If metrics from the @@ -1834,38 +1893,37 @@ You should see all your pods here. If they are not: ## The "linkerd-jaeger" checks {#l5d-jaeger} -These checks only run when the `linkerd-jaeger` extension is installed. -This check is intended to verify the installation of linkerd-jaeger -extension which comprises of open-census collector and jaeger -components along with `jaeger-injector` which injects the specific -trace configuration to the proxies. +These checks only run when the `linkerd-jaeger` extension is installed. This +check is intended to verify the installation of linkerd-jaeger extension which +comprises of open-census collector and jaeger components along with +`jaeger-injector` which injects the specific trace configuration to the proxies. ### √ linkerd-jaeger extension Namespace exists {#l5d-jaeger-ns-exists} -This is the basic check used to verify if the linkerd-jaeger extension -namespace is installed or not. The extension can be installed by running -the following command +This is the basic check used to verify if the linkerd-jaeger extension namespace +is installed or not. The extension can be installed by running the following +command ```bash linkerd jaeger install | kubectl apply -f - ``` -The installation can be configured by using the -`--set`, `--values`, `--set-string` and `--set-file` flags. -See [Linkerd Jaeger Readme](https://www.github.com/linkerd/linkerd2/tree/main/jaeger/charts/linkerd-jaeger/README.md) +The installation can be configured by using the `--set`, `--values`, +`--set-string` and `--set-file` flags. See +[Linkerd Jaeger Readme](https://www.github.com/linkerd/linkerd2/tree/main/jaeger/charts/linkerd-jaeger/README.md) for a full list of configurable fields. ### √ jaeger extension proxies are healthy {#l5d-jaeger-proxy-healthy} -This error indicates that the proxies running in the jaeger extension are -not healthy. Ensure that linkerd-jaeger has been installed with all of the -correct setting or re-install as necessary. +This error indicates that the proxies running in the jaeger extension are not +healthy. Ensure that linkerd-jaeger has been installed with all of the correct +setting or re-install as necessary. ### √ jaeger extension proxies are up-to-date {#l5d-jaeger-proxy-cp-version} -This warning indicates the proxies running in the jaeger extension are -running an old version. We recommend downloading the latest linkerd-jaeger -and upgrading. +This warning indicates the proxies running in the jaeger extension are running +an old version. We recommend downloading the latest linkerd-jaeger and +upgrading. ### √ jaeger extension proxies and cli versions match {#l5d-jaeger-proxy-cli-version} @@ -1917,10 +1975,10 @@ Make sure that the `proxy-injector` is working correctly by running ## The "linkerd-buoyant" checks {#l5d-buoyant} -These checks only run when the `linkerd-buoyant` extension is installed. -This check is intended to verify the installation of linkerd-buoyant -extension which comprises `linkerd-buoyant` CLI, the `buoyant-cloud-agent` -Deployment, and the `buoyant-cloud-metrics` DaemonSet. +These checks only run when the `linkerd-buoyant` extension is installed. This +check is intended to verify the installation of linkerd-buoyant extension which +comprises `linkerd-buoyant` CLI, the `buoyant-cloud-agent` Deployment, and the +`buoyant-cloud-metrics` DaemonSet. ### √ Linkerd extension command linkerd-buoyant exists