This resume is also available in English.

六、實戰部署第 2 / 5 篇 · 全部目錄

專欄 › 六、實戰部署 › 第 22 篇

在 Kubernetes 部署整套微服務

Deploying a Microservice System on Kubernetes

把 api-gateway、order、payment、inventory 搬進 Kubernetes:每個服務一組 Deployment 與 Service、Gateway API 對外、NetworkPolicy 限制呼叫路徑、HPA 與 PDB 撐住流量與維護,再用 Kustomize 管理 dev/prod,並把建置、遷移、發佈、回滾與除錯串成流程。

  • Kubernetes
  • Kustomize
  • Microservices
  • Go
這篇的步驟
  1. 第 1 步:規劃命名空間、標籤與目錄結構
  2. 第 2 步:每個服務一個 Deployment 與 Service
  3. 第 3 步:每個服務自己的 ConfigMap 與 Secret
  4. 第 4 步:有狀態的依賴——資料庫與訊息佇列
  5. 第 5 步:對外入口與 NetworkPolicy
  6. 第 6 步:探針、資源、HPA 與 PDB
  7. 第 7 步:Kustomize 組合 base 與 dev/prod overlay
  8. 第 8 步:遷移 Job、發佈流程、滾動更新與回滾
  9. 第 9 步:出事時怎麼查
  10. 常見陷阱
  11. 重點整理
  12. 下一篇

上一篇〈用 Docker Compose 部署整套微服務〉我們用一份 compose.yaml 讓四個服務在一台主機上一起跑起來;這篇接著把同一套系統搬進 Kubernetes 叢集,補上 Compose 給不了的多主機、不停機更新、自動擴縮與細緻的存取控制。

〈Docker 與 Kubernetes 部署(單一服務)〉已經示範過把一個服務放上叢集:一個 Deployment、一個 Service、三種探針。從一個變成四個,困難的地方並不是「把 YAML 複製四份」,而是那些只有在系統層級才會出現的問題:

  • 四個服務、兩個以上的環境,設定檔怎麼組織才不會到處重複,又能看清楚每個環境差在哪裡?
  • 服務之間怎麼找到彼此?外部流量怎麼進來,又怎麼保證只能從入口進來?
  • 資料庫、訊息佇列這些有狀態的元件,該放在叢集裡還是交給託管服務?
  • 每次發佈時,資料庫遷移要在什麼時機跑?新版本有問題時怎麼退回去?
  • 出事的時候,從哪裡開始查?

這篇沿用前面整個系列的訂單系統,從目錄結構開始,一步一步組出可以實際套用到叢集的設定。範例使用的 API 版本都是目前的穩定版:apps/v1、autoscaling/v2、policy/v1、networking.k8s.io/v1,以及 Gateway API 的 gateway.networking.k8s.io/v1。設定管理用 kubectl 內建的 Kustomize。

第 1 步:規劃命名空間、標籤與目錄結構

先決定三件會影響後面所有檔案的事。

一、環境怎麼分。 常見做法有兩種:每個環境一個叢集,或同一個叢集裡每個環境一個命名空間(namespace)。正式環境與開發環境放在不同叢集,隔離最徹底,一個環境的誤操作或資源耗盡不會波及另一個;開發與測試環境共用一個叢集、各用一個命名空間,則省下許多成本。本文的範例是:正式環境的命名空間叫 shop,開發環境叫 shop-dev。如果你的開發環境在另一個叢集,也可以兩邊都叫 shop,後面的設定完全不受影響——因為服務之間的位址都寫成短名稱,這一點在第 2 步說明。

二、標籤的慣例。 Kubernetes 用標籤(label)把資源串在一起:Service 用標籤選 Pod、NetworkPolicy 用標籤決定誰能連誰、PDB 用標籤知道要保護哪些 Pod。標籤一亂,這些機制就會默默失效。範例統一使用 Kubernetes 建議的標籤:

標籤用途範例值
app.kubernetes.io/name哪一個服務,選擇器用這個order、api-gateway
app.kubernetes.io/part-of屬於哪個系統shop
app.kubernetes.io/component資源的角色migrate、config

三、目錄結構。 延續系列的儲存庫配置,Kubernetes 的設定放在 deploy/k8s/,分成 base(所有環境共用)與 overlays(每個環境的差異):

shop/                                  # 模組路徑 example.com/shop
├── cmd/{api-gateway,order,payment,inventory}/main.go
├── internal/ …
├── api/proto/ …
└── deploy/
    ├── docker/Dockerfile              # 四個服務共用(上一篇)
    ├── compose/ …                     # 上一篇的 Compose 設定
    └── k8s/
        ├── base/
        │   ├── kustomization.yaml     # 列出四個服務與共用資源
        │   ├── httproute.yaml         # 對外路由到 api-gateway
        │   ├── networkpolicy.yaml     # 誰可以連誰
        │   ├── api-gateway/
        │   │   ├── kustomization.yaml
        │   │   ├── config.env
        │   │   ├── deployment.yaml
        │   │   ├── service.yaml
        │   │   ├── hpa.yaml
        │   │   └── pdb.yaml
        │   ├── order/                 # 同上,再加 migrate-job.yaml
        │   ├── payment/               # 同 order
        │   └── inventory/             # 同 order
        └── overlays/
            ├── dev/
            │   ├── kustomization.yaml # namespace: shop-dev、機密、較少副本
            │   ├── namespace.yaml
            │   ├── data/              # 開發用的 postgres、nats、redis
            │   └── secrets/           # 不進版本控制
            └── prod/
                ├── kustomization.yaml # namespace: shop、映像檔標籤、較多資源
                ├── namespace.yaml
                └── patches/

