Kubectl on Liangweidong's blog

K8s 集群运维命令大全：kubectl 速查 + 节点维护 + harbor 私有仓库

Tue, 15 Oct 2024 00:00:00 +0800

kubectl 是 K8s 运维的"瑞士军刀"

K8s 1.28 时代的运维 90% 都靠 kubectl 完成。本文是"速查手册"——按场景分类，所有命令都可以直接复制粘贴。

适用版本：kubectl ≥ 1.28 / K8s 1.28.5

1. 基础环境

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 启用命令补全
apt install -y bash-completion
echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

# 所有用户生效
kubectl completion bash | sudo tee /etc/bash_completion.d/kubectl > /dev/null

# 设置别名
echo 'alias k=kubectl' >> ~/.bashrc
source ~/.bashrc

# 设置默认 namespace
kubectl config set-context --current --namespace=rook-ceph

2. 资源查看

2.1 kubectl get 简写表

名称	简写	示例	说明
`pods`	`po`	`k get po -A`	Pod
`services`	`svc`	`k get svc -A`	Service
`deployments`	`deploy`	`k get deploy -A`	Deployment
`statefulsets`	`sts`	`k get sts -A`	StatefulSet
`daemonsets`	`ds`	`k get ds -A`	DaemonSet
`nodes`	`no`	`k get no`	Node
`namespaces`	`ns`	`k get ns`	Namespace
`configmaps`	`cm`	`k get cm -A`	ConfigMap
`secrets`		`k get secret -A`	Secret
`persistentvolumes`	`pv`	`k get pv`	PV
`persistentvolumeclaims`	`pvc`	`k get pvc -A`	PVC
`ingresses`	`ing`	`k get ing -A`	Ingress
`storageclasses`	`sc`	`k get sc`	StorageClass
`events`	`ev`	`k get ev -A`	Event

2.2 常用查询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 看所有 kind
kubectl api-resources --verbs=list --namespaced -o name

# 全集群资源
kubectl get all -o wide -A

# 命名空间下所有资源
kubectl api-resources --verbs=list --namespaced -o name | \
 xargs -n 1 kubectl get --show-kind --ignore-not-found -n <namespace>

# 看 image
kubectl get deployment <name> -n <ns> -o jsonpath='{.spec.template.spec.containers[0].image}'

# 镜像与版本
kubectl api-versions

2.3 节点负载

1
2


kubectl top node
kubectl top pod -A

3. 节点管理

3.1 节点状态

1
2
3
4
5
6
7
8


# 查询节点
kubectl get node

# 节点标签
kubectl label nodes worker2 mysql-node=tenant1
kubectl label nodes worker2 mysql-node- # 删除
kubectl get nodes --show-labels
kubectl label nodes worker9 --list

3.2 节点污点（Taints）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 添加污点
kubectl taint nodes master3 node-role.kubernetes.io/master3=:NoSchedule
# 去除
kubectl taint nodes master3 node-role.kubernetes.io/master3-

# Rook-Ceph 专用污点（不让普通 Pod 调度到 mon 节点）
kubectl taint nodes master3 dedicated=ceph:NoSchedule --overwrite

# Rook-Ceph Pod 加容忍度
# kubectl -n rook-ceph edit deploy rook-ceph-operator
# 在 spec.template.spec.tolerations 中加：
tolerations:
 - key: "dedicated"
 operator: "Equal"
 value: "ceph"
 effect: "NoSchedule"

3.3 节点隔离与驱逐

1
2
3
4
5
6
7
8


# 标记不可调度
kubectl cordon master1

# 驱逐 Pod
kubectl drain master1 --delete-emptydir-data --ignore-daemonsets --force

# 恢复调度
kubectl uncordon master1

3.4 删除节点

1
2


kubectl delete node master1
# 节点上的 kubelet 进程会自动停

4. Pod 运维

4.1 查 Pod

1
2
3
4
5


kubectl get po -owide -n <ns>
kubectl get pods -n <ns> | grep redis | awk '{print $1}'

# 详细
kubectl describe po -n kube-system metrics-server-7745c6dfc5-8sjjc

4.2 日志

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 单容器
kubectl logs -f <pod> -n <ns>

# 多容器
kubectl logs -f <pod> -c <container> -n <ns>

# 用标签
kubectl logs -f --tail=100 -l app=nginx -n test

