本文档涵盖 kubectl 的安装配置、常用命令、高级技巧以及生产环境最佳实践，适用于 Kubernetes 日常运维和故障排查。
kubectl 是 Kubernetes 的命令行工具，用于与集群进行交互。
# macOS (使用 Homebrew)
brew install kubectl
# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
# Windows (使用 Chocolatey)
choco install kubernetes-cli
在 GKE (Google Kubernetes Engine) 中使用 kubectl 需要额外安装认证插件：
# 安装 GKE 认证插件
gcloud components install gke-gcloud-auth-plugin
# 查看可用集群列表
gcloud container clusters list
# 获取指定集群的凭据（以新加坡区域 staging 集群为例）
gcloud container clusters get-credentials platform-preprod-sg --zone asia-southeast1
踩坑记录：GKE 在 2022 年后要求必须使用
gke-gcloud-auth-plugin进行认证，旧的基于客户端证书的方式已被废弃。如果未安装插件，kubectl 会报错Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found。
kubectl 通过 ~/.kube/config 文件管理集群连接信息，包含：
# 查看所有上下文
kubectl config get-contexts
# 查看当前上下文
kubectl config current-context
# 切换上下文
kubectl config use-context <context-name>
# 设置默认命名空间
kubectl config set-context --current --namespace=<namespace>
# 查看完整配置
kubectl config view
# 查看特定集群配置
kubectl config view --minify
# 合并多个 kubeconfig 文件
export KUBECONFIG=~/.kube/config:~/.kube/prod-config:~/.kube/staging-config
# 或者使用 kubectl 内置合并
kubectl config view --flatten > ~/.kube/merged-config
export KUBECONFIG=~/.kube/merged-config
# 查看所有 Pod
kubectl get pods
# 查看所有命名空间的 Pod
kubectl get pods --all-namespaces
# 查看特定命名空间
kubectl get pods -n <namespace>
# 查看更详细信息（包括 IP、节点等）
kubectl get pods -o wide
# 查看资源使用标签选择器
kubectl get pods -l app=nginx
# 查看多种资源类型
kubectl get pods,services,deployments
# 查看节点
kubectl get nodes
# 查看节点详细信息
kubectl get nodes -o wide
# 查看 Pod 详细信息
kubectl describe pod <pod-name>
# 查看 Deployment 详情
kubectl describe deployment <deployment-name>
# 查看事件（排查问题必备）
kubectl get events
kubectl get events --sort-by='.lastTimestamp'
# 查看特定类型事件
kubectl get events --field-selector type=Warning
# 通过 YAML 创建资源
kubectl apply -f deployment.yaml
# 创建多个资源
kubectl apply -f ./manifests/
# 从标准输入创建
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Namespace
metadata:
name: my-namespace
EOF
# 删除资源
kubectl delete -f deployment.yaml
# 删除特定 Pod
kubectl delete pod <pod-name>
# 强制删除（不等待优雅终止）
kubectl delete pod <pod-name> --force --grace-period=0
# 应用更新
kubectl apply -f deployment.yaml
# 滚动更新镜像
kubectl set image deployment/nginx nginx=nginx:1.21
# 编辑资源（交互式）
kubectl edit deployment nginx
# 打标签
kubectl label pod <pod-name> env=production
# 添加注解
kubectl annotate pod <pod-name> description="test pod"
# 查看 Pod 日志
kubectl logs <pod-name>
# 查看多容器 Pod 中特定容器的日志
kubectl logs <pod-name> -c <container-name>
# 实时跟踪日志（类似 tail -f）
kubectl logs -f <pod-name>
# 查看之前容器的日志（Pod 重启后）
kubectl logs <pod-name> --previous
# 查看最近 100 行日志
kubectl logs --tail=100 <pod-name>
# 查看带时间戳的日志
kubectl logs <pod-name> --timestamps
# 在 Pod 中执行命令
kubectl exec <pod-name> -- ls /app
# 进入容器交互式 Shell
kubectl exec -it <pod-name> -- /bin/sh
# 进入多容器 Pod 的特定容器
kubectl exec -it <pod-name> -c <container-name> -- /bin/bash
# 在特定节点上调试（使用临时 Pod）
kubectl debug node/<node-name> -it --image=busybox
# 查看 Pod 状态详情
kubectl get pod <pod-name> -o yaml
# 查看 Pod 的资源使用
kubectl top pod <pod-name>
# 查看 Pod 中所有容器的资源使用
kubectl top pod <pod-name> --containers
# 复制文件到 Pod
kubectl cp ./local-file.txt <pod-name>:/app/
# 从 Pod 复制文件到本地
kubectl cp <pod-name>:/app/log.txt ./local-log.txt
# 查看所有服务
kubectl get svc
# 查看服务详情
kubectl describe svc <service-name>
原内容示例输出：
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE kubernetes ClusterIP 10.67.38.1 <none> 443/TCP 2y77d
# 将本地端口转发到 Pod 端口
kubectl port-forward <pod-name> 8080:80
# 将本地端口转发到服务（最常用）
kubectl -n staging port-forward service/approval-service 9090:9090
# 后台运行端口转发
kubectl port-forward <pod-name> 8080:80 &
# 转发 Deployment 的所有 Pod
kubectl port-forward deployment/nginx 8080:80
最佳实践：端口转发主要用于本地开发和调试，不适合生产环境长期使用。生产环境应通过 Ingress 或 LoadBalancer 暴露服务。
# 从 Pod 内部测试网络连通性
kubectl exec -it <pod-name> -- ping <target-ip>
# 使用临时调试 Pod
kubectl run debug --rm -it --image=nicolaka/netshoot -- /bin/bash
# 查看 Service 的 Endpoints
kubectl get endpoints <service-name>
# 查看网络策略
kubectl get networkpolicies
# 从文件创建 ConfigMap
kubectl create configmap app-config --from-file=config.json
# 从字面量创建
kubectl create configmap app-config \
--from-literal=database_url=postgres://localhost:5432/mydb
# 查看 ConfigMap
kubectl get configmap <config-name> -o yaml
# 创建 Secret（从字面量）
kubectl create secret generic db-password \
--from-literal=password=mysecretpassword
# 创建 Secret（从文件）
kubectl create secret tls tls-cert \
--cert=path/to/cert.crt --key=path/to/key.key
# 查看 Secret（值会被 base64 编码）
kubectl get secret <secret-name> -o jsonpath='{.data.password}' | base64 -d
# 查看 PersistentVolume
kubectl get pv
# 查看 PersistentVolumeClaim
kubectl get pvc
# 查看 StorageClass
kubectl get storageclass
# 查看 Pod 资源使用（需要 metrics-server）
kubectl top pod
# 查看节点资源使用
kubectl top node
# 查看资源配额
kubectl get resourcequota
# 查看限制范围
kubectl get limitrange
# 1. 查看 Pod 状态
kubectl get pods -n <namespace>
# 2. 查看 Pod 详情和事件
kubectl describe pod <pod-name> -n <namespace>
# 3. 查看日志
kubectl logs <pod-name> -n <namespace>
# 4. 查看之前容器的日志（如果 Pod 重启过）
kubectl logs <pod-name> -n <namespace> --previous
# 5. 进入容器检查
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh
# 删除所有 Evicted Pod
kubectl get pods --all-namespaces | grep Evicted | \
awk '{print $2 " --namespace=" $1}' | \
xargs -L1 kubectl delete pod
# 强制删除所有 Terminating Pod
kubectl get pods --all-namespaces | grep Terminating | \
awk '{print $2 " --namespace=" $1}' | \
xargs -L1 kubectl delete pod --force
# 给所有节点打标签
kubectl get nodes -o name | \
xargs -I {} kubectl label {} env=production
Kubernetes 提供了 kompose 工具，可以将 Docker Compose 文件自动转换为 Kubernetes 资源定义。
# macOS
curl -L https://github.com/kubernetes/kompose/releases/download/v1.26.0/kompose-darwin-amd64 -o kompose
chmod +x kompose
sudo mv ./kompose /usr/local/bin/kompose
# Linux
curl -L https://github.com/kubernetes/kompose/releases/download/v1.26.0/kompose-linux-amd64 -o kompose
chmod +x kompose
sudo mv ./kompose /usr/local/bin/kompose
# 转换并输出到控制台
kompose convert -f docker-compose.yaml --stdout
# 转换并生成文件
kompose convert -f docker-compose.yaml
# 直接部署到 Kubernetes
kompose up -f docker-compose.yaml
# 清理部署的资源
kompose down -f docker-compose.yaml
注意事项：
- Kompose 转换的是基础结构，复杂的网络配置、卷挂载可能需要手动调整
- 生产环境建议审查生成的 YAML 文件后再应用
- 某些 Docker Compose 特性（如
depends_on）在 Kubernetes 中没有直接对应，需要额外配置
# 使用 RBAC 限制权限
kubectl create role developer --verb=get,list,watch --resource=pods,services
kubectl create rolebinding dev-binding --role=developer --user=developer
# 查看当前用户的权限
kubectl auth can-i create pods
kubectl auth can-i '*' '*'
# 设置资源配额
kubectl create quota compute-resources \
--hard=limits.cpu=10,limits.memory=20Gi,pods=100,services=10
# 查看资源使用
kubectl top nodes
kubectl top pods --all-namespaces
# 查看 Pod 分布
kubectl get pods -o wide --all-namespaces
# 设置 Pod 反亲和性（分散部署）
# 在 Deployment 的 spec.template.spec.affinity 中配置
# 导出所有资源
kubectl get all --all-namespaces -o yaml > cluster-backup.yaml
# 导出特定命名空间
kubectl get all -n <namespace> -o yaml > namespace-backup.yaml
# 使用 Velero 进行完整备份（推荐生产环境）
# velero backup create my-backup --include-namespaces my-namespace
| 命令 | 说明 |
|---|---|
kubectl get pods |
查看 Pod 列表 |
kubectl get pods -o wide |
查看 Pod 详细信息 |
kubectl get pods --all-namespaces |
查看所有命名空间的 Pod |
kubectl describe pod <name> |
查看 Pod 详情 |
kubectl logs <name> |
查看 Pod 日志 |
kubectl logs -f <name> |
实时跟踪日志 |
kubectl exec -it <name> -- /bin/sh |
进入容器 |
| 命令 | 说明 |
|---|---|
kubectl apply -f <file> |
应用配置 |
kubectl delete -f <file> |
删除资源 |
kubectl get svc |
查看服务 |
kubectl get nodes |
查看节点 |
kubectl get events |
查看事件 |
| 命令 | 说明 |
|---|---|
kubectl port-forward <pod> 8080:80 |
端口转发到 Pod |
kubectl port-forward svc/<name> 8080:80 |
端口转发到服务 |
kubectl proxy |
启动 API 代理 |
| 命令 | 说明 |
|---|---|
kubectl config get-contexts |
查看上下文 |
kubectl config current-context |
查看当前上下文 |
kubectl config use-context <name> |
切换上下文 |
kubectl get configmap <name> |
查看 ConfigMap |
kubectl get secret <name> |
查看 Secret |
| 命令 | 说明 |
|---|---|
kubectl top pod |
查看 Pod 资源使用 |
kubectl top node |
查看节点资源使用 |
kubectl get events --sort-by='.lastTimestamp' |
按时间排序事件 |
kubectl describe node <name> |
查看节点详情 |