每個服務一個子目錄、各自有自己的 kustomization.yaml,好處是「order 的一切」都在 base/order/ 裡:要新增一個服務,就是複製一個目錄、改名稱,再在上一層的清單加一行。

使用者 Gateway(gateway-system 命名空間) HTTPRoute:shop.example.com 命名空間 shop Service api-gateway Pod × 2~N(HPA) Service order Service payment Service inventory Pod × 3~20 Pod × 2~10 Pod × 2~10 彼此用 DNS 呼叫:order.shop.svc.cluster.local:9090(同命名空間可簡寫 order:9090) 託管 PostgreSQL 每個服務一個資料庫 NATS nats 命名空間(Helm) 託管 Redis 快取、限流、冪等鍵

圖:外部流量經 Gateway 與 HTTPRoute 進到 api-gateway,後端服務之間用叢集 DNS 互相呼叫;正式環境的資料庫與快取在叢集外,NATS 在自己的命名空間。

第 2 步:每個服務一個 Deployment 與 Service

先把 order 寫完整,其他三個服務照同樣的形狀寫。Deployment 描述「要跑什麼、怎麼跑」:

# deploy/k8s/base/order/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order
  labels:
    app.kubernetes.io/name: order
spec:
  # 不寫 replicas:副本數交給 HPA,否則每次 apply 都會把它蓋回去
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app.kubernetes.io/name: order
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app.kubernetes.io/name: order
    spec:
      terminationGracePeriodSeconds: 30
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: order
      containers:
        - name: app
          image: registry.example.com/shop/order:latest
          args: ['serve']
          ports:
            - name: http
              containerPort: 8080
            - name: grpc
              containerPort: 9090
          envFrom:
            - configMapRef:
                name: order-config
          env:
            - name: DB_PASSWORD_FILE
              value: /etc/shop/secrets/db-password
            - name: GOMEMLIMIT
              valueFrom:
                resourceFieldRef:
                  resource: limits.memory
          volumeMounts:
            - name: secrets
              mountPath: /etc/shop/secrets
              readOnly: true
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 256Mi
          startupProbe:
            httpGet:
              path: /livez
              port: http
            periodSeconds: 2
            failureThreshold: 30
          readinessProbe:
            httpGet:
              path: /readyz
              port: http
            periodSeconds: 5
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /livez
              port: http
            periodSeconds: 10
            failureThreshold: 3
          lifecycle:
            preStop:
              sleep:
                seconds: 5
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ['ALL']
      volumes:
        - name: secrets
          secret:
            secretName: order-secrets

這份檔案比單一服務那篇長,多出來的部分都有理由:

  • image 的標籤寫什麼不重要。 base 裡寫 latest 只是佔位,真正的標籤由 overlay 的 images 欄位改寫成 git SHA(第 7、8 步)。
  • args: ["serve"] 對應上一篇的子指令設計:同一個映像檔,serve 跑服務、migrate up 跑遷移。
  • envFrom 讀 ConfigMap、密碼用檔案掛載,搭配上一篇的 envOrFile:程式讀 DB_PASSWORD_FILE 指向的檔案。Compose 的 /run/secrets/… 與這裡的 /etc/shop/secrets/… 只差在路徑,程式碼完全不用改。
  • GOMEMLIMIT 從記憶體上限取值。 Go 執行環境預設不知道容器的記憶體上限,設定之後垃圾回收器會在接近上限前更積極地回收,降低被 OOMKilled 的機率;〈效能調校:pprof 與 benchmark〉量出來的記憶體曲線正好用來決定這個上限。
  • topologySpreadConstraints 讓同一個服務的 Pod 盡量分散到不同節點,一個節點故障不會同時帶走所有副本。
  • preStop 的 sleep 讓 Pod 在收到終止訊號前先等幾秒,給 Service 端點與負載平衡器時間把它從名單移除,避免關閉過程中還有新請求進來。distroless 映像檔裡沒有 sleep 指令,所以使用 Kubernetes 內建的 sleep 動作(較新版本的 Kubernetes 才支援,舊叢集可改由程式在收到訊號後自行延遲)。之後程式照〈設定與優雅關閉〉處理 SIGTERM,在 terminationGracePeriodSeconds 內收尾。
  • securityContext 以非 root 執行、根檔案系統唯讀、拿掉所有 Linux capabilities。Go 的靜態執行檔本來就不需要這些權限,順手收緊沒有任何成本。

Service 則替這組 Pod 提供穩定的名稱與位址:

# deploy/k8s/base/order/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: order
  labels:
    app.kubernetes.io/name: order
spec:
  selector:
    app.kubernetes.io/name: order
  ports:
    - name: http
      port: 8080
      targetPort: http
    - name: grpc
      port: 9090
      targetPort: grpc

服務之間怎麼找到彼此。 叢集 DNS 會替每個 Service 建立 <服務>.<命名空間>.svc.cluster.local 的紀錄:在命名空間 shop 裡,order 的完整名稱是 order.shop.svc.cluster.local。同一個命名空間內的 Pod 可以只寫 order,DNS 搜尋網域會自動補上後面的部分。所以 api-gateway 的設定寫 ORDER_ADDR=order:9090——和上一篇 Compose 裡的寫法一模一樣,而且不論部署在 shop 還是 shop-dev 都不用改。只有跨命名空間時才需要寫長一點的名稱,例如正式環境的 NATS 在 nats 命名空間,就寫 nats.nats.svc.cluster.local。

提示:gRPC 使用長連線的 HTTP/2。一般的 ClusterIP Service 在建立連線時做負載平衡,連線建好之後所有請求都會送到同一個 Pod,擴充副本後流量也不會自動分散。〈服務發現與負載平衡〉介紹的兩種解法在這裡都適用:另建一個 clusterIP: None 的 headless Service,讓 gRPC 客戶端用 dns:///order-headless:9090 拿到所有 Pod 位址並以 round_robin 分散;或交給服務網格(service mesh)在請求層級做負載平衡。