# 时间范围
kubectl logs --since=9h -l app=app -n test
kubectl logs --since-time="2024-12-15T00:00:00Z" -l app=app -n test

4.3 执行命令

1
2
3
4
5
6
7
8
9


# 单次
kubectl exec <pod> -n <ns> -- nslookup kubernetes

# 交互
kubectl exec -it <pod> -- sh
kubectl exec -it <pod> -c <container> -- sh

# 临时容器（K8s 1.23+，调试 CrashLoopBackOff 神器）
kubectl debug -it <pod> --image=busybox:1.28 --target=<container>

4.4 删除

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 正常
kubectl delete po <pod> -n <ns>
kubectl delete -f deployment.yaml

# 强制
kubectl delete po <pod> -n <ns> --grace-period=0 --force
kubectl delete po calico-kube-controllers-546dcc6886-mf8rt -n kube-system --force --grace-period=0

# 批量删 Error
kubectl delete po $(kubectl get po | grep Error | awk '{print $1}')

# 批量删非 Running
kubectl delete pod -n <ns> $(kubectl get pods -n <ns> | grep -v "Running" | awk '{print $1}') --force --grace-period=0

4.5 副本数

1
2


kubectl scale --replicas=1 deployment/<name> -n <ns>
kubectl -n kube-system scale --replicas=10 deployment/coredns

4.6 强制重启

1
2


kubectl rollout restart deployment/<name> -n <ns>
kubectl rollout status deployment/<name> -n <ns>

5. Deployment 高级

5.1 版本回滚

1
2
3
4
5
6
7
8
9


# 记录版本（apply 时 --record 已废弃，用 annotate）
kubectl annotate deployment/<name> kubernetes.io/change-cause="image updated"

# 历史
kubectl rollout history deployment/<name>

# 回滚
kubectl rollout undo deployment/<name>
kubectl rollout undo deployment/<name> --to-revision=2

5.2 HPA（自动扩缩）

1
2
3


# 设置 HPA（注意：设了 HPA 后不能手动 scale）
kubectl autoscale deployment <name> -n <ns> --min=1 --max=1
kubectl edit hpa <name> -n <ns>

5.3 测试压测

1
2


kubectl run -i --tty load-generator --rm --image=busybox:1.28 --restart=Never -- \
 /bin/sh -c "while sleep 0.01; do wget -q -O- http://php-apache; done"

6. Secret 与 harbor

6.1 创建 harbor secret

1
2
3
4
5


kubectl create secret docker-registry harbor-secret \
 --docker-server=<harbor-host>:13001 \
 --docker-username=admin \
 --docker-password={{HARBOR_PASSWORD}} \
 -n <ns>

真实密码用占位符 {{HARBOR_PASSWORD}} 替代。

6.2 Pod 引用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: v1
kind: Pod
metadata:
 name: pod-harbor
spec:
 containers:
 - name: c1
 image: <harbor-host>:13001/test/nginx:v1
 imagePullSecrets:
 - name: harbor-secret

6.3 docker daemon.json（提前配）

所有节点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "exec-opts": ["native.cgroupdriver=systemd"],
 "log-driver": "json-file",
 "log-opts": { "max-size": "50m", "max-file": "1" },
 "registry-mirrors": [
 "https://<your-mirror>.mirror.aliyuncs.com",
 "https://docker.m.daocloud.io",
 "https://hub-mirror.c.163.com"
 ],
 "insecure-registries": ["<harbor-host>:13001"]
}

6.4 Token（admin 登录）

1

kubectl -n kube-system create token admin-user

7. 内部网络测试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 创建测试 pod
kubectl run -it --rm busybox --image=busybox:1.28 -- nslookup mine-backend.test

# 测试 DNS
kubectl run busybox --image=busybox:1.28 -- sleep 3600
kubectl exec -it busybox -- sh
nslookup kubernetes.default
nslookup extend-service.test

# 跨 namespace 解析
kubectl exec busybox -n default -- nslookup safety-auth.safety-hnpre.svc.cluster.local

修改 CoreDNS 配置后重启：

1
2
3
4
5
6
7
8
9


kubectl edit configmap coredns -n kube-system

# 改 forward 段
forward . __PILLAR__CLUSTER__DNS__ {
 prefer_udp
 max_concurrent 1000
}

kubectl rollout restart deploy/coredns -n kube-system

8. 命名空间与 finalizers

8.1 命名空间管理

1
2
3


