270 lines
10 KiB
Markdown
270 lines
10 KiB
Markdown
---
|
||
title: "kubectl 故障排查"
|
||
content_type: task
|
||
weight: 10
|
||
---
|
||
<!--
|
||
title: "Troubleshooting kubectl"
|
||
content_type: task
|
||
weight: 10
|
||
-->
|
||
|
||
<!-- overview -->
|
||
|
||
<!--
|
||
This documentation is about investigating and diagnosing
|
||
{{<glossary_tooltip text="kubectl" term_id="kubectl">}} related issues.
|
||
If you encounter issues accessing `kubectl` or connecting to your cluster, this
|
||
document outlines various common scenarios and potential solutions to help
|
||
identify and address the likely cause.
|
||
-->
|
||
本文讲述研判和诊断 {{<glossary_tooltip text="kubectl" term_id="kubectl">}} 相关的问题。
|
||
如果你在访问 `kubectl` 或连接到集群时遇到问题，本文概述了各种常见的情况和可能的解决方案，
|
||
以帮助确定和解决可能的原因。
|
||
|
||
<!-- body -->
|
||
|
||
## {{% heading "prerequisites" %}}
|
||
|
||
<!--
|
||
* You need to have a Kubernetes cluster.
|
||
* You also need to have `kubectl` installed - see [install tools](/docs/tasks/tools/#kubectl)
|
||
-->
|
||
* 你需要有一个 Kubernetes 集群。
|
||
* 你还需要安装好 `kubectl`，参见[安装工具](/zh-cn/docs/tasks/tools/#kubectl)。
|
||
|
||
<!--
|
||
## Verify kubectl setup
|
||
|
||
Make sure you have installed and configured `kubectl` correctly on your local machine.
|
||
Check the `kubectl` version to ensure it is up-to-date and compatible with your cluster.
|
||
|
||
Check kubectl version:
|
||
-->
|
||
## 验证 kubectl 设置 {#verify-kubectl-setup}
|
||
|
||
确保你已在本机上正确安装和配置了 `kubectl`。
|
||
检查 `kubectl` 版本以确保其是最新的，并与你的集群兼容。
|
||
|
||
检查 kubectl 版本：
|
||
|
||
```shell
|
||
kubectl version
|
||
```
|
||
|
||
<!--
|
||
You'll see a similar output:
|
||
-->
|
||
你将看到类似的输出：
|
||
|
||
```console
|
||
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"}
|
||
Kustomize Version: v5.0.1
|
||
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"}
|
||
```
|
||
|
||
<!--
|
||
If you see `Unable to connect to the server: dial tcp <server-ip>:8443: i/o timeout`,
|
||
instead of `Server Version`, you need to troubleshoot kubectl connectivity with your cluster.
|
||
|
||
Make sure you have installed the kubectl by following the
|
||
[official documentation for installing kubectl](/docs/tasks/tools/#kubectl), and you have
|
||
properly configured the `$PATH` environment variable.
|
||
-->
|
||
如果你看到 `Unable to connect to the server: dial tcp <server-ip>:8443: i/o timeout`，
|
||
而不是 `Server Version`，则需要解决 kubectl 与你集群的连接问题。
|
||
|
||
确保按照 [kubectl 官方安装文档](/zh-cn/docs/tasks/tools/#kubectl)安装了 kubectl，
|
||
并正确配置了 `$PATH` 环境变量。
|
||
|
||
<!--
|
||
## Check kubeconfig
|
||
|
||
The `kubectl` requires a `kubeconfig` file to connect to a Kubernetes cluster. The
|
||
`kubeconfig` file is usually located under the `~/.kube/config` directory. Make sure
|
||
that you have a valid `kubeconfig` file. If you don't have a `kubeconfig` file, you can
|
||
obtain it from your Kubernetes administrator, or you can copy it from your Kubernetes
|
||
control plane's `/etc/kubernetes/admin.conf` directory. If you have deployed your
|
||
Kubernetes cluster on a cloud platform and lost your `kubeconfig` file, you can
|
||
re-generate it using your cloud provider's tools. Refer the cloud provider's
|
||
documentation for re-generating a `kubeconfig` file.
|
||
-->
|
||
## 检查 kubeconfig {#check-kubeconfig}
|
||
|
||
`kubectl` 需要一个 `kubeconfig` 文件来连接到 Kubernetes 集群。
|
||
`kubeconfig` 文件通常位于 `~/.kube/config` 目录下。确保你有一个有效的 `kubeconfig` 文件。
|
||
如果你没有 `kubeconfig` 文件，可以从 Kubernetes 管理员那里获取，或者可以从 Kubernetes 控制平面的
|
||
`/etc/kubernetes/admin.conf` 目录复制这个文件。如果你在云平台上部署了 Kubernetes 集群并且丢失了你的
|
||
`kubeconfig` 文件，则可以使用云厂商的工具重新生成它。参考云厂商的文档以重新生成 `kubeconfig` 文件。
|
||
|
||
<!--
|
||
Check if the `$KUBECONFIG` environment variable is configured correctly. You can set
|
||
`$KUBECONFIG`environment variable or use the `--kubeconfig` parameter with the kubectl
|
||
to specify the directory of a `kubeconfig` file.
|
||
|
||
## Check VPN connectivity
|
||
|
||
If you are using a Virtual Private Network (VPN) to access your Kubernetes cluster,
|
||
make sure that your VPN connection is active and stable. Sometimes, VPN disconnections
|
||
can lead to connection issues with the cluster. Reconnect to the VPN and try accessing
|
||
the cluster again.
|
||
-->
|
||
检查 `$KUBECONFIG` 环境变量是否配置正确。你可以设置 `$KUBECONFIG` 环境变量，或者在
|
||
kubectl 中使用 `--kubeconfig` 参数来指定 `kubeconfig` 文件的目录。
|
||
|
||
## 检查 VPN 连接 {#check-vpn-connectivity}
|
||
|
||
如果你正在使用虚拟专用网络（VPN）访问 Kubernetes 集群，请确保你的 VPN 连接是可用且稳定的。
|
||
有时，VPN 断开连接可能会导致与集群的连接问题。重新连接到 VPN，并尝试再次访问集群。
|
||
|
||
<!--
|
||
## Authentication and authorization
|
||
|
||
If you are using the token based authentication and the kubectl is returning an error
|
||
regarding the authentication token or authentication server address, validate the
|
||
Kubernetes authentication token and the authentication server address are configured
|
||
properly.
|
||
|
||
If kubectl is returning an error regarding the authorization, make sure that you are
|
||
using the valid user credentials. And you have the permission to access the resource
|
||
that you have requested.
|
||
-->
|
||
## 身份认证和鉴权 {#authentication-and-authorization}
|
||
|
||
如果你正在使用基于令牌的身份认证，并且 kubectl 返回有关身份认证令牌或身份认证服务器地址的错误，
|
||
校验 Kubernetes 身份认证令牌和身份认证服务器地址是否被配置正确。
|
||
|
||
如果 kubectl 返回有关鉴权的错误，确保你正在使用有效的用户凭据，并且你具有访问所请求资源的权限。
|
||
|
||
<!--
|
||
## Verify contexts
|
||
|
||
Kubernetes supports [multiple clusters and contexts](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
|
||
Ensure that you are using the correct context to interact with your cluster.
|
||
|
||
List available contexts:
|
||
-->
|
||
## 验证上下文 {#verify-contexts}
|
||
|
||
Kubernetes 支持[多个集群和上下文](/zh-cn/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)。
|
||
确保你正在使用正确的上下文与集群进行交互。
|
||
|
||
列出可用的上下文：
|
||
|
||
```shell
|
||
kubectl config get-contexts
|
||
```
|
||
|
||
<!--
|
||
Switch to the appropriate context:
|
||
-->
|
||
切换到合适的上下文：
|
||
|
||
```shell
|
||
kubectl config use-context <context-name>
|
||
```
|
||
|
||
<!--
|
||
## API server and load balancer
|
||
|
||
The {{<glossary_tooltip text="kube-apiserver" term_id="kube-apiserver">}} server is the
|
||
central component of a Kubernetes cluster. If the API server or the load balancer that
|
||
runs in front of your API servers is not reachable or not responding, you won't be able
|
||
to interact with the cluster.
|
||
-->
|
||
## API 服务器和负载均衡器 {#api-server-and-load-balancer}
|
||
|
||
{{<glossary_tooltip text="kube-apiserver" term_id="kube-apiserver">}} 服务器是 Kubernetes
|
||
集群的核心组件。如果 API 服务器或运行在 API 服务器前面的负载均衡器不可达或没有响应，你将无法与集群进行交互。
|
||
|
||
<!--
|
||
Check the if the API server's host is reachable by using `ping` command. Check cluster's
|
||
network connectivity and firewall. If your are using a cloud provider for deploying
|
||
the cluster, check your cloud provider's health check status for the cluster's
|
||
API server.
|
||
|
||
Verify the status of the load balancer (if used) to ensure it is healthy and forwarding
|
||
traffic to the API server.
|
||
-->
|
||
通过使用 `ping` 命令检查 API 服务器的主机是否可达。检查集群的网络连接和防火墙。
|
||
如果你使用云厂商部署集群，请检查云厂商对集群的 API 服务器的健康检查状态。
|
||
|
||
验证负载均衡器（如果使用）的状态，确保其健康且转发流量到 API 服务器。
|
||
|
||
<!--
|
||
## TLS problems
|
||
|
||
The Kubernetes API server only serves HTTPS requests by default. In that case TLS problems
|
||
may occur due to various reasons, such as certificate expiry or chain of trust validity.
|
||
-->
|
||
## TLS 问题 {#tls-problems}
|
||
|
||
Kubernetes API 服务器默认只为 HTTPS 请求提供服务。在这种情况下，
|
||
TLS 问题可能会因各种原因而出现，例如证书过期或信任链有效性。
|
||
|
||
<!--
|
||
You can find the TLS certificate in the kubeconfig file, located in the `~/.kube/config`
|
||
directory. The `certificate-authority` attribute contains the CA certificate and the
|
||
`client-certificate` attribute contains the client certificate.
|
||
|
||
Verify the expiry of these certificates:
|
||
-->
|
||
你可以在 kubeconfig 文件中找到 TLS 证书，此文件位于 `~/.kube/config` 目录下。
|
||
`certificate-authority` 属性包含 CA 证书，而 `client-certificate` 属性则包含客户端证书。
|
||
|
||
验证这些证书的到期时间：
|
||
|
||
```shell
|
||
openssl x509 -noout -dates -in $(kubectl config view --minify --output 'jsonpath={.clusters[0].cluster.certificate-authority}')
|
||
```
|
||
|
||
<!--
|
||
output:
|
||
-->
|
||
输出为：
|
||
|
||
```console
|
||
notBefore=Sep 2 08:34:12 2023 GMT
|
||
notAfter=Aug 31 08:34:12 2033 GMT
|
||
```
|
||
|
||
```shell
|
||
openssl x509 -noout -dates -in $(kubectl config view --minify --output 'jsonpath={.users[0].user.client-certificate}')
|
||
```
|
||
|
||
<!--
|
||
output:
|
||
-->
|
||
输出为：
|
||
|
||
```console
|
||
notBefore=Sep 2 08:34:12 2023 GMT
|
||
notAfter=Sep 2 08:34:12 2026 GMT
|
||
```
|
||
|
||
<!--
|
||
## Verify kubectl helpers
|
||
|
||
Some kubectl authentication helpers provide easy access to Kubernetes clusters. If you
|
||
have used such helpers and are facing connectivity issues, ensure that the necessary
|
||
configurations are still present.
|
||
|
||
Check kubectl configuration for authentication details:
|
||
-->
|
||
## 验证 kubectl 助手 {#verify-kubectl-helpers}
|
||
|
||
某些 kubectl 身份认证助手提供了便捷访问 Kubernetes 集群的方式。
|
||
如果你使用了这些助手并且遇到连接问题，确保必要的配置仍然存在。
|
||
|
||
查看 kubectl 配置以了解身份认证细节：
|
||
|
||
```shell
|
||
kubectl config view
|
||
```
|
||
|
||
<!--
|
||
If you previously used a helper tool (for example, `kubectl-oidc-login`), ensure that it is still
|
||
installed and configured correctly.
|
||
-->
|
||
如果你之前使用了辅助工具（例如 `kubectl-oidc-login`），确保它仍然安装和配置正确。
|