api-gateway、payment、inventory 的 Deployment 與 Service 結構相同,只改名稱與標籤;api-gateway 不連資料庫,所以沒有機密掛載,也只開 8080 埠。

第 3 步:每個服務自己的 ConfigMap 與 Secret

設定與機密要做到兩件事:每個服務只拿得到自己的;設定變動時 Pod 會自動換新。Kustomize 的產生器(generator)可以同時做到。

在每個服務的子目錄裡,用 configMapGenerator 從環境檔產生 ConfigMap:

# deploy/k8s/base/order/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - hpa.yaml
  - pdb.yaml
  - migrate-job.yaml
configMapGenerator:
  - name: order-config
    envs:
      - config.env
    options:
      labels:
        app.kubernetes.io/component: config
# deploy/k8s/base/order/config.env
LOG_LEVEL=info
LOG_FORMAT=json
DB_HOST=postgres
DB_NAME=order
DB_USER=order
PAYMENT_ADDR=payment:9090
INVENTORY_ADDR=inventory:9090
NATS_URL=nats://nats:4222
REDIS_ADDR=redis:6379
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.monitoring:4317

產生器做的事情有一個關鍵細節:產出的 ConfigMap 名稱會帶上內容的雜湊值,例如 order-config-t59gh52tg6,而 Deployment 裡寫的 order-config 會被自動改寫成這個帶雜湊的名稱。這帶來兩個好處:

  1. 設定一改,Pod 自動滾動更新。 一般的 ConfigMap 被修改後,已經在跑的 Pod 不會重新讀取環境變數;但用了產生器,內容一變名稱就變,Deployment 的 Pod 範本也跟著變,Kubernetes 便會滾動更新。
  2. 回滾時設定一起回去。 舊的 ReplicaSet 引用的是舊名稱的 ConfigMap,kubectl rollout undo 時程式與設定是一組的,不會發生「程式回到舊版、設定還是新的」。

options.labels 替 ConfigMap 加上 app.kubernetes.io/component: config,這是為了第 8 步的發佈流程:先只套用設定與遷移工作,再套用其他資源。

機密在不同環境用不同來源。 開發環境可以用 secretGenerator 從本機檔案產生(檔案不進版本控制):

# deploy/k8s/overlays/dev/kustomization.yaml(節錄)
secretGenerator:
  - name: order-secrets
    files:
      - db-password=secrets/order-db-password.txt
    options:
      labels:
        app.kubernetes.io/component: config

正式環境則不應該讓密碼以任何形式出現在儲存庫或 CI 的檔案系統裡。常見的做法是 External Secrets Operator 從雲端的金鑰管理服務同步出名為 order-secrets 的 Secret、Sealed Secrets 把加密後的密文放進儲存庫,或用 Secrets Store CSI Driver 直接把金鑰掛進 Pod。無論用哪一種,對 Deployment 來說都只是「有一個叫 order-secrets 的 Secret」,base 不需要知道它從哪來。

項目放哪裡範例
各環境相同的設定base 的 config.env日誌格式、服務之間的短名稱位址
各環境不同的設定overlay 合併 ConfigMap資料庫主機、快取位址
開發環境的機密overlay 的 secretGenerator本機產生的測試密碼
正式環境的機密叢集外的金鑰管理服務由 External Secrets 等工具同步

提示:Kubernetes 的 Secret 預設只是 base64 編碼,不是加密。要確認叢集有開啟 etcd 的靜態加密,並用 RBAC 限制誰能讀取 Secret;能在命名空間裡建立 Pod 的人,實際上就能讀到該命名空間所有的 Secret。

第 4 步:有狀態的依賴——資料庫與訊息佇列

微服務本身是無狀態的,可以隨時殺掉、重排、擴充;資料庫和訊息佇列不是。它們該放在哪裡,是部署整套系統時最重要的決定之一:

選項優點代價
雲端託管資料庫備份、修補、高可用、容量調整都有人負責費用、與雲端綁定
叢集內的 Operator宣告式管理、仍可做到高可用與自動備份要理解 Operator 本身、儲存要可靠
自己寫 StatefulSet完全掌控、最快能動備份、升級、故障轉移全部自己來

一個務實的組合是:正式環境的資料庫用託管服務,開發環境用叢集內一個簡單的 StatefulSet。訊息佇列則看團隊能力:NATS、RabbitMQ 這類元件有官方維護的 Helm chart 或 Operator,裝在自己的命名空間(例如 nats),四個服務透過 nats.nats.svc.cluster.local 連線。

開發環境的 PostgreSQL 可以直接重用上一篇的初始化腳本:

# deploy/k8s/overlays/dev/data/postgres.yaml
apiVersion: v1
kind: Service
metadata:
  name: postgres
spec:
  clusterIP: None
  selector:
    app.kubernetes.io/name: postgres
  ports:
    - name: postgres
      port: 5432
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: postgres
  template:
    metadata:
      labels:
        app.kubernetes.io/name: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:17-alpine
          env:
            - name: POSTGRES_USER
              value: postgres
            - name: POSTGRES_PASSWORD_FILE
              value: /run/secrets/postgres_password
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata
          ports:
            - name: postgres
              containerPort: 5432
          readinessProbe:
            exec:
              command: ['pg_isready', '-U', 'postgres', '-d', 'postgres']
            periodSeconds: 5
          resources:
            requests:
              cpu: 100m
              memory: 256Mi
            limits:
              memory: 512Mi
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
            - name: secrets
              mountPath: /run/secrets
              readOnly: true
            - name: initdb
              mountPath: /docker-entrypoint-initdb.d
              readOnly: true
      volumes:
        - name: secrets
          secret:
            secretName: postgres-secrets
        - name: initdb
          configMap:
            name: postgres-initdb
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ['ReadWriteOnce']
        resources:
          requests:
            storage: 5Gi

