kubectl

Kubectl 使用指南

📖 核心概念

💡 一句话解释

kubectl 是 Kubernetes 集群的“万能遥控器”，它通过命令行与集群的控制面（API Server）进行交互，从而管理整个集群的资源调度与运行。

如果把 Kubernetes 集群比作一个繁忙的集装箱码头：

Master Node (Control Plane) 是塔台指挥中心。
Worker Node 是停靠船只的码头泊位。
Pod 是集装箱。
kubectl 就是操作员手中的对讲机/控制台，你发出的每一个指令（部署、扩容、销毁）都通过它传达给指挥中心。

⚙️ 原理与配置

Kubeconfig 配置管理

kubeconfig 文件存储了集群的访问凭证（User）、集群地址（Cluster）和上下文（Context）。

🛠️ 多集群管理技巧

如果需要同时管理多个集群，可以将多个配置文件放在 ~/.kube/ 目录下，利用环境变量 KUBECONFIG 进行聚合。

# 环境变量聚合配置
export KUBECONFIG=~/.kube/config:~/.kube/config-prod:~/.kube/config-test

# 查看合并后的配置
kubectl config view

# 切换当前操作的上下文（集群/Namespace）
kubectl config use-context <context_name>

# 查看所有上下文列表
kubectl config get-contexts

# 合并多个 kubeconfig 文件为一个（物理合并）
KUBECONFIG=config1:config2 kubectl config view --merge --flatten > merged_config.yaml

💻 常用指令清单

1. 资源查看 (Observability)

用于快速了解集群状态、节点健康度和应用运行情况。

# === 基础列表 ===
# 查看所有节点（-o wide 查看 IP 等详情）
kubectl get nodes -o wide

# 查看当前命令空间下的 Pod
kubectl get pods

# 查看所有命名空间(Namespace)下的 Pod
kubectl get pods -A

# 查看其他资源类型
kubectl get svc -A        # Service
kubectl get job -A        # Job
kubectl get ingress -A    # Ingress
kubectl get deployment -A # Deployment
kubectl get statefulset -A # StatefulSet
kubectl get daemonset -A  # DaemonSet

# === 筛选查询 ===
# 使用 Label Selector 筛选
kubectl get pods -l app=nginx,env=prod
kubectl get nodes --selector=gpu=true

# 使用 Field Selector（更高效的字段过滤）
kubectl get pod -n default --field-selector=status.phase=Running,spec.nodeName=Node-01

2. 深入排查 (Debugging)

当服务出现异常时，需要查看日志、配置细节或直接进入容器排查。

# === 查看细节 ===
# 查看资源的详细配置和事件（Event），排错神器
kubectl describe <resource_type> <resource_name> -n <namespace>
# 示例：
kubectl describe pod my-pod -n default
kubectl describe node worker-01 | grep Taints

# === 导出配置 ===
# 查看资源的 YAML 定义（常用于备份或查看隐藏字段）
kubectl get pod my-pod -o yaml

# === 容器内部操作 ===
# 进入 Pod 内部（打开交互式终端）
kubectl exec -it <pod_name> -n <namespace> -- /bin/bash

# 日志查看（实时追踪）
kubectl logs -f <pod_name> -n <namespace>

# === 网络调试 ===
# 端口转发：将集群内部端口映射到本地 localhost（用于调试 Prometheus、WebUI 等）
kubectl --namespace monitoring port-forward svc/prometheus-k8s 9090:9090 --address 0.0.0.0

3. 数据传输 (Data Transfer)

在本地与 Pod 之间互相拷贝文件。

# 将本地文件拷贝到 Pod
kubectl cp /tmp/local_file <namespace>/<pod_name>:/tmp/remote_file -c <container_name>

# 将 Pod 文件拷贝到本地
kubectl cp <namespace>/<pod_name>:/tmp/remote_file /tmp/local_file -c <container_name>

4. 资源生命周期管理 (Lifecycle)

创建、删除、修改、修补资源。

# === 创建/删除 ===
# 创建命名空间
kubectl create namespace <namespace_name>

# 删除资源（Pod/Service/Deployment等）
kubectl delete pod <pod_name> -n <namespace>

# 应用/更新配置文件（最常用）
kubectl apply -f deployment.yaml

# === 修改配置 ===
# 在线编辑资源配置（使用默认编辑器打开 YAML，保存即生效）
kubectl edit svc my-service -n default

# 修改 Metallb IP 池示例
kubectl edit IPAddressPool -n metallb-system pool-0

# === 导出/导入 ConfigMap ===
kubectl get configmap my-config -n default -o yaml > config.yaml
# (修改 config.yaml 后)
kubectl apply -f config.yaml

🛠️ 高级运维操作

节点维护与调度 (Node & Taints)

当需要对物理机进行维护或进行复杂的调度隔离时使用。

# === 污点 (Taint) 管理 ===
# 给节点打污点，阻止普通 Pod 调度上来
# effect 包含: NoSchedule (不调度), PreferNoSchedule (尽量不调度), NoExecute (驱逐已有)
kubectl taint nodes node-01 key=value:NoSchedule

# 允许 Master 节点参与调度（移除 Master 的污点）
kubectl taint nodes --all node-role.kubernetes.io/control-plane-

# 移除污点
kubectl taint nodes node-01 key:NoSchedule-

# === 节点维护流程 (缩容/下线) ===
# 1. 封锁节点，设为不可调度
kubectl cordon <node_name>

# 2. 驱逐节点上的 Pod（安全排空）
# --ignore-daemonsets: 忽略守护进程集
# --delete-emptydir-data: 允许删除临时数据卷
kubectl drain <node_name> --ignore-daemonsets --delete-emptydir-data

# 3. 物理维护或下线后，删除节点记录
kubectl delete node <node_name>

# (维护结束后恢复)
kubectl uncordon <node_name>

Patch 操作 (热更新)

无需编辑完整 YAML，直接修补部分字段。

# === Patch Pod ===
# 动态添加 Label 或 Annotation
kubectl patch pod <pod-name> -n <namespace> --type merge -p '{"metadata":{"annotations":{"debug":"true"}}}'

# === Patch Node 资源容量 (Hack) ===
# 手动修改 Node 的 Status（例如模拟 GPU 资源）
# 注意：直接修改 status 需要使用 --subresource='status'
# op: replace表示修改，add表示添加，remove表示删除
kubectl patch node <node-name> --type='json' -p='[{"op": "add", "path": "/status/capacity/faceunity.com~1gpu", "value": "100"}]' --subresource='status'

Secret 与 StorageClass 实战

1. 创建 Docker Registry Secret

用于拉取私有仓库镜像。

kubectl create secret docker-registry harbor \
  --docker-server=harbor.example.com \
  --docker-username=<user> \
  --docker-password=<pwd> \
  --docker-email=<email> \
  -n <namespace>

2. 配置 S3 StorageClass (Based on MinIO)

场景：使用对象存储作为 K8s 的持久化卷。

前提：安装 k8s-csi-s3 插件 (参考: yandex-cloud/k8s-csi-s3)。
创建 Secret：存储 MinIO/S3 认证信息。

apiVersion: v1
kind: Secret
metadata:
  name: csi-s3-secret
  namespace: kube-system # 需与 StorageClass 配置一致
stringData:
  accessKeyID: xxxxxxx
  secretAccessKey: xxxxxxx
  endpoint: xxxxxxx
  # region: "" # AWS环境需指定

🔗 参考与扩展

k8s-csi-s3 GitHub 仓库