Skip to content

Commit 1b56dc5

Browse files
Affan-7windsonsea
Affan-7
and
windsonsea
authored
Add a task page for troubleshooting kubectl (#42347)
* Add troubleshoot-kubectl-connectivity.md * Add overview * Add body * Update content/en/docs/tasks/debug/debug-cluster/_index.md Co-authored-by: Michael <[email protected]> * Modify note in _index.md * Add prerequisites section * Fix API server section * Fix TLS section * Fix heading formatting * Change the title * Revise prerequisites * Drop the note * Fix some nits --------- Co-authored-by: Michael <[email protected]>
1 parent a269016 commit 1b56dc5

File tree

2 files changed

+161
-0
lines changed

2 files changed

+161
-0
lines changed

‎content/en/docs/tasks/debug/debug-cluster/_index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ problem you are experiencing. See
1414
the [application troubleshooting guide](/docs/tasks/debug/debug-application/) for tips on application debugging.
1515
You may also visit the [troubleshooting overview document](/docs/tasks/debug/) for more information.
1616

17+
For troubleshooting {{<glossary_tooltip text="kubectl" term_id="kubectl">}}, refer to
18+
[Troubleshooting kubectl](/docs/tasks/debug/debug-cluster/troubleshoot-kubectl/).
19+
1720
<!-- body -->
1821

1922
## Listing your cluster

‎content/en/docs/tasks/debug/debug-cluster/troubleshoot-kubectl.md

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: "Troubleshooting kubectl"
3+
content_type: task
4+
weight: 10
5+
---
6+
7+
<!-- overview -->
8+
9+
This documentation is about investigating and diagnosing
10+
{{<glossary_tooltip text="kubectl" term_id="kubectl">}} related issues.
11+
If you encounter issues accessing `kubectl` or connecting to your cluster, this
12+
document outlines various common scenarios and potential solutions to help
13+
identify and address the likely cause.
14+
15+
<!-- body -->
16+
17+
## {{% heading "prerequisites" %}}
18+
19+
* You need to have a Kubernetes cluster.
20+
* You also need to have `kubectl` installed - see [install tools](/docs/tasks/tools/#kubectl)
21+
22+
## Verify kubectl setup
23+
24+
Make sure you have installed and configured `kubectl` correctly on your local machine.
25+
Check the `kubectl` version to ensure it is up-to-date and compatible with your cluster.
26+
27+
Check kubectl version:
28+
29+
```shell
30+
kubectl version
31+
```
32+
33+
You'll see a similar output:
34+
35+
```console
36+
Client Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.4",GitCommit:"fa3d7990104d7c1f16943a67f11b154b71f6a132", GitTreeState:"clean",BuildDate:"2023-07-19T12:20:54Z", GoVersion:"go1.20.6", Compiler:"gc", Platform:"linux/amd64"}
37+
Kustomize Version: v5.0.1
38+
Server Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.3",GitCommit:"25b4e43193bcda6c7328a6d147b1fb73a33f1598", GitTreeState:"clean",BuildDate:"2023-06-14T09:47:40Z", GoVersion:"go1.20.5", Compiler:"gc", Platform:"linux/amd64"}
39+
40+
```
41+
42+
If you see `Unable to connect to the server: dial tcp <server-ip>:8443: i/o timeout`,
43+
instead of `Server Version`, you need to troubleshoot kubectl connectivity with your cluster.
44+
45+
Make sure you have installed the kubectl by following the
46+
[official documentation for installing kubectl](/docs/tasks/tools/#kubectl), and you have
47+
properly configured the `$PATH` environment variable.
48+
49+
## Check kubeconfig
50+
51+
The `kubectl` requires a `kubeconfig` file to connect to a Kubernetes cluster. The
52+
`kubeconfig` file is usually located under the `~/.kube/config` directory. Make sure
53+
that you have a valid `kubeconfig` file. If you don't have a `kubeconfig` file, you can
54+
obtain it from your Kubernetes administrator, or you can copy it from your Kubernetes
55+
control plane's `/etc/kubernetes/admin.conf` directory. If you have deployed your
56+
Kubernetes cluster on a cloud platform and lost your `kubeconfig` file, you can
57+
re-generate it using your cloud provider's tools. Refer the cloud provider's
58+
documentation for re-generating a `kubeconfig` file.
59+
60+
Check if the `$KUBECONFIG` environment variable is configured correctly. You can set
61+
`$KUBECONFIG`environment variable or use the `--kubeconfig` parameter with the kubectl
62+
to specify the directory of a `kubeconfig` file.
63+
64+
## Check VPN connectivity
65+
66+
If you are using a Virtual Private Network (VPN) to access your Kubernetes cluster,
67+
make sure that your VPN connection is active and stable. Sometimes, VPN disconnections
68+
can lead to connection issues with the cluster. Reconnect to the VPN and try accessing
69+
the cluster again.
70+
71+
## Authentication and authorization
72+
73+
If you are using the token based authentication and the kubectl is returning an error
74+
regarding the authentication token or authentication server address, validate the
75+
Kubernetes authentication token and the authentication server address are configured
76+
properly.
77+
78+
If kubectl is returning an error regarding the authorization, make sure that you are
79+
using the valid user credentials. And you have the permission to access the resource
80+
that you have requested.
81+
82+
## Verify contexts
83+
84+
Kubernetes supports [multiple clusters and contexts](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
85+
Ensure that you are using the correct context to interact with your cluster.
86+
87+
List available contexts:
88+
89+
```shell
90+
kubectl config get-contexts
91+
```
92+
93+
Switch to the appropriate context:
94+
95+
```shell
96+
kubectl config use-context <context-name>
97+
```
98+
99+
## API server and load balancer
100+
101+
The {{<glossary_tooltip text="kube-apiserver" term_id="kube-apiserver">}} server is the
102+
central component of a Kubernetes cluster. If the API server or the load balancer that
103+
runs in front of your API servers is not reachable or not responding, you won't be able
104+
to interact with the cluster.
105+
106+
Check the if the API server's host is reachable by using `ping` command. Check cluster's
107+
network connectivity and firewall. If your are using a cloud provider for deploying
108+
the cluster, check your cloud provider's health check status for the cluster's
109+
API server.
110+
111+
Verify the status of the load balancer (if used) to ensure it is healthy and forwarding
112+
traffic to the API server.
113+
114+
## TLS problems
115+
116+
The Kubernetes API server only serves HTTPS requests by default. In that case TLS problems
117+
may occur due to various reasons, such as certificate expiry or chain of trust validity.
118+
119+
You can find the TLS certificate in the kubeconfig file, located in the `~/.kube/config`
120+
directory. The `certificate-authority` attribute contains the CA certificate and the
121+
`client-certificate` attribute contains the client certificate.
122+
123+
Verify the expiry of these certificates:
124+
125+
```shell
126+
openssl x509 -noout -dates -in $(kubectl config view --minify --output 'jsonpath={.clusters[0].cluster.certificate-authority}')
127+
```
128+
129+
output:
130+
```console
131+
notBefore=Sep 2 08:34:12 2023 GMT
132+
notAfter=Aug 31 08:34:12 2033 GMT
133+
```
134+
135+
```shell
136+
openssl x509 -noout -dates -in $(kubectl config view --minify --output 'jsonpath={.users[0].user.client-certificate}')
137+
```
138+
139+
output:
140+
```console
141+
notBefore=Sep 2 08:34:12 2023 GMT
142+
notAfter=Sep 2 08:34:12 2026 GMT
143+
```
144+
145+
## Verify kubectl helpers
146+
147+
Some kubectl authentication helpers provide easy access to Kubernetes clusters. If you
148+
have used such helpers and are facing connectivity issues, ensure that the necessary
149+
configurations are still present.
150+
151+
Check kubectl configuration for authentication details:
152+
153+
```shell
154+
kubectl config view
155+
```
156+
157+
If you previously used a helper tool (for example, `kubectl-oidc-login`), ensure that it is still
158+
installed and configured correctly.

0 commit comments

Comments
 (0)