StatefulSet 和 Deployment 的差別在於它給每個 Pod 穩定的名稱(postgres-0)與專屬的持久卷宗:Pod 被重新排程後,會重新掛回同一份資料。搭配 headless Service(clusterIP: None),服務仍然用 postgres:5432 連線。PGDATA 指向子目錄,是因為許多儲存類別在掛載點根目錄放了 lost+found,PostgreSQL 初始化時會拒絕非空目錄。

機密掛在 /run/secrets,檔名用 order_db_password 這種底線形式,於是上一篇 Compose 用的 10-create-databases.sh 一個字都不用改,透過 configMapGenerator 放進 ConfigMap 掛到初始化目錄即可。NATS 與 Redis 在開發環境就是一個 Deployment 加一個 Service,結構與上面類似,不再重複。

到了正式環境,overlay 只要把 ConfigMap 裡的位址換成託管服務的主機名稱(第 7 步),四個服務的程式與 base 都不用動。這正是把「位址」放進設定、而不是寫死在程式裡的回報。

提示:什麼時候該用 Helm?當你要安裝的是別人維護的元件(NATS、PostgreSQL Operator、監控套件、Gateway 控制器),Helm chart 是最省事的方式,它把多年累積的設定選項都包好了。你自己的四個服務結構單純、差異集中在少數欄位,用 Kustomize 直接看得到最終的 YAML,除錯更直觀。兩者也可以並用:第三方元件用 Helm 裝,自己的服務用 Kustomize 管。若要把整套系統打包給其他團隊或客戶安裝,需要大量參數化時,才是把自己的服務也做成 Helm chart 的時機。

第 5 步:對外入口與 NetworkPolicy

在 Compose 裡,「只有 gateway 對外」靠的是只發佈一個埠、後端放在 internal 網路。在 Kubernetes 裡,這件事分成兩半:讓外部流量能進到 api-gateway,以及讓其他路徑都走不通。

對外路由。 傳統做法是 Ingress(networking.k8s.io/v1),新的標準是 Gateway API。Gateway API 把職責拆開:平台管理者負責 Gateway(監聽哪些埠、用哪張憑證),應用團隊只寫 HTTPRoute(哪個主機名稱、哪些路徑送到哪個 Service)。Kubernetes 社群在 2025 年底宣布 ingress-nginx 專案退役,新系統直接從 Gateway API 開始是比較穩當的選擇:

# deploy/k8s/base/httproute.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
spec:
  parentRefs:
    - name: public
      namespace: gateway-system
  hostnames:
    - shop.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: api-gateway
          port: 8080

這裡假設平台已經在 gateway-system 命名空間建立名為 public 的 Gateway,並允許其他命名空間掛上路由。注意路由只指向 api-gateway 一個 Service:路由、認證、限流這些事都在〈API Gateway:路由、認證、限流〉那篇的程式裡做,叢集的入口只負責 TLS 與把流量交進來。

如果你的叢集用的是 Ingress 控制器,等價的寫法是:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
spec:
  ingressClassName: example-ingress-class # 換成叢集裡實際的 IngressClass
  tls:
    - hosts:
        - shop.example.com
      secretName: shop-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-gateway
                port:
                  number: 8080

NetworkPolicy:讓其他路徑都走不通。 Kubernetes 預設是「所有 Pod 都可以連所有 Pod」。即使 order 的 Service 沒有對外,叢集裡任何一個 Pod(包括別的團隊的、或被入侵的)都能直接打 order:9090,繞過 api-gateway 的認證。NetworkPolicy 用「先全部拒絕、再逐條放行」的方式修正這件事:

# deploy/k8s/base/networkpolicy.yaml
# 1. 預設拒絕:命名空間內所有 Pod 都不接受任何進來的連線
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-ingress
spec:
  podSelector: {}
  policyTypes: ['Ingress']
---
# 2. api-gateway 只接受來自 Gateway 控制器命名空間的流量
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-gateway-from-edge
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: api-gateway
  policyTypes: ['Ingress']
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: gateway-system
      ports:
        - port: 8080
---
# 3. 後端服務只接受 api-gateway 與 order(Saga 協調者)的 gRPC 呼叫
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: backend-from-callers
spec:
  podSelector:
    matchExpressions:
      - key: app.kubernetes.io/name
        operator: In
        values: ['order', 'payment', 'inventory']
  policyTypes: ['Ingress']
  ingress:
    - from:
        - podSelector:
            matchExpressions:
              - key: app.kubernetes.io/name
                operator: In
                values: ['api-gateway', 'order']
      ports:
        - port: 9090
---
# 4. 監控系統可以抓所有服務的 /metrics
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: metrics-from-monitoring
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/part-of: shop
  policyTypes: ['Ingress']
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: monitoring
      ports:
        - port: 8080

NetworkPolicy 是累加的:只要有任何一條規則放行,流量就能通過;沒有任何規則放行,就被第 1 條擋下。所以閱讀時要問的是「有哪些路是開的」,而不是「哪些路被關了」。kubernetes.io/metadata.name 是 Kubernetes 自動替每個命名空間加上的標籤,用它選命名空間比自己加標籤可靠。

規則 3 寫得比較寬:api-gateway 與 order 都能呼叫三個後端。若要更嚴格,可以拆成每個服務一條,例如 inventory 只接受 order 的呼叫——規則愈細,愈能把「哪個服務依賴哪個服務」寫成可執行的文件,代價是新增呼叫關係時要記得同步修改。

