Kubernetes 基础

官方文档：https://kubernetes.io/zh-cn/docs/home/
适用版本：Kubernetes 1.29+（2026-05-07 核实）

核心概念

集群架构

Kubernetes 集群由两类节点组成：Control Plane（控制平面）和 Worker Node（工作节点）。

Control Plane 组件

Worker Node 组件

Pod、Node、Namespace 的关系

• Node 是物理或虚拟机器，是运行 Pod 的宿主机。
• Pod 是 Kubernetes 最小调度单元，运行在某个 Node 上，包含一个或多个容器，共享网络栈和存储卷。
• Namespace 是逻辑隔离单位，用于将同一集群的资源划分为不同的虚拟空间（如 dev、staging、prod）。Node 本身不属于 Namespace，Pod 和 Service 等资源属于某个 Namespace。

声明式 vs 命令式

生产环境推荐声明式，便于版本控制和 GitOps 工作流。

kubectl 常用命令

kubectl get

列出资源对象。

kubectl get <resource> [-n namespace] [-o wide|yaml|json]

kubectl get pods -n kube-system -o wide
kubectl get all -A
kubectl get pods -l app=nginx

kubectl describe

查看资源详情及事件（排查问题的首选命令）。

kubectl describe <resource> <name> [-n namespace]

kubectl describe pod my-pod -n default
kubectl describe node worker-1

kubectl apply

将 YAML/JSON 清单应用到集群（声明式更新）。

kubectl apply -f <file.yaml>

kubectl apply -f deployment.yaml
kubectl apply -f ./manifests/ -R
kubectl apply -f deployment.yaml --dry-run=client

kubectl delete

删除资源对象。

kubectl delete <resource> <name> [-n namespace]

kubectl delete pod my-pod
kubectl delete -f deployment.yaml
kubectl delete pod my-pod --grace-period=0 --force

kubectl logs

查看 Pod 中容器的日志。

kubectl logs <pod> [-c container] [-f] [--previous]

kubectl logs my-pod -c sidecar -f
kubectl logs my-pod --previous --tail=100

kubectl exec

在运行中的容器内执行命令。

kubectl exec -it <pod> [-c container] -- /bin/sh

kubectl exec -it my-pod -- /bin/bash
kubectl exec -it my-pod -c init-container -- /bin/sh

kubectl port-forward

将本地端口转发到 Pod 端口，常用于本地调试。

kubectl port-forward <pod> <local>:<remote>

kubectl port-forward my-pod 8080:80
kubectl port-forward svc/my-service 9090:9090 -n staging

kubectl scale

调整 Deployment/StatefulSet/ReplicaSet 的副本数。

kubectl scale deployment <name> --replicas=N

kubectl scale deployment my-app --replicas=3

kubectl rollout

管理 Deployment 的发布过程。

kubectl rollout status|history|undo deployment/<name>

kubectl rollout status deployment/my-app
kubectl rollout history deployment/my-app
kubectl rollout undo deployment/my-app
kubectl rollout undo deployment/my-app --to-revision=2

核心资源对象

Pod

Pod 是 Kubernetes 的最小调度单元，封装一个或多个容器。

基本 YAML 结构

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  namespace: default
  labels:
    app: my-app
spec:
  containers:
    - name: main
      image: nginx:1.25
      ports:
        - containerPort: 80
      env:
        - name: ENV_VAR
          value: "hello"
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          cpu: "500m"
          memory: "256Mi"
      volumeMounts:
        - name: config-vol
          mountPath: /etc/config
      livenessProbe:
        httpGet:
          path: /healthz
          port: 80
        initialDelaySeconds: 10
        periodSeconds: 5
      readinessProbe:
        httpGet:
          path: /ready
          port: 80
        initialDelaySeconds: 5
        periodSeconds: 3
  volumes:
    - name: config-vol
      configMap:
        name: my-config

spec.containers 核心字段

resources.requests vs resources.limits

建议始终设置 requests，在资源紧张的生产环境也应设置 limits。

多容器 Pod（Sidecar 模式）

同一 Pod 内的容器共享网络（localhost 互通）和存储卷，适合以下模式：

• Sidecar：辅助主容器，如日志收集（Fluentd）、配置同步
• Ambassador：代理主容器对外通信
• Adapter：转换主容器的输出格式

spec:
  containers:
    - name: app
      image: my-app:1.0
      volumeMounts:
        - name: log-vol
          mountPath: /var/log/app
    - name: log-collector
      image: fluentd:latest
      volumeMounts:
        - name: log-vol
          mountPath: /var/log/app
  volumes:
    - name: log-vol
      emptyDir: {}

Deployment

Deployment 管理无状态应用的副本集，提供滚动更新和回滚能力。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

spec 核心字段

滚动更新策略参数

零停机发布建议：maxSurge: 1，maxUnavailable: 0。

Service

Service 为一组 Pod 提供稳定的访问入口（虚拟 IP + DNS 名称）。

Service 类型对比

spec.selector 工作方式

Service 通过标签选择器动态发现后端 Pod。只要 Pod 带有匹配的标签且处于 Ready 状态，就会加入 Endpoints 列表。

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: my-app       # 匹配带有此标签的 Pod
  ports:
    - port: 80        # Service 暴露的端口
      targetPort: 8080  # 转发到 Pod 的端口
  type: ClusterIP

