容器与云原生 / 系统课时
安装与配置 kubectl
安装与配置 kubectl
kubectl 是操作 Kubernetes API 的命令行客户端。本课将完成客户端安装、kubeconfig 接入、集群连通性验证与上下文切换;结束后,你能确认自己正在使用哪个集群、身份和命名空间,避免把命令发往错误环境。
学习目标
- 安装与校验适合当前系统架构的
kubectl。 - 理解 kubeconfig 中集群、用户与上下文的组合关系。
- 查看集群状态,并安全切换上下文和默认命名空间。
安装前检查
kubectl 客户端应与 API Server 保持兼容,通常不要相差超过一个次版本。安装前还要确认操作系统、CPU 架构,以及是否已经从集群管理员、云平台或本地集群工具取得可信的 kubeconfig。不要直接使用来源不明的配置文件,因为其中可能包含凭据或外部认证命令。
下面的 POSIX Shell 示例适用于 Linux 与 macOS,会自动识别系统和常见 CPU 架构,下载当前稳定版、校验 SHA-256,并安装到 /usr/local/bin。执行前需要 curl、校验工具和 sudo 权限。
set -euo pipefail
os="$(uname -s | tr '[:upper:]' '[:lower:]')"
case "$(uname -m)" in
x86_64) arch="amd64" ;;
aarch64|arm64) arch="arm64" ;;
*) echo "Unsupported architecture: $(uname -m)"; exit 1 ;;
esac
version="$(curl -L -s https://dl.k8s.io/release/stable.txt)"
curl -LO "https://dl.k8s.io/release/${version}/bin/${os}/${arch}/kubectl"
curl -LO "https://dl.k8s.io/release/${version}/bin/${os}/${arch}/kubectl.sha256"
if [ "${os}" = "darwin" ]; then
echo "$(cat kubectl.sha256) kubectl" | shasum -a 256 --check
else
echo "$(cat kubectl.sha256) kubectl" | sha256sum --check
fi
if [ "${os}" = "darwin" ]; then
sudo install -o root -g wheel -m 0755 kubectl /usr/local/bin/kubectl
else
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
fi
kubectl version --client
rm -f kubectl kubectl.sha256预期输出中的具体版本取决于执行日期,但校验必须成功,客户端版本信息必须能够正常显示。
kubectl: OK
Client Version: v<MAJOR>.<MINOR>.<PATCH>Windows 可在 PowerShell 中使用 winget 安装,并立即验证命令是否进入 PATH。
winget install -e --id Kubernetes.kubectl
kubectl version --client预期结果是安装命令成功结束,并显示客户端版本;安装器的进度文本会随 winget 版本变化。
Client Version: v<MAJOR>.<MINOR>.<PATCH>理解 kubeconfig
kubeconfig 不是某个固定文件名,而是一类集群访问配置。它主要保存 clusters、users 和 contexts:集群条目提供 API Server 地址与证书信息,用户条目提供认证方式,上下文把一个集群、一个用户和可选命名空间组合成可切换的工作环境。

默认情况下,kubectl 读取 $HOME/.kube/config。也可以用 --kubeconfig 指定单个文件,或通过 KUBECONFIG 合并多个文件。下面把管理员提供的可信配置复制到默认位置,并限制文件权限。
mkdir -p "$HOME/.kube"
cp "<PATH>" "$HOME/.kube/config"
chmod 600 "$HOME/.kube/config"
kubectl config get-contexts
kubectl config current-context
kubectl cluster-info
kubectl get nodes预期结果是当前上下文前带 *,控制面地址可访问,并至少看到一个处于 Ready 状态的节点。名称、地址、角色和版本会因集群而异。
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* dev-context dev-cluster dev-user default
dev-context
Kubernetes control plane is running at https://<HOST>:<PORT>
NAME STATUS ROLES AGE VERSION
<NODE> Ready <ROLE> <AGE> v<MAJOR>.<MINOR>.<PATCH>切换上下文与命名空间
执行任何写操作前,先读取当前上下文。切换后再设置默认命名空间,可以减少每条命令重复填写 -n,但也会放大误操作风险,因此生产环境应使用醒目的上下文名称并在部署前再次核对。
kubectl config use-context "<CONTEXT>"
kubectl config set-context --current --namespace="<NAMESPACE>"
kubectl config current-context
kubectl config view --minify预期输出会确认上下文已切换;view --minify 只显示当前生效的集群、身份与命名空间。
Switched to context "<CONTEXT>".
Context "<CONTEXT>" modified.
<CONTEXT>处理常见连接问题
出现 connection refused 时,优先检查 kubeconfig 路径、当前上下文和 API Server 地址;出现 Unauthorized 通常表示认证失败,Forbidden 则说明身份已确认但缺少 RBAC 权限。证书错误应核对系统时间、CA 数据和服务端域名,不要用 --insecure-skip-tls-verify 作为长期修复。
可用以下命令完成最小诊断。auth can-i 返回 yes 才表示当前身份允许读取 Pod;若返回 no,应申请权限而不是更换未知凭据。
kubectl config view --minify
kubectl cluster-info
kubectl auth can-i get pods --all-namespaces权限充足且连接正常时,最后一条命令的预期输出为:
yes