kubectl create ns <name>
kubectl delete ns <name>
kubectl get ns

8.2 namespace 卡 Terminating

1
2
3
4
5
6


ns=cattle-fleet-system
kubectl get namespace $ns -o json | jq '.metadata.finalizers=[]' | \
 kubectl replace --raw "/api/v1/namespaces/$ns/finalize" -f -

# 通用 patch
kubectl patch ns rook-ceph --type=merge -p '{"metadata":{"finalizers":null}}'

8.3 PVC 卡 Terminating

1
2
3
4


kubectl patch pvc jenkins-agent-pvc -n kube-ops --type=merge -p '{"metadata":{"finalizers":null}}'

kubectl patch pv pvc-c87554c7-6b20-42ed-8cdd-8be1d630a744 \
 -p '{"metadata":{"finalizers":null}}' --type=merge

9. 排错速查表

现象	命令	解决
节点 NotReady	`kubectl describe node <n>`	查 Conditions
Pod Pending	`kubectl describe po <p>`	查 Events
Pod CrashLoopBackOff	`kubectl logs <p> --previous`	看上一次容器日志
Service 不通	`kubectl get ep`	ep 是不是有后端 Pod
NodePort 外网访问不了	`kubectl get svc -o yaml`	type=NodePort, nodePort 范围
DNS 不通	`kubectl exec <p> -- nslookup kubernetes`	CoreDNS Pod 状态
镜像拉不到	`kubectl describe po <p>`	检查 imagePullSecrets
PVC Pending	`kubectl describe pvc`	StorageClass 配额 / 节点亲和
HPA 不会缩	`kubectl describe hpa`	看 metrics-server 是否正常
升级失败	`kubectl rollout undo`	回滚

10. 小结

kubectl 命令覆盖 K8s 运维的 80% 场景：

get + describe + logs 是排障三件套
rollout undo 是版本回滚神器
drain + cordon 是节点维护的标配
drain + delete node 是缩容的标配
patch … finalizers=null 是 namespace 卡死的杀手锏

下一步：K8s 集群升级与卸载：版本升级 + finalizers 清理。

K8s 集群管理：升级 / 节点隔离 / 常用 API 与排错清单

Wed, 15 Dec 2021 00:00:00 +0800

写于 2021-12，背景：K8s 1.23 GA，1.24 即将引入对 dockershim 移除。本文聚焦"集群日常运维"——升级、节点隔离、API 速查与排错清单。

一、kubectl 命令速查

1.1 资源操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# 查看（-o wide 显示节点，-A 所有 namespace）
kubectl get all -o wide -A
kubectl get pods -n test
kubectl get nodes -o wide

# 描述（看详细事件）
kubectl describe pod <pod-name> -n <ns>
kubectl describe node <node-name>

# 日志
kubectl logs -f <pod-name> -n <ns>
kubectl logs -f <pod-name> -c <container-name> -n <ns> # 多容器 Pod
kubectl logs --previous <pod-name> -n <ns> # 上一个崩溃实例

# 进入容器
kubectl exec -it <pod-name> -n <ns> -- sh
kubectl exec -it <pod-name> -c <container> -n <ns> -- sh

# 删除
kubectl delete pod <pod-name> -n <ns>
kubectl delete -f deployment.yaml
kubectl delete ns <ns-name>

# 强制删除卡 Terminating 的 Pod
kubectl delete pod <pod-name> -n <ns> --grace-period=0 --force

# 编辑（直接改集群里的配置）
kubectl edit deployment <name> -n <ns>
kubectl edit cm <configmap> -n <ns>

# apply / replace
kubectl apply -f deployment.yaml
kubectl replace -f deployment.yaml --force

1.2 排错三剑客

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# describe：看 Event，最常用
kubectl describe pod <pod> -n <ns>
# 关键信息：
# Events:
# Type Reason Age From Message
# ---- ------ ---- ---- -------
# Normal Scheduled 60s default-scheduler Successfully assigned ...
# Normal Pulling 58s kubelet Pulling image "nginx:1.25"
# Warning Failed 30s kubelet Failed to pull image: ... timeout

# logs：看容器内输出
kubectl logs -f <pod> -n <ns>
kubectl logs --previous <pod> -n <ns> # 上一个实例

# exec：进容器内部
kubectl exec -it <pod> -n <ns> -- sh

二、版本升级