gateway-system monitoring 命名空間 shop(default-deny-ingress) 允許 :8080 api-gateway 所有 Pod 的 :8080/metrics 允許 :9090(也可直連 payment、inventory) order payment inventory order 協調 Saga:可呼叫 payment、inventory 其他 Pod 直接連後端 → 被拒絕(沒有任何規則放行)

圖:只有 Gateway 能連 api-gateway,只有 api-gateway 與 order 能連後端的 gRPC 埠,監控只能抓 8080 的指標;其他連線全部被預設規則擋下。

開發環境把 PostgreSQL、NATS、Redis 放在同一個命名空間,它們也會被預設拒絕擋住,所以 dev overlay 另外放行「同命名空間的 Pod 可以連資料元件」。正式環境的資料庫在叢集外,若要限制出站流量,就要再寫 Egress 類型的規則,並記得放行 DNS(kube-system 的 53 埠,UDP 與 TCP),否則所有服務連名稱都解析不了。

提示:NetworkPolicy 需要叢集的網路外掛(CNI)支援才會生效。有些網路外掛會接受你建立 NetworkPolicy 物件,卻完全不執行它。部署後務必實測:從一個臨時 Pod 嘗試連 order:9090,應該要連不上。

第 6 步:探針、資源、HPA 與 PDB

服務要在叢集裡「撐得住」,需要四樣東西各司其職:

機制回答的問題設定錯誤的後果
startupProbe程式啟動完了沒?太短:慢啟動的服務被不斷重啟
readinessProbe現在可以接流量嗎?檢查太多依賴:一個依賴故障讓全部服務下線
livenessProbe程式是不是卡死了,需要重啟?檢查外部依賴:資料庫一抖,所有 Pod 一起重啟
resources需要多少資源、最多能用多少?沒有 requests:排程失準、HPA 無法計算
HPA流量變大時要幾個副本?和 Deployment 的 replicas 互相覆蓋
PDB維護節點時最多能同時少幾個?設太嚴:節點永遠無法清空

探針已經寫在第 2 步的 Deployment 裡。重點在於語意:/livez 只回答「程式本身還活著」,不檢查資料庫;/readyz 回答「我能處理請求」,可以檢查自己的連線池是否就緒。資料庫短暫斷線時,readiness 失敗讓 Pod 暫時退出負載平衡,等連線恢復再回來;如果 liveness 也檢查資料庫,Kubernetes 就會把所有 Pod 一起重啟,讓小問題變成全面中斷。

資源設定方面,CPU 只設 requests、不設 limits,是 Go 服務常見的選擇:CPU limit 會造成節流(throttling),讓延遲在負載高時突然惡化;記憶體則一定要設 limit,並用前面的 GOMEMLIMIT 讓 Go 執行環境知道這條線在哪裡。

HPA 依 CPU 使用率調整副本數:

# deploy/k8s/base/order/hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: order
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: order
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300

averageUtilization 是相對於 requests 計算的,所以沒有設 CPU requests 的 Pod,HPA 根本無法運作。scaleDown.stabilizationWindowSeconds 讓縮減副本前先觀察一段時間,避免流量一波一波時副本數上上下下。每個服務的 HPA 獨立設定:api-gateway 處理每個請求,order 協調 Saga,兩者的負載形狀不同,副本範圍也應該分開調。若 CPU 不是好指標(例如 inventory 主要在等資料庫),可以改用自訂指標,例如每秒請求數或佇列長度,這需要安裝指標轉接器。

PDB 則保護「自願性中斷」——節點維護、叢集升級時的驅逐:

# deploy/k8s/base/order/pdb.yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: order
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: order

用 maxUnavailable: 1 而不是 minAvailable,是因為它在任何副本數下都合理:十個副本時一次只驅逐一個,開發環境只有一個副本時也仍然允許驅逐,不會卡住節點維護。如果寫成 minAvailable: 1,只有一個副本的環境就會讓 kubectl drain 永遠等下去。

滾動更新的節奏由 Deployment 的 strategy 決定。maxUnavailable: 0 加上 maxSurge: 25%,意思是:先多起新的 Pod,等它通過 readiness,才關掉一個舊的。整個過程中可以服務的副本數不會低於原本的數量,代價是更新期間需要多一點資源。

第 7 步:Kustomize 組合 base 與 dev/prod overlay

前面寫的檔案都在 base,現在用 overlay 組出兩個環境。base 的入口列出四個服務與共用資源:

# deploy/k8s/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
labels:
  - pairs:
      app.kubernetes.io/part-of: shop
resources:
  - api-gateway
  - order
  - payment
  - inventory
  - httproute.yaml
  - networkpolicy.yaml

labels 會替所有資源加上 app.kubernetes.io/part-of: shop。這裡用 labels 而不是舊的 commonLabels,因為後者也會改寫 Deployment 的 selector,而 selector 建立後就不能修改——日後想調整標籤時,舊寫法會讓套用直接失敗。

開發環境的 overlay:

# deploy/k8s/overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: shop-dev
resources:
  - namespace.yaml
  - ../../base
  - data/postgres.yaml
  - data/nats.yaml
  - data/redis.yaml
  - data/networkpolicy.yaml
configMapGenerator:
  - name: postgres-initdb
    files:
      - data/10-create-databases.sh
secretGenerator:
  - name: order-secrets
    files:
      - db-password=secrets/order-db-password.txt
    options:
      labels:
        app.kubernetes.io/component: config
  # payment-secrets、inventory-secrets 同上
  - name: postgres-secrets
    files:
      - postgres_password=secrets/postgres-password.txt
      - order_db_password=secrets/order-db-password.txt
      - payment_db_password=secrets/payment-db-password.txt
      - inventory_db_password=secrets/inventory-db-password.txt
