kubernetes-operations

Kubernetes 运维

提供全面的 kubectl 辅助功能，涵盖调试、资源管理和集群运维，并通过节省令牌的脚本提高效率。

开始之前

此技能可避免 5 种常见错误，并节省约 70% 的令牌。

指标	未使用技能	使用技能
Pod 调试	约 1200 个令牌	约 400 个令牌
资源列表	约 800 个令牌	约 200 个令牌
集群健康状况	约 1500 个令牌	约 300 个令牌

此技能可避免的已知问题

1. 在错误的命名空间或上下文中运行 kubectl 命令
2. 冗长的输出将不必要的数据灌入上下文
3. 遗漏关键调试步骤（事件、之前的日志）
4. 以纯文本形式暴露机密
5. 未进行试运行验证就执行破坏性操作

快速开始

步骤 1：验证上下文

kubectl config current-context
kubectl config get-contexts

重要原因： 在错误的集群中运行命令可能导致生产事故。

步骤 2：调试 Pod

uv run scripts/debug_pod.py <pod-name> [-n namespace]

重要原因： 此脚本将 describe、日志和事件整合成精简摘要，可节省约 800 个令牌。

步骤 3：检查集群健康状况

uv run scripts/cluster_health.py

重要原因： 无需冗长输出，即可快速查看节点状态和不健康的 Pod。

重要规则

务必做到

• 操作前务必验证 kubectl config current-context
• 务必使用 -n namespace 明确指定目标
• 应用更改前务必使用 --dry-run=client -o yaml
• 调试时务必检查事件：kubectl get events --sort-by='.lastTimestamp'
• Pod 处于 CrashLoopBackOff 状态时，务必使用 --previous 标志

切勿

• 在生产环境中，未经 --dry-run 试运行，切勿运行 kubectl delete
• 切勿在未过滤的情况下输出机密：避免使用 kubectl get secret -o yaml
• 切勿假定使用默认命名空间，务必指定 -n
• 调试 OOMKilled 的 Pod 时，切勿忽略资源限制
• 日志未显示错误时，切勿跳过 describe

常见错误

错误示例：

kubectl logs my-pod

正确示例：

kubectl logs my-pod -n my-namespace --tail=100 --timestamps

原因： 默认命名空间可能不正确；无限制的日志会灌满上下文；时间戳有助于与事件关联。

避免已知问题

问题	根本原因	解决方案
CrashLoopBackOff	应用启动时崩溃	检查 kubectl logs --previous，并通过 describe 查看退出代码
ImagePullBackOff	仓库身份验证或镜像标签问题	确认镜像存在，并检查拉取密钥
Pending Pod	没有可调度的节点	检查节点资源以及 Pod 亲和性/容忍度
OOMKilled	超出内存限制	使用 kubectl top 检查容器限制与实际用量
连接被拒绝	Service 选择器不匹配	确认 Pod 标签与 Service 选择器相符

调试工作流

Pod 无法启动

# 1. Get pod status and events
kubectl describe pod <name> -n <namespace>

# 2. Check logs (current or previous)
kubectl logs <name> -n <namespace> --tail=100
kubectl logs <name> -n <namespace> --previous  # If restarting

# 3. Check events for scheduling issues
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | grep <name>

# 4. Interactive debugging
kubectl exec -it <name> -n <namespace> -- /bin/sh

Service 连通性

# 1. Verify service exists and has endpoints
kubectl get svc <name> -n <namespace>
kubectl get endpoints <name> -n <namespace>

# 2. Check pod labels match service selector
kubectl get pods -n <namespace> --show-labels

# 3. Test from within cluster
kubectl run debug --rm -it --image=busybox -- wget -qO- http://<service>:<port>

# 4. Port-forward for local testing
kubectl port-forward svc/<name> 8080:80 -n <namespace>

资源管理

Deployment

# List deployments
kubectl get deployments -n <namespace>

# Scale
kubectl scale deployment <name> --replicas=3 -n <namespace>

# Rollout status
kubectl rollout status deployment/<name> -n <namespace>

# Rollback
kubectl rollout undo deployment/<name> -n <namespace>

# History
kubectl rollout history deployment/<name> -n <namespace>

ConfigMap 和 Secret

# List
kubectl get configmaps -n <namespace>
kubectl get secrets -n <namespace>

# View ConfigMap data
kubectl get configmap <name> -n <namespace> -o jsonpath='{.data}'

# View Secret keys (NOT values)
kubectl get secret <name> -n <namespace> -o jsonpath='{.data}' | jq 'keys'

# Create from file
kubectl create configmap <name> --from-file=<path> -n <namespace> --dry-run=client -o yaml

集群运维

节点管理

# List nodes with status
kubectl get nodes -o wide

# Node details
kubectl describe node <name>

# Cordon (prevent scheduling)
kubectl cordon <node>

# Drain (evict pods)
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

# Uncordon
kubectl uncordon <node>

资源用量

# Node resources
kubectl top nodes

# Pod resources
kubectl top pods -n <namespace>

# Sort by memory
kubectl top pods -n <namespace> --sort-by=memory

捆绑资源

脚本

位于 scripts/：

• debug_pod.py - 全面的 Pod 调试，输出精简
• get_resources.py - 使用 jsonpath 生成资源摘要，尽量减少令牌用量
• cluster_health.py - 快速概览集群状态

参考资料

位于 references/：

• kubectl-cheatsheet.md - 精简的命令参考
• jsonpath-patterns.md - 常见 JSONPath 表达式
• debugging-flowchart.md - Pod 问题决策树

注意： 如需深入了解特定主题，请参阅上述参考文件。

依赖项

必需

软件包	版本	用途
kubectl	1.25+	Kubernetes 命令行界面
jq	1.6+	用于脚本的 JSON 解析

可选

软件包	版本	用途
k9s	0.27+	Kubernetes 终端界面
stern	1.25+	多 Pod 日志跟踪

官方文档

• kubectl 快速参考
• JSONPath 支持
• kubectl 速查表
• 调试运行中的 Pod

故障排除

找不到 kubectl 命令

症状： command not found: kubectl

解决方案：

# macOS
brew install kubectl

# Verify
kubectl version --client

未设置上下文

症状： error: no context is currently set

解决方案：

# List available contexts
kubectl config get-contexts

# Set context
kubectl config use-context <context-name>

权限被拒绝

症状： Error from server (Forbidden)

解决方案：

# Check current user
kubectl auth whoami

# Check permissions
kubectl auth can-i get pods -n <namespace>
kubectl auth can-i --list -n <namespace>

连接集群超时

症状： Unable to connect to the server: dial tcp: i/o timeout

解决方案：

# Check cluster endpoint
kubectl cluster-info

# Verify network connectivity
curl -k https://<cluster-api-endpoint>/healthz

# Check kubeconfig
cat ~/.kube/config

设置检查清单

使用此技能前，请确认：

• 已安装 kubectl（kubectl version --client）
• 已配置 Kubeconfig（~/.kube/config 存在）
• 上下文已设置为正确的集群（kubectl config current-context）
• 已验证权限（kubectl auth can-i get pods）
• 已安装用于 JSON 解析的 jq（jq --version）