重要原则：K8s 一年发 4 个版本（1.24+），生产不要追新；只升补丁版本（z 版本）几乎零风险，升次要版本（y 版本）要谨慎。

2.1 升级前准备

检查项	命令
当前版本	`kubectl version`
节点数	`kubectl get nodes`
是否有运行中的 workload	`kubectl get pods -A`
备份 etcd	`etcdctl snapshot save /tmp/etcd.db`
备份 /etc/kubernetes	`cp -r /etc/kubernetes /etc/kubernetes.bak`
备份证书	`cp -r /etc/kubernetes/pki /etc/kubernetes/pki.bak`

2.2 升级流程（小版本，如 1.28.5 → 1.28.8）

步骤：

升级 master 节点（先升级第一个，验证后再升级其他）
升级 worker 节点（一次一个）
验证

master1 操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 1. 备份
mkdir -p /usr/local/bin/bak
mv /usr/local/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy} /usr/local/bin/bak

# 2. 下载新包
wget https://dl.k8s.io/v1.28.8/kubernetes-server-linux-amd64.tar.gz
# （生产环境建议从内网文件服务器拉取）

# 3. 解压到 /usr/local/bin
tar -xf kubernetes-server-linux-amd64.tar.gz \
 --strip-components=3 -C /usr/local/bin \
 kubernetes/server/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy}

# 4. 重启组件
systemctl restart kube-apiserver.service
systemctl restart kube-controller-manager.service
systemctl restart kube-scheduler.service
systemctl restart kubelet.service
systemctl restart kube-proxy.service

# 5. 验证
kubectl version
kubectl get nodes

其他 master 节点（master2 / master3）：

1
2
3
4
5
6
7


# 一键批量升级
for NODE in master2 master3; do
 echo "===== $NODE ====="
 ssh $NODE "mkdir -p /usr/local/bin/bak && mv /usr/local/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy} /usr/local/bin/bak"
 scp /usr/local/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy} $NODE:/usr/local/bin/
 ssh $NODE "systemctl restart kube-apiserver kube-controller-manager kube-scheduler kubelet kube-proxy"
done

worker 节点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# worker 只跑 kubelet + kube-proxy
for NODE in worker1 worker2 worker3; do
 echo "===== $NODE ====="
 # 先 cordon + drain（见下节）
 kubectl cordon $NODE
 kubectl drain $NODE --delete-local-data --ignore-daemonsets --force
 
 # 升级
 ssh $NODE "mkdir -p /usr/local/bin/bak && mv /usr/local/bin/kube{let,-proxy} /usr/local/bin/bak"
 scp /usr/local/bin/kube{let,-proxy} $NODE:/usr/local/bin/
 ssh $NODE "systemctl restart kubelet kube-proxy"
 
 # 验证 + uncordon
 sleep 30
 kubectl uncordon $NODE
done

2.3 升级验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 所有节点版本一致
kubectl get nodes
# NAME STATUS ROLES AGE VERSION
# master1 Ready control-plane 50d v1.28.8
# master2 Ready control-plane 50d v1.28.8
# master3 Ready control-plane 50d v1.28.8
# worker1 Ready <none> 30d v1.28.8
# worker2 Ready <none> 30d v1.28.8

# 集群健康
kubectl get cs
kubectl get pods -A | grep -v Running

三、节点隔离：cordon / drain / uncordon

K8s 提供 3 个状态机操作：

命令	作用	是否驱逐 Pod
`kubectl cordon <node>`	标记节点 unschedulable	否
`kubectl drain <node>`	cordon + 驱逐所有 Pod	是
`kubectl uncordon <node>`	恢复 schedulable	否

3.1 维护前的标准操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 1. cordon：禁止新 Pod 调度上来
kubectl cordon master1
# node/master1 cordoned

# 2. drain：驱逐现有 Pod
kubectl drain master1 --delete-local-data --ignore-daemonsets --force
# --delete-local-data：删除带 emptyDir 的 Pod
# --ignore-daemonsets：忽略 DaemonSet（kube-proxy / calico 不能被驱逐）
# --force：强制驱逐没有 PDB 保护的 Pod

# 3. 维护：升级内核 / 改网络 / 重启 etcd
...

# 4. uncordon：恢复
kubectl uncordon master1
# node/master1 uncordoned

3.2 查看节点上的所有 Pod

1
2
3
4
5
6
7


# 某个节点上所有 Pod
kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=worker2