patches:
  - target:
      kind: HorizontalPodAutoscaler
    patch: |-
      - op: replace
        path: /spec/minReplicas
        value: 1
      - op: replace
        path: /spec/maxReplicas
        value: 2
  - target:
      kind: HTTPRoute
      name: shop
    patch: |-
      - op: replace
        path: /spec/hostnames/0
        value: dev.shop.example.com
images:
  - name: registry.example.com/shop/api-gateway
    newTag: dev
  - name: registry.example.com/shop/order
    newTag: dev
  - name: registry.example.com/shop/payment
    newTag: dev
  - name: registry.example.com/shop/inventory
    newTag: dev

正式環境的 overlay:

# deploy/k8s/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: shop
resources:
  - namespace.yaml
  - ../../base
configMapGenerator:
  - name: order-config
    behavior: merge
    literals:
      - DB_HOST=order-db.prod.example.internal
      - NATS_URL=nats://nats.nats.svc.cluster.local:4222
      - REDIS_ADDR=shop-cache.prod.example.internal:6379
  # payment-config、inventory-config、api-gateway-config 同樣合併各自的位址
patches:
  - path: patches/order-resources.yaml
  - target:
      kind: HorizontalPodAutoscaler
      name: order
    patch: |-
      - op: replace
        path: /spec/minReplicas
        value: 3
      - op: replace
        path: /spec/maxReplicas
        value: 20
images:
  - name: registry.example.com/shop/api-gateway
    newTag: 3f2c1a9e4b7d
  - name: registry.example.com/shop/order
    newTag: 3f2c1a9e4b7d
  - name: registry.example.com/shop/payment
    newTag: 3f2c1a9e4b7d
  - name: registry.example.com/shop/inventory
    newTag: 3f2c1a9e4b7d
# deploy/k8s/overlays/prod/patches/order-resources.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order
spec:
  template:
    spec:
      containers:
        - name: app
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              memory: 1Gi
# deploy/k8s/overlays/prod/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: shop
  labels:
    pod-security.kubernetes.io/enforce: restricted

overlay 裡用到 Kustomize 的幾種修改方式,各有適合的情境:

方式適合範例
namespace整個環境換命名空間shop-dev、shop
images只換映像檔標籤git SHA
configMapGenerator + merge覆蓋部分設定值正式環境的資料庫主機
策略性合併 patch(檔案)改一段結構,例如資源order-resources.yaml
JSON 6902 patch(op: replace)精準改某個欄位,或一次套用到同類資源所有 HPA 的最小副本數

正式環境的命名空間標上 pod-security.kubernetes.io/enforce: restricted,讓 Pod Security Admission 拒絕任何以 root 執行、要求額外權限的 Pod。第 2 步的 securityContext 正是為了通過這個等級而寫的;遷移 Job 也要有同樣的設定,否則會在正式環境被擋下。

在套用之前,永遠先看產出的結果:

# 產出完整 YAML,不需要連線到叢集
kubectl kustomize deploy/k8s/overlays/prod > /tmp/shop-prod.yaml

# 和叢集上目前的狀態比較差異
kubectl diff -k deploy/k8s/overlays/prod

# 用伺服器端的驗證試跑,不真正寫入
kubectl apply -k deploy/k8s/overlays/prod --dry-run=server
base 4 × Deployment、Service HPA、PDB、遷移 Job ConfigMap、HTTPRoute NetworkPolicy overlays/dev namespace: shop-dev 叢集內的 postgres、nats、redis secretGenerator 產生機密 HPA 1~2、標籤 dev overlays/prod namespace: shop 合併 ConfigMap 指向託管資料庫 機密由外部同步,不進版控 較大資源、標籤 = git SHA

圖:base 放四個服務共用的資源;dev 與 prod 只描述自己的命名空間、資料元件、機密來源、副本數與映像檔標籤。

第 8 步:遷移 Job、發佈流程、滾動更新與回滾

遷移當作 Job。 和上一篇的一次性服務同一個概念,用同一個映像檔、換一個指令:

# deploy/k8s/base/order/migrate-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: order-migrate
  labels:
    app.kubernetes.io/name: order-migrate
    app.kubernetes.io/component: migrate
spec:
  backoffLimit: 2
  activeDeadlineSeconds: 600
  template:
    metadata:
      labels:
        app.kubernetes.io/name: order-migrate
        app.kubernetes.io/component: migrate
    spec:
      restartPolicy: Never
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: migrate
          image: registry.example.com/shop/order:latest
          args: ['migrate', 'up']
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop: ['ALL']
          envFrom:
            - configMapRef:
                name: order-config
          env:
            - name: DB_PASSWORD_FILE
              value: /etc/shop/secrets/db-password
          volumeMounts:
            - name: secrets
              mountPath: /etc/shop/secrets
              readOnly: true
      volumes:
        - name: secrets
          secret:
            secretName: order-secrets

Job 有一個特性決定了發佈流程的寫法:Job 的 Pod 範本建立後不能修改。下一次發佈時映像檔標籤變了,直接 apply 會失敗。所以流程要先刪掉上一次的遷移 Job,再建立新的。另一個要求是遷移必須在新版本的 Pod 上線之前完成,而且結構變更要向後相容(先加欄位、程式改完、之後再刪舊欄位),因為滾動更新期間新舊版本會同時存在。

發佈流程。 把建置、推送、改標籤、遷移、套用、等待串成一個腳本,CI 在合併到主幹後執行:

#!/usr/bin/env bash
# 發佈流程大綱:在儲存庫根目錄執行
set -euo pipefail

SHA="$(git rev-parse --short=12 HEAD)"
REG="registry.example.com/shop"
NS="shop"
OVERLAY="deploy/k8s/overlays/prod"
SERVICES=(api-gateway order payment inventory)

