Kubernetes 发布与滚动升级的坑：不可变字段、节拍参数与配置热更新误解

Error from server (Invalid): error when applying patch:
The Deployment `web` is invalid: spec.selector: Invalid value: {...}: field is immutable

Service `my-svc` is invalid: spec.clusterIP: Invalid value: ``: field is immutable

kubectl get deploy web -o yaml > live.yaml
# 将本地期望的清单保存为 desired.yaml
diff -u live.yaml desired.yaml | sed -n '/spec:/,$p'

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: app
          image: ghcr.io/nginxinc/nginx-unprivileged:1.27-alpine
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  selector:
    matchLabels:
      app: web-v2   # 期望修改为 web-v2，会触发不可变

kubectl apply -f bad-deploy.yaml --server-side --force-conflicts

kubectl delete deploy web --cascade=orphan
kubectl apply -f fixed-deploy.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-v2
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-v2
  template:
    metadata:
      labels:
        app: web-v2
    spec:
      containers:
        - name: app
          image: ghcr.io/nginxinc/nginx-unprivileged:1.27-alpine

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1           # 额外加 1 个副本平滑引入新版本
      maxUnavailable: 0     # 保证服务不减容
  template:
    metadata:
      labels:
        app: api
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          image: ghcr.io/nginxinc/nginx-unprivileged:1.27-alpine
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /
              port: 8080
            initialDelaySeconds: 3
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ['sh','-c','sleep 10']   # 留出 10 秒排空连接

kubectl rollout restart deploy/api
kubectl rollout status deploy/api -w
kubectl get po -l app=api -w

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-cm
data:
  app.conf: |
    message=hello

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cm-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cm-demo
  template:
    metadata:
      labels:
        app: cm-demo
    spec:
      containers:
        - name: app
          image: alpine:3.20
          command: ['sh','-c','while true; do cat /etc/app/app.conf; sleep 3; done']
          volumeMounts:
            - name: cfg
              mountPath: /etc/app/app.conf
              subPath: app.conf     # 这是坑：subPath 不会热更新
      volumes:
        - name: cfg
          configMap:
            name: app-cm

kubectl create configmap app-cm --from-literal=app.conf='message=world' -o yaml --dry-run=client | kubectl apply -f -

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cm-demo-fixed
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cm-demo-fixed
  template:
    metadata:
      labels:
        app: cm-demo-fixed
    spec:
      containers:
        - name: app
          image: alpine:3.20
          command: ['sh','-c','inotifyd - /etc/app:W | while read e; do echo reload; done']
          volumeMounts:
            - name: cfg
              mountPath: /etc/app
      volumes:
        - name: cfg
          configMap:
            name: app-cm

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include 'app.fullname' . }}
spec:
  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath '/configmap.yaml') . | sha256sum }}

helm repo add stakater https://stakater.github.io/stakater-charts
helm install reloader stakater/reloader

metadata:
  annotations:
    reloader.stakater.com/auto: 'true'

# 预览会失败的升级（Helm）
helm upgrade web ./chart --dry-run --debug | sed -n '/^---/,$p' > rendered.yaml

# 与线上资源对比
kubectl get deploy web -o yaml > live.yaml
diff -u live.yaml rendered.yaml | grep -E 'spec.selector|clusterIP'

# 在升级前抓取 clusterIP，写回到生成的 yaml 再 apply
ip=$(kubectl get svc my-svc -o jsonpath='{.spec.clusterIP}')
yq -i ".spec.clusterIP = '${ip}'" svc.yaml
kubectl apply -f svc.yaml

kubectl rollout restart deploy/api
kubectl rollout status deploy/api -w
kubectl rollout history deploy/api
kubectl rollout undo deploy/api

# 给 Pod 模板加一个时间戳注解触发滚动
kubectl patch deploy api -p \
  '{"spec":{"template":{"metadata":{"annotations":{"reload-at":"'$(date +%s)'"}}}}}'