# 批量删除（驱逐后用）
kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=worker2 | \
 grep -v "kube-system" | awk '{print $1,$2}' | \
 xargs -n2 kubectl delete pod -n

四、强制删除卡住的 Pod

症状：kubectl delete pod xxx 后 Pod 一直 Terminating（>5 分钟）。

原因：

Pod 里有容器没响应 SIGTERM
Pod 有 finalizer 卡住
kubelet 与 apiserver 通信异常

解决：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 强制删除（跳过 graceful period）
kubectl delete pod <pod> -n <ns> --grace-period=0 --force

# 还是卡？看 finalizer
kubectl get pod <pod> -n <ns> -o yaml | grep finalizers

# 移除 finalizer（必须先 kubectl edit）
kubectl edit pod <pod> -n <ns>
# 删除 metadata.finalizers 字段，保存

# 再删
kubectl delete pod <pod> -n <ns> --force --grace-period=0

五、备份与恢复

5.1 etcd 备份

1
2
3
4
5
6
7
8
9


# 在每个 etcd 节点执行（或一个能访问所有 etcd 的节点）
ETCDCTL_API=3 etcdctl snapshot save /tmp/etcd-snapshot-$(date +%Y%m%d).db \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/etcd/ssl/etcd-ca.pem \
 --cert=/etc/etcd/ssl/etcd.pem \
 --key=/etc/etcd/ssl/etcd-key.pem

# 验证
etcdctl snapshot status /tmp/etcd-snapshot-20231215.db --write-out=table

定时备份（crontab）：

1

0 2 * * * /usr/local/bin/etcd-backup.sh >> /var/log/etcd-backup.log 2>&1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


#!/bin/bash
# /usr/local/bin/etcd-backup.sh
BACKUP_DIR=/var/backups/etcd
mkdir -p $BACKUP_DIR
ETCDCTL_API=3 etcdctl snapshot save $BACKUP_DIR/etcd-$(date +\%Y\%m\%d-\%H\%M\%S).db \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/etcd/ssl/etcd-ca.pem \
 --cert=/etc/etcd/ssl/etcd.pem \
 --key=/etc/etcd/ssl/etcd-key.pem
# 保留 7 天
find $BACKUP_DIR -name "etcd-*.db" -mtime +7 -delete

5.2 etcd 恢复

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


# 1. 停所有 master 上的 apiserver（避免新数据写入）
for NODE in master1 master2 master3; do
 ssh $NODE "systemctl stop kube-apiserver"
done

# 2. 在每个 etcd 节点恢复
etcdctl snapshot restore /tmp/etcd-snapshot.db \
 --name master1 \
 --initial-cluster master1=https://192.168.139.133:2380,... \
 --initial-advertise-peer-urls https://192.168.139.133:2380 \
 --data-dir /var/lib/etcd-restore

# 3. 改 etcd.service 指向新 data-dir
# ExecStart=/usr/local/bin/etcd --config-file=/etc/etcd/etcd.config.yml
# 改 data-dir: /var/lib/etcd → /var/lib/etcd-restore

# 4. 启动 etcd
systemctl start etcd

# 5. 启动 apiserver
for NODE in master1 master2 master3; do
 ssh $NODE "systemctl start kube-apiserver"
done

# 6. 验证
kubectl get nodes

六、master 节点 IP 更换

K8s master 节点 IP 变了（机房迁移），需要：

替换 /etc/kubernetes 下所有 IP
替换 /etc/etcd/etcd.config.yml IP
替换 kube-apiserver systemd unit
重新签发证书（新 IP 必须在证书 hostname 列表里）
重启所有组件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


# 1. 替换配置
oldip=192.168.0.121
newip=192.168.133.121

find /etc/kubernetes -type f -exec grep -l "$oldip" {} \;
find /etc/kubernetes -type f -exec sed -i "s/$oldip/$newip/g" {} \;

find /etc/etcd/etcd.config.yml -type f -exec grep -l "$oldip" {} \;
find /etc/etcd/etcd.config.yml -type f -exec sed -i "s/$oldip/$newip/g" {} \;

# 2. 重新签发所有证书（用新 IP）
cd /data/softs/pki
cfssl gencert -initca etcd-ca-csr.json | cfssljson -bare /etc/etcd/ssl/etcd-ca
cfssl gencert -ca=/etc/etcd/ssl/etcd-ca.pem -ca-key=/etc/etcd/ssl/etcd-ca-key.pem \
 -config=ca-config.json \
 -hostname=127.0.0.1,master1,$newip \
 -profile=kubernetes etcd-csr.json | cfssljson -bare /etc/etcd/ssl/etcd