# 1. 建置並推送映像檔,標籤是 git SHA(不可變、可追溯)
for svc in "${SERVICES[@]}"; do
  docker buildx build \
    --build-arg SERVICE="$svc" \
    -f deploy/docker/Dockerfile \
    -t "$REG/$svc:$SHA" \
    --push .
done

# 2. 把 overlay 的映像檔標籤改成這次的 SHA(需要獨立安裝的 kustomize)
(
  cd "$OVERLAY"
  for svc in "${SERVICES[@]}"; do
    kustomize edit set image "$REG/$svc=$REG/$svc:$SHA"
  done
)

# 3. 先跑資料庫遷移:刪掉上一次的 Job,只套用設定與遷移工作
kubectl -n "$NS" delete job -l app.kubernetes.io/component=migrate --ignore-not-found --wait
kubectl apply -k "$OVERLAY" -l 'app.kubernetes.io/component in (config,migrate)'
kubectl -n "$NS" wait --for=condition=complete job -l app.kubernetes.io/component=migrate --timeout=10m

# 4. 套用全部資源,等每個服務滾動更新完成
kubectl apply -k "$OVERLAY"
for svc in "${SERVICES[@]}"; do
  kubectl -n "$NS" rollout status "deployment/$svc" --timeout=5m
done

幾個設計重點:

  • 標籤用 git SHA,不用 latest。 latest 不會觸發滾動更新(Pod 範本沒變),而且無從得知叢集上跑的是哪一版。SHA 讓「哪一次提交、哪個映像檔、哪次 rollout」三者一一對應。
  • 四個服務用同一個 SHA。 在單一儲存庫裡,這讓整個系統的版本有一個名字;就算某個服務的程式碼沒變,重新建置的映像檔也會因為快取而幾乎不花時間。如果服務很多、想只發佈有變動的服務,可以比對變更的路徑,但要小心共用的 internal/ 套件。
  • apply -l 先只套用設定與遷移。 遷移 Job 需要新的 ConfigMap(名稱帶雜湊)與 Secret,所以第 3 節用標籤選擇器挑出 config 與 migrate 兩類資源先套用。遷移失敗時 kubectl wait 會逾時,腳本因 set -e 中止,Deployment 完全沒動,舊版本繼續服務。
  • kubectl wait 只等「成功」。 遷移失敗時要等到逾時才會中止;想更快失敗,可以在腳本中另外輪詢 Job 的 Failed 狀態。
  • 修改後的 overlay 要提交回儲存庫,或改用 GitOps:CI 只負責建置映像檔並開一個「把標籤改成新 SHA」的提交,由 Argo CD 或 Flux 在叢集裡偵測變更並套用。這樣儲存庫永遠是叢集狀態的唯一來源,誰在什麼時候發佈了什麼,看提交歷史就知道。
1 git push 合併到主幹 2 建置映像檔 4 個服務 3 推送 標籤 = git SHA 4 設定標籤 kustomize edit 5 遷移 Job 等待 complete 6 apply -k overlays/prod 7 rollout status 滾動更新完成 失敗:回滾 還原上一個 SHA 同一個 SHA 從建置一路帶到叢集:映像檔、overlay、rollout 歷史都對得上 遷移失敗時停在第 5 步,舊版本繼續服務

圖:同一個 git SHA 從建置帶到叢集;遷移成功後才套用新版本,任何一步失敗都停下來,舊版本繼續服務。

滾動更新與回滾。 rollout status 會一直等到新的 ReplicaSet 全部就緒,或超過 progressDeadlineSeconds(預設 600 秒)被標記為失敗。新版本有問題時,有兩種退回方式:

# 看某個服務的發佈歷史
kubectl -n shop rollout history deployment/order

# 緊急退回上一版(只影響這個 Deployment)
kubectl -n shop rollout undo deployment/order

# 退回指定的版本
kubectl -n shop rollout undo deployment/order --to-revision=3

rollout undo 很快,適合緊急止血;因為 ConfigMap 名稱帶雜湊,舊版本的設定也一起回來。但它讓叢集的狀態和儲存庫不一致:下一次有人執行發佈流程,壞掉的版本又會被套用回去。所以止血之後,正式的做法是在儲存庫裡回退那次提交(或把 overlay 的標籤改回上一個 SHA),再走一次完整的發佈流程。資料庫遷移通常不回滾:向後相容的結構變更讓舊版程式也能在新結構上運作,這比寫「降版遷移」安全得多。

第 9 步:出事時怎麼查

整套系統部署上去之後,最常遇到的問題可以用一組固定的指令由外而內排查:

# 整體概況:哪些 Pod 不正常、重啟了幾次
kubectl -n shop get pods -o wide
kubectl -n shop get deploy,svc,hpa,pdb

# 某個 Pod 為什麼起不來:看最下面的 Events
kubectl -n shop describe pod order-7c9d8f6b5-x2k4q

# 命名空間最近發生的事件,依時間排序
kubectl -n shop get events --sort-by=.lastTimestamp

# 日誌:所有 order Pod、上一次崩潰前的日誌
kubectl -n shop logs -l app.kubernetes.io/name=order --tail=100 --prefix
kubectl -n shop logs order-7c9d8f6b5-x2k4q --previous

# Service 有沒有選到 Pod:端點是空的就是選擇器或 readiness 的問題
kubectl -n shop get endpointslices -l kubernetes.io/service-name=order

# 繞過入口,直接從本機連到某個服務
kubectl -n shop port-forward svc/order 9090:9090

# distroless 沒有 shell:掛一個除錯容器進去,共用程序命名空間
kubectl -n shop debug -it order-7c9d8f6b5-x2k4q --image=busybox:1.37 --target=app

# 滾動更新卡住時
kubectl -n shop rollout status deployment/order
kubectl -n shop describe deployment order

常見的症狀與方向:

