在 Kubernetes 部署整套微服務
Deploying a Microservice System on Kubernetes
把 api-gateway、order、payment、inventory 搬進 Kubernetes:每個服務一組 Deployment 與 Service、Gateway API 對外、NetworkPolicy 限制呼叫路徑、HPA 與 PDB 撐住流量與維護,再用 Kustomize 管理 dev/prod,並把建置、遷移、發佈、回滾與除錯串成流程。
這篇的步驟
上一篇〈用 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 與 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 會被自動改寫成這個帶雜湊的名稱。這帶來兩個好處:
- 設定一改,Pod 自動滾動更新。 一般的 ConfigMap 被修改後,已經在跑的 Pod 不會重新讀取環境變數;但用了產生器,內容一變名稱就變,Deployment 的 Pod 範本也跟著變,Kubernetes 便會滾動更新。
- 回滾時設定一起回去。 舊的 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: 5GiStatefulSet 和 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: 8080NetworkPolicy:讓其他路徑都走不通。 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: 8080NetworkPolicy 是累加的:只要有任何一條規則放行,流量就能通過;沒有任何規則放行,就被第 1 條擋下。所以閱讀時要問的是「有哪些路是開的」,而不是「哪些路被關了」。kubernetes.io/metadata.name 是 Kubernetes 自動替每個命名空間加上的標籤,用它選命名空間比自己加標籤可靠。
規則 3 寫得比較寬:api-gateway 與 order 都能呼叫三個後端。若要更嚴格,可以拆成每個服務一條,例如 inventory 只接受 order 的呼叫——規則愈細,愈能把「哪個服務依賴哪個服務」寫成可執行的文件,代價是新增呼叫關係時要記得同步修改。
圖:只有 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: 300averageUtilization 是相對於 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.yamllabels 會替所有資源加上 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: restrictedoverlay 裡用到 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 放四個服務共用的資源;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-secretsJob 有一個特性決定了發佈流程的寫法: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 在叢集裡偵測變更並套用。這樣儲存庫永遠是叢集狀態的唯一來源,誰在什麼時候發佈了什麼,看提交歷史就知道。
圖:同一個 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=3rollout 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、資源不足無法多起 Pod | rollout 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 → 分散式追蹤。
下一篇
到這裡,整套訂單系統已經能在叢集裡多副本運行、自動擴縮、安全地發佈與回滾。但不是每個系統一開始就需要這些:下一篇〈從單體到微服務:十萬、百萬、千萬級的架構怎麼演進〉退一步看,同一個商店系統應該怎麼隨著規模,從一個單體一階一階長成現在的樣子,什麼時候該拆、什麼時候還不該拆。