# ... 同样方式签发 apiserver / front-proxy / controller-manager / scheduler / admin / kube-proxy

# 3. 重新生成 kubeconfig
kubectl config set-cluster kubernetes --certificate-authority=/etc/kubernetes/pki/ca.pem \
 --embed-certs=true --server=https://$newip:6443 \
 --kubeconfig=/etc/kubernetes/admin.kubeconfig
# ... controller-manager / scheduler / kube-proxy / bootstrap 都重做

# 4. 重启
systemctl daemon-reload
systemctl restart kube-apiserver kube-controller-manager kube-scheduler
systemctl restart kubelet kube-proxy

七、排错清单

7.1 Pod 排错

症状	排查命令	原因
Pending	`kubectl describe pod` 看 Events	资源不够 / 节点 selector 不匹配 / PVC 未绑定
ImagePullBackOff	`kubectl describe pod`	镜像拉取失败（私有仓库 auth 错 / 镜像名错 / 网络问题）
CrashLoopBackOff	`kubectl logs --previous`	容器启动后立即退出（应用配置错 / OOMKilled）
ContainerCreating	`kubectl describe pod` + `kubectl get events`	volume 挂载失败 / CNI 没就绪
Error	`kubectl logs`	镜像启动命令失败 / 配置文件错

7.2 节点排错

症状	排查命令	原因
NotReady	`kubectl describe node`	kubelet 没起 / 网络不通 / 磁盘满
内存压力	`kubectl describe node`	节点压力驱逐 Pod

7.3 网络排错

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 同 Pod 内容器互通（同 Pod 共享网络）
kubectl exec -it pod1 -c c1 -- ping <pod2-ip>

# 同节点不同 Pod 互通
kubectl exec -it pod1 -- ping <pod2-ip>

# 跨节点 Pod 互通
kubectl exec -it pod1 -- ping <node2-ip>

# Service 解析
kubectl exec -it pod1 -- nslookup kubernetes.default

# Service 访问
kubectl exec -it pod1 -- curl http://<service-ip>:<port>

7.4 性能问题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 节点资源使用
kubectl top node
kubectl top pod -A

# 找最忙的 Pod
kubectl top pod -A --sort-by=memory | head -10
kubectl top pod -A --sort-by=cpu | head -10

# 找 Pending 原因
kubectl get pods -A | grep Pending
kubectl describe pod <pending-pod>

# kube-proxy 模式（iptables vs ipvs）
kubectl get cm kube-proxy -n kube-system -o yaml | grep mode

八、常见坑

升级大版本跳级：必须逐级升（1.27 → 1.28 → 1.29），不能 1.26 → 1.28 跳升
cordon 后忘了 uncordon：节点永久 unschedulable
drain 没加 –ignore-daemonsets：calico / kube-proxy 被驱逐，节点网络断
etcd 备份忘了定时：灾难时无法恢复
证书 hostname 漏配：节点迁移后 kubectl 报 x509 错误
kubeconfig 没更新：节点迁移后 kubectl 仍连老 IP

九、前置知识 / 下一步

前置：

K8s 集群完整部署（参考 2020-03-15《K8s 二进制部署》）
etcd 备份（参考 2020-09-15《etcd 集群部署》）

下一步：

K8s 资源限制与探针（2022-03-15）—— Pod 调优
Kubeadm 一键部署（2022-06-15）—— 生产部署实战

参考资料

K8s 工具链速装：kubectl / kubeadm / minikube / kind / helm

Sat, 15 Dec 2018 00:00:00 +0800

写于 2018-12，背景：K8s 1.13 GA、Helm v3 alpha 即将发布。客户端工具已经收敛到 kubectl/kubeadm/kubelet 三件套，本地实验工具有 minikube / kind 双雄，包管理是 helm。

一、工具全景图

K8s 生态里跟"集群打交道的"工具，按使用场景分四类：

场景	工具	角色
客户端	`kubectl`	必装，对集群执行命令的唯一官方 CLI
本地实验	`minikube` / `kind`	一键起本地 K8s 集群（学习/测试用）
集群初始化	`kubeadm`	官方推荐的集群 bootstrap 工具
包管理	`helm`	K8s 应用的包管理（类似 apt/yum）