症狀常見原因先看哪裡
ImagePullBackOff標籤不存在、倉庫認證失敗describe pod 的 Events
CrashLoopBackOff設定缺漏、連不上資料庫、程式啟動就崩潰logs --previous
CreateContainerConfigError引用的 ConfigMap 或 Secret 不存在describe pod、get secret
Pending資源不足、PVC 綁不到、親和性條件無法滿足describe pod、get events
Running 但不接流量readiness 一直失敗describe pod 的探針訊息、/readyz
Service 打不通選擇器與 Pod 標籤不符、埠名寫錯、NetworkPolicy 擋住get endpointslices、NetworkPolicy
OOMKilled記憶體上限太低、沒設 GOMEMLIMIT、真的有洩漏describe pod 的 Last State、pprof
滾動更新卡住新 Pod 一直不 ready、資源不足無法多起 Podrollout status、describe deploy

除錯的順序大致是:Pod 有沒有起來(get、describe)→ 程式說了什麼(logs)→ 網路通不通(endpointslices、port-forward、NetworkPolicy)→ 請求在哪裡變慢或失敗(〈可觀測性:日誌、指標、追蹤〉的追蹤)。前三步用 kubectl 就能完成,第四步才需要觀測工具。port-forward 特別好用:它讓你從本機直接連到某個服務,跳過 Gateway、api-gateway 與 NetworkPolicy,一次就能判斷問題是在服務本身還是在路徑上。

常見陷阱

  • Deployment 寫了 replicas 又配了 HPA。 每次 apply 都會把副本數重設成檔案裡的值,HPA 剛擴出來的副本瞬間被砍掉。有 HPA 的 Deployment 不要寫 replicas。
  • 用 latest 標籤。 Pod 範本沒變就不會滾動更新,也無法知道叢集上是哪一版;回滾時更是無從下手。一律用 git SHA。
  • liveness 探針檢查資料庫。 資料庫一抖動,所有服務一起被重啟。liveness 只檢查程式本身。
  • 沒設 CPU requests。 HPA 以 requests 為基準計算使用率,沒有 requests 就無法擴縮,排程器也不知道該把 Pod 放在哪裡。
  • PDB 用 minAvailable 搭配單一副本。 節點永遠無法清空,叢集升級卡住。用 maxUnavailable: 1。
  • 以為建了 NetworkPolicy 就安全。 網路外掛不支援時物件存在卻沒有效果;限制出站時忘了放行 DNS,所有服務都解析不了名稱。部署後要實測。
  • ClusterIP 上跑 gRPC 卻以為流量會平均。 長連線讓請求黏在少數 Pod 上,擴充副本也沒用。改用 headless Service 加客戶端負載平衡,或服務網格。
  • 直接修改遷移 Job 再 apply。 Job 的 Pod 範本不可修改,必須先刪除再建立;而且要在新版本上線前完成。
  • 用 commonLabels 加共用標籤。 它會改寫 selector,日後想改標籤時 Deployment 無法更新。用 labels 並保持 includeSelectors 為預設的 false。
  • 把正式環境的密碼放進 secretGenerator 檔案。 那些檔案會出現在 CI 的工作目錄、甚至被誤提交。正式環境的機密交給外部金鑰管理服務。
  • rollout undo 之後就收工。 叢集與儲存庫不一致,下一次發佈會把壞版本帶回來。止血後要在儲存庫裡回退。
  • 忘了 Pod Security 等級。 正式命名空間是 restricted,Job 或附屬容器少寫 securityContext 就會被拒絕建立,而且錯誤出現在 ReplicaSet 或 Job 的事件裡,不在 apply 的輸出。

重點整理

  • 每個環境一個命名空間(或一個叢集):正式 shop、開發 shop-dev;服務之間用短名稱 order:9090,完整名稱是 order.shop.svc.cluster.local。
  • 每個服務一組 Deployment、Service、HPA、PDB 與 ConfigMap,放在 deploy/k8s/base/<服務>/,統一用 app.kubernetes.io/* 標籤。
  • Deployment 要有三種探針、CPU requests、記憶體 limit、GOMEMLIMIT、preStop 延遲、非 root 的 securityContext。
  • configMapGenerator 的雜湊名稱讓設定變動觸發滾動更新、回滾時設定一起回去;正式環境的機密由外部金鑰管理服務提供。
  • 正式環境的資料庫用託管服務,第三方元件(NATS、Operator、監控)用 Helm 安裝,自己的服務用 Kustomize 管理。
  • 對外只有一條路:Gateway API 的 HTTPRoute(或 Ingress)指向 api-gateway;NetworkPolicy 預設拒絕,再逐條放行 Gateway → api-gateway → 後端。
  • Kustomize:base 放共用資源,overlay 用 namespace、images、ConfigMap 合併與 patch 描述環境差異;套用前用 kubectl kustomize 與 kubectl diff 確認。
  • 發佈流程:建置映像檔 → 以 git SHA 標記並推送 → kustomize edit set image → 刪舊 Job、套用設定與遷移、等待完成 → apply -k → rollout status。
  • 回滾:rollout undo 緊急止血,之後在儲存庫回退;資料庫結構變更保持向後相容,不靠降版遷移。
  • 除錯由外而內:get/describe → logs(含 --previous)→ endpointslices/port-forward/NetworkPolicy → 分散式追蹤。

下一篇

到這裡,整套訂單系統已經能在叢集裡多副本運行、自動擴縮、安全地發佈與回滾。但不是每個系統一開始就需要這些:下一篇〈從單體到微服務:十萬、百萬、千萬級的架構怎麼演進〉退一步看,同一個商店系統應該怎麼隨著規模,從一個單體一階一階長成現在的樣子,什麼時候該拆、什麼時候還不該拆。