Headless Service

将 clusterIP 设为 None，不分配虚拟 IP，DNS 查询直接返回 Pod IP 列表。StatefulSet 场景下常用，客户端可以直接连接到特定 Pod。

spec:
  clusterIP: None
  selector:
    app: my-statefulset

ConfigMap 与 Secret

创建方式

# 命令行字面量
kubectl create configmap my-config --from-literal=key1=value1 --from-literal=key2=value2

# 从文件创建
kubectl create configmap my-config --from-file=config.properties

# 从目录创建（目录下每个文件成为一个键）
kubectl create configmap my-config --from-file=./configs/

# YAML 方式
kubectl apply -f configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  APP_ENV: production
  config.yaml: |
    server:
      port: 8080

Secret 创建方式相同，但内容会经 Base64 编码存储：

kubectl create secret generic my-secret \
  --from-literal=db-password=s3cr3t \
  --from-file=tls.crt=./certs/tls.crt

注入方式对比

# 环境变量注入
env:
  - name: APP_ENV
    valueFrom:
      configMapKeyRef:
        name: my-config
        key: APP_ENV
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: my-secret
        key: db-password

# 全量注入为环境变量
envFrom:
  - configMapRef:
      name: my-config

# volumeMount 注入
volumeMounts:
  - name: config-vol
    mountPath: /etc/app
volumes:
  - name: config-vol
    configMap:
      name: my-config

Health Check（健康检查）

三种探针的区别

探针类型参数

httpGet

exec

tcpSocket

探针通用配置参数

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  exec:
    command: ["redis-cli", "ping"]
  initialDelaySeconds: 5
  periodSeconds: 5

startupProbe:
  tcpSocket:
    port: 8080
  failureThreshold: 30    # 最多等待 30 * 10 = 300 秒
  periodSeconds: 10

踩坑与注意事项

Pod 一直处于 Pending 状态

排查思路：kubectl describe pod <name> 查看 Events 字段。

ImagePullBackOff 排查步骤

1. kubectl describe pod <name> 查看具体错误信息
2. 确认镜像地址和 tag 正确：docker pull <image> 在本地验证
3. 私有仓库需创建 Secret 并配置 imagePullSecrets：

   kubectl create secret docker-registry regcred \
     --docker-server=registry.example.com \
     --docker-username=user \
     --docker-password=password
   

   spec:
     imagePullSecrets:
       - name: regcred
   

4. 检查节点网络是否能访问镜像仓库

其他常见坑

• 环境变量中引用 Secret：Secret 的 value 已经是明文，不需要 Base64 解码，Kubernetes 会自动处理。
• ConfigMap 大小限制：单个 ConfigMap 数据上限为 1MB，超大配置文件建议用 Volume 挂载外部存储。
• Service 和 Pod 标签必须严格匹配：selector 中的每个标签键值对都必须出现在 Pod 的 labels 中。
• kubectl apply 与 kubectl create 的区别：create 用于首次创建，资源已存在则报错；apply 创建或更新，推荐生产使用。

最佳实践

始终设置 resources.requests 和 resources.limits：没有 requests 的 Pod 会被调度到资源不足的节点，没有 limits 的 Pod 可能耗尽节点资源导致其他 Pod 被驱逐。

resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

用 livenessProbe 和 readinessProbe 保障流量切换：livenessProbe 失败时 kubelet 重启容器，readinessProbe 失败时 Service 摘除该 Pod 的流量，两者配合实现零停机滚动更新。

命名空间隔离不同环境：用 dev/staging/prod 命名空间隔离资源，配合 RBAC 限制各命名空间的操作权限，避免误操作生产资源。

kubectl apply 优于 kubectl create：apply 是声明式更新，支持 GitOps 工作流；create 只能用于首次创建，资源已存在时报错。所有资源文件纳入 Git 版本控制。

使用 Deployment 而非直接管理 Pod：裸 Pod 在节点故障后不会自动重建，Deployment 通过 ReplicaSet 保证副本数，并提供滚动更新和回滚能力。

常见陷阱

陷阱：Pod 一直处于 Pending 状态

现象： kubectl get pods 显示 Pod 长时间 Pending，无法调度到节点。
原因： 常见原因：节点资源不足（CPU/内存）、节点 taint 与 Pod 无匹配 toleration、PVC 未绑定、nodeSelector 无匹配节点。
解决： kubectl describe pod <name> 查看 Events 字段，根据 Insufficient cpu、no nodes are available 等提示定位原因。

陷阱：ConfigMap / Secret 更新后 Pod 内不生效

现象： 更新了 ConfigMap，但 Pod 内挂载的文件仍是旧值。
原因： 以 subPath 挂载的 Volume 不会自动同步更新；环境变量注入的值在 Pod 启动时已固化。
解决： 避免 subPath；使用环境变量时需滚动重启 Pod（kubectl rollout restart deployment/<name>）使新配置生效。

陷阱：Service 无法访问 Pod

现象： Service ClusterIP 可达但请求超时，或返回 connection refused。
原因： Service 的 selector 标签与 Pod 的 labels 不匹配，导致 Endpoints 列表为空。
解决： kubectl get endpoints <service-name> 检查 Endpoints，若为空则检查 selector 与 Pod labels 是否一致（区分大小写）。

参见

Kubernetes进阶
Docker高级指南
GitHub Actions完全指南