二、kubectl 安装

2.1 二进制安装（推荐）

1
2
3
4
5
6
7
8
9


# 下载最新稳定版
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

# 验证
kubectl version --client
kubectl version --client --output=yaml

2.2 apt 安装

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 国外官方源
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | \
 sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | \
 sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubectl

# 国内阿里源（cn region 推荐）
curl https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | \
 gpg --dearmor > /usr/share/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/kubernetes-apt-keyring.gpg] https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main' | \
 sudo tee /etc/apt/sources.list.d/kubernetes.list
apt-get update && apt-get install -y kubectl

2.3 命令补全

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 装 bash-completion
apt-get install bash-completion

# 加到 .bashrc
echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

# 推荐别名：把 kubectl 缩成 k
alias k=kubectl
complete -F __start_kubectl k

2.4 kubectl-convert 转换工具

K8s API 经常废弃/迁移，旧的 Deployment extensions/v1beta1 在 1.16 之后要换成 apps/v1。kubectl-convert 一键转换：

1
2
3
4
5


curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl-convert"
sudo install -o root -g root -m 0755 kubectl-convert /usr/local/bin/kubectl-convert

# 把老 API 转换成新 API
kubectl-convert -f old-deployment.yaml --output-version apps/v1

三、kubeadm / kubelet 安装

kubeadm 用于初始化集群，kubelet 是 worker 节点上的核心 agent。它们必须和 kubectl 版本一致（同 minor 版本）：

1
2
3
4
5
6
7


# apt 安装
sudo apt-get install -y kubelet kubeadm kubectl
# 锁定版本，防止 apt upgrade 时被升级
sudo apt-mark hold kubelet kubeadm kubectl

# 查看可用版本
apt-cache madison kubeadm

为什么 lock 版本？ K8s minor 版本升级时 API 可能废弃，跨版本 kubectl 可能无法解析新格式的 manifest。生产环境永远锁版本。

四、minikube：本地 K8s 一体化

minikube 在你本机（Windows/macOS/Linux）启动一个单节点 K8s 集群，适合学习/开发。

4.1 安装

1
2
3
4
5
6


# Linux
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# 验证
minikube version

4.2 启动集群

1
2
3
4
5
6
7
8
9


# 默认 driver（Linux 通常是 docker，macOS 是 hyperkit，Windows 是 hyperv）
minikube start

# 显式指定
minikube start --driver=docker --kubernetes-version=v1.28.5

# 国内环境加代理
minikube start --docker-env http_proxy=http://192.168.x.x:7890 \
 --docker-env https_proxy=http://192.168.x.x:7890

4.3 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


minikube status # 集群状态
minikube ip # 集群 IP
minikube ssh # SSH 进节点
minikube dashboard --url # Dashboard URL
minikube addons enable metrics-server

# 镜像操作（minikube 自带 docker）
minikube image list
minikube image pull nginx:latest

# 清理
minikube delete --purge --all

五、kind：Docker-in-Docker 集群

kind（Kubernetes in Docker）用 Docker 容器模拟 K8s 节点，可以快速起多节点集群做测试。

5.1 安装

1
2
3
4
5
6


# AMD64 / x86_64
[ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
# ARM64
[ $(uname -m) = aarch64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-arm64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

5.2 与 minikube 对比

维度	minikube	kind
实现	VM / 容器	纯 Docker 容器
多节点	实验性	一等公民（multi-node config）
启动速度	较慢（拉镜像+启动 VM）	很快（共享 host docker 缓存）
适合场景	个人学习、单节点	CI/CD、e2e 测试、多节点演练

注意：kind 集群不能用于生产。它的"集群"本质是 Docker 容器，节点宕机 = 容器被回收，etcd 数据可能丢。

六、Helm：K8s 包管理

Helm 把 K8s 资源打成一个 “Chart”（类似 Debian 的 .deb / Python 的 wheel），方便应用分发和版本管理。

6.1 安装

1
2
3
4
5
6
7


# 下载
curl -L -O https://get.helm.sh/helm-v3.13.3-linux-amd64.tar.gz
tar xvf helm-v3.13.3-linux-amd64.tar.gz
sudo cp linux-amd64/helm /usr/local/bin/

# 验证
helm version

6.2 三大概念

概念	含义
Chart	应用包（yaml 模板 + values.yaml）
Release	Chart 的一个部署实例（同一 Chart 可装多次，每次一个 release）
Repository	Chart 仓库（公共有 artifacthub.io）

6.3 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 添加仓库
helm repo add bitnami https://charts.bitnami.com/bitnami

# 搜索 chart
helm search repo nginx

# 安装（会生成一个 release）
helm install my-nginx bitnami/nginx

# 查看已安装
helm list -A

# 升级（改 values 后）
helm upgrade my-nginx bitnami/nginx --set replicaCount=3

# 回滚
helm rollback my-nginx 1

# 卸载
helm uninstall my-nginx

七、工具选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


你是要学习 K8s 概念？
 ↓
minikube start （最简单）
 ↓
你需要快速拉起多节点做 CI 测试？
 ↓
kind （Docker 容器，秒级启动）
 ↓
你要部署生产集群？
 ↓
kubeadm init（最常见）
 或
二进制部署（理解原理，2017-2018 主流）
 ↓
你要分发应用到多个集群？
 ↓
helm chart + 私有 repo

八、常见坑

kubectl 与集群版本不一致：kubectl get nodes 报 “couldn’t get version” 时，先 kubectl version 看 client/server 版本
apt 源没换 cn：国外源拉 kubectl 慢到怀疑人生，先换阿里源
minikube 启动失败：99% 是 driver 问题，Linux 推荐 docker，macOS 用 hyperkit
kind 容器间网络不通：通常是因为 host 防火墙，iptables 临时关一下验证
Helm v2 → v3 迁移：v2 还需要 Tiller（一个集群内 agent），v3 完全去除了，更安全

九、前置知识 / 下一步

前置：Docker 基础、K8s 架构概念（参考 2017-06-15《Kubernetes 入门》）

下一步：

Containerd 实战（2019-12-15）—— 替代 Docker 的轻量容器运行时
K8s 二进制部署（2020-03-15）—— 深入理解组件协作
Kubeadm 一键部署（2022-06-15）—— 生产环境部署实战

参考资料

2024+ 视角

K8s 工具链到 2024-2026 年整体走向"轻量化 + 声明式 + 多云"：

kubectl 被 Krew 增强：Krew 已成为 kubectl 插件事实标准（200+ 插件），推荐安装 ctx、ns、tail、images、resource-capacity、node-shell、mtail 等，把 kubectl 从 CLI 升级为"瑞士军刀"。
kind 持续领先本地多节点测试：kind v0.20+ 支持 loadbalancer mirror（模拟云 LB）、Ingress dual-stack、extraPortMappings；CI 集成（GitHub Actions、GitLab CI）首选 kind + MetalLB。k3d（k3s on Docker）在低资源 CI 环境也很流行。
minikube 地位变化：v1.32+ minikube 默认 driver 仍为 docker，但实际场景已被 kind/k3d 蚕食——CI 几乎全用 kind/k3d，个人学习仍可用 minikube（自带 dashboard、metrics-server addon）。
Helm 4.0 路线图（2025）：v3.x 仍是主流，但 Helm 4 计划将 --dependency-build 改为 helm dependency up 单一命令、引入 OCI registry 默认（Helm 3.8 已支持 OCI，Helm 4 默认全 OCI）。生产强烈建议 OCI 化——避免 HTTP tgz repo 不可达。
新工具崛起：
- k9s（终端 TUI，kubectl 的视觉化）——运维日常神器
- Lens / OpenLens（桌面 IDE）—— 团队协作场景
- Argo CD / Flux（GitOps）—— K8s 部署的事实标准
- Karpenter（AWS）或 Cluster Autoscaler（多云）——节点自动扩缩容
- Kustomize（裸 YAML 模板）—— 已被 kubectl 1.14+ 内置，kubectl apply -k
包管理二分：Helm 仍是 Chart 的事实标准，KubeVela / Open Application Model（OAM） 在多云/多集群部署场景作为补充。

实战选型更新（2024 视角）：

本地学习：minikube（dashboard 加分）
CI 集成：kind（首选） / k3d（低资源）
生产部署：Helm 3 + OCI + Argo CD（GitOps）
运维日常：k9s + Krew
集群自扩缩：Karpenter（AWS）或 Cluster Autoscaler（多云）

2018 年这篇的"kubectl/kubeadm/kind/helm 四件套"基础仍然成立，变化的是 OCI、GitOps、可视化运维这三层。