Kubernetes Deployment 設定詳解：YAML 範例與最佳實踐

當你開始使用 Kubernetes 部署應用程式時，Deployment YAML 是你必須掌握的核心設定檔。如果你已經閱讀過 Kubernetes Deploy 完整教學，對 K8s 有了基本認識，現在是時候深入了解每個 YAML 欄位的意義與最佳配置方式。

這篇文章將帶你逐一拆解 Deployment YAML 的每個區塊，從 replicas、strategy 到 Health Checks，提供可直接複製使用的範例程式碼，讓你能夠根據實際需求打造最佳的部署設定。

Deployment YAML 結構總覽

插圖：Kubernetes Deployment YAML 結構圖

場景描述：
Technical illustration showing Kubernetes Deployment YAML 結構圖. Clean, professional diagram style.

視覺重點：
- Clear presentation of the concept
- Professional technical diagram style
- Easy to understand visual elements

必須出現的元素：
- Relevant technical components
- Clear labels and annotations
- Logical flow or structure

需要顯示的中文字：
無

風格：
Clean flat design, technical illustration, modern infographic style

顏色調性：
Professional blues and grays, with accent colors for emphasis

避免元素：
Cluttered design, realistic photos, complex 3D rendering

一個完整的 Kubernetes Deployment YAML 檔案由四個主要區塊組成，每個區塊都有其特定的功能與設定項目。

apiVersion 與 kind

apiVersion: apps/v1
kind: Deployment

這兩行是所有 K8s 資源檔案的開頭，用來告訴 Kubernetes 這是什麼類型的資源。

對於 Deployment，apiVersion 必須使用 apps/v1。如果你看到舊教學使用 extensions/v1beta1，那是已經棄用的版本，請務必更新。

metadata 區塊

metadata:
  name: my-app
  namespace: production
  labels:
    app: my-app
    environment: production
    version: v1.2.0
  annotations:
    description: "主要應用程式 Deployment"
    maintainer: "[email protected]"

metadata 區塊定義這個 Deployment 的識別資訊。

最佳實踐：至少加上 app、environment、version 三個 labels，方便後續管理與查詢。

spec 區塊

spec 區塊是 Deployment 的核心，包含了副本數、部署策略、Pod 模板等所有設定。結構如下：

spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-app:1.2.0
          # ...更多 container 設定

特別注意 selector.matchLabels 必須與 template.metadata.labels 一致，否則 Deployment 會無法找到它管理的 Pod。

如果你對整體 程式部署 流程還不熟悉，建議先閱讀完整指南建立概念。

replicas 與擴展設定

插圖：手動擴展 vs HPA 自動擴展比較圖

場景描述：
Technical illustration showing 手動擴展 vs HPA 自動擴展比較圖. Clean, professional diagram style.

視覺重點：
- Clear presentation of the concept
- Professional technical diagram style
- Easy to understand visual elements

必須出現的元素：
- Relevant technical components
- Clear labels and annotations
- Logical flow or structure

需要顯示的中文字：
無

風格：
Clean flat design, technical illustration, modern infographic style

顏色調性：
Professional blues and grays, with accent colors for emphasis

避免元素：
Cluttered design, realistic photos, complex 3D rendering

replicas 決定了你的應用程式要運行幾個副本。這是影響可用性與成本的關鍵設定。

設定副本數量

spec:
  replicas: 3

這個簡單的設定會告訴 Kubernetes 維持 3 個 Pod 副本。當某個 Pod 故障時，K8s 會自動建立新的 Pod 來補足。

副本數量的建議：

生產環境至少設定 3 個副本，這樣即使一個 Pod 故障、一個正在更新，仍有一個副本可以處理請求。

手動擴展 vs 自動擴展（HPA）

除了在 YAML 中寫死 replicas 數量，你也可以使用 kubectl 手動調整：

# 將副本數調整為 5
kubectl scale deployment my-app --replicas=5

# 確認調整結果
kubectl get deployment my-app

但更推薦的做法是使用 HPA（Horizontal Pod Autoscaler）自動擴展：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

這個 HPA 設定會：
- 最少維持 2 個副本
- 最多擴展到 10 個副本
- 當平均 CPU 使用率超過 70% 時自動擴展

💡 不確定 replicas 該設多少？

副本數量與資源配置需要根據實際流量與預算來評估。

預約免費諮詢，讓我們的工程師幫你評估最佳配置。

strategy 部署策略

插圖：RollingUpdate 與 Recreate 策略比較圖

場景描述：
Technical illustration showing RollingUpdate 與 Recreate 策略比較圖. Clean, professional diagram style.

視覺重點：
- Clear presentation of the concept
- Professional technical diagram style
- Easy to understand visual elements

必須出現的元素：
- Relevant technical components
- Clear labels and annotations
- Logical flow or structure

需要顯示的中文字：
無

風格：
Clean flat design, technical illustration, modern infographic style

顏色調性：
Professional blues and grays, with accent colors for emphasis

避免元素：
Cluttered design, realistic photos, complex 3D rendering

部署策略決定了更新 Deployment 時，舊 Pod 與新 Pod 的替換方式。選擇正確的策略可以避免服務中斷。

RollingUpdate 滾動更新

RollingUpdate 是 Kubernetes 的預設策略，也是大多數情況下的最佳選擇。它會逐步用新版 Pod 取代舊版 Pod，確保服務不中斷。

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%

優點：
- 零停機更新（Zero Downtime Deployment）
- 可以隨時暫停、恢復或回滾
- 流量會平滑地轉移到新版本

適用場景：
- 一般的版本更新
- 需要保持服務可用的生產環境
- 無狀態應用程式

Recreate 重建部署

Recreate 策略會先刪除所有舊版 Pod，再建立新版 Pod。這意味著會有一段服務中斷時間。

spec:
  strategy:
    type: Recreate

優點：
- 確保新舊版本不會同時運行
- 避免版本不一致的問題

適用場景：
- 資料庫 Schema 變更（新舊版本無法並存）
- 有狀態應用程式（StatefulSet 可能更適合）
- 開發環境快速更新

maxSurge 與 maxUnavailable

這兩個參數是 RollingUpdate 策略的核心設定，控制更新過程中的 Pod 數量：

假設 replicas: 4，以下是不同設定的效果：

# 保守策略：永遠有足夠的 Pod 處理請求
maxSurge: 1
maxUnavailable: 0
# 更新過程：4 → 5 → 5 → 5 → 4（最少維持 4 個）

# 平衡策略：兼顧速度與可用性（預設）
maxSurge: 25%
maxUnavailable: 25%
# 更新過程：4 → 4 → 4 → 4（維持 3~5 個）

# 積極策略：最快速度完成更新
maxSurge: 100%
maxUnavailable: 50%
# 更新過程：4 → 8 → 4（可能短暫只有 2 個）

建議：生產環境使用 maxUnavailable: 0 搭配 maxSurge: 25%，確保更新過程中服務不受影響。

container 設定詳解

container 設定定義了 Pod 內運行的容器，這是應用程式實際執行的地方。

image 與 imagePullPolicy

containers:
  - name: my-app
    image: my-registry.com/my-app:1.2.0
    imagePullPolicy: IfNotPresent

最佳實踐：
- 永遠使用明確的版本 tag（如 v1.2.0），避免使用 latest
- 生產環境使用 IfNotPresent，節省拉取時間
- 使用私有 Registry 時，需配置 imagePullSecrets

spec:
  imagePullSecrets:
    - name: my-registry-secret

ports 設定

containers:
  - name: my-app
    ports:
      - containerPort: 8080
        name: http
        protocol: TCP
      - containerPort: 9090
        name: metrics
        protocol: TCP

這裡設定的 ports 是「宣告」用途，讓其他人知道這個容器監聽哪些 port。實際的對外暴露需要透過 Service 設定。

env 環境變數

環境變數有三種設定方式：

containers:
  - name: my-app
    env:
      # 方式一：直接設定值
      - name: NODE_ENV
        value: "production"

      # 方式二：從 ConfigMap 取得
      - name: DATABASE_HOST
        valueFrom:
          configMapKeyRef:
            name: app-config
            key: database.host

      # 方式三：從 Secret 取得
      - name: DATABASE_PASSWORD
        valueFrom:
          secretKeyRef:
            name: app-secrets
            key: database.password

最佳實踐：
- 敏感資訊（密碼、API Key）一定要用 Secret
- 可能變動的設定使用 ConfigMap
- 固定的設定可以直接寫在 YAML

resources（CPU/Memory）

resources 設定 Pod 的 CPU 和記憶體配額，這是 K8s 排程與資源管理的基礎。

containers:
  - name: my-app
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "500m"
        memory: "512Mi"

CPU 單位：
- 1 = 1 個 vCPU
- 500m = 0.5 個 vCPU
- 250m = 0.25 個 vCPU

Memory 單位：
- Mi = MiB（二進制，1 Mi = 1024 Ki）
- M = MB（十進制，1 M = 1000 K）

常見的資源配置範例：

如果你正在學習 Docker 容器化，可以參考 Docker Deploy 教學 了解基礎觀念。

Health Checks 健康檢查

插圖：三種 Probe 的作用時間軸圖

場景描述：
Technical illustration showing 三種 Probe 的作用時間軸圖. Clean, professional diagram style.

視覺重點：
- Clear presentation of the concept
- Professional technical diagram style
- Easy to understand visual elements

必須出現的元素：
- Relevant technical components
- Clear labels and annotations
- Logical flow or structure

需要顯示的中文字：
無

風格：
Clean flat design, technical illustration, modern infographic style

顏色調性：
Professional blues and grays, with accent colors for emphasis

避免元素：
Cluttered design, realistic photos, complex 3D rendering

健康檢查是 Kubernetes 判斷 Pod 是否正常運作的機制。設定正確的 Health Checks 可以讓 K8s 自動處理故障的 Pod，維持服務穩定。

livenessProbe

livenessProbe 用於判斷容器是否「活著」。如果檢查失敗，K8s 會重啟容器。

containers:
  - name: my-app
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 30
      periodSeconds: 10
      timeoutSeconds: 5
      failureThreshold: 3

readinessProbe

readinessProbe 用於判斷容器是否「準備好」接收流量。如果檢查失敗，K8s 會將 Pod 從 Service 的 Endpoint 移除，不再接收新請求。

containers:
  - name: my-app
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 5
      timeoutSeconds: 3
      successThreshold: 1
      failureThreshold: 3

livenessProbe vs readinessProbe：

startupProbe

startupProbe 是 Kubernetes 1.16 新增的功能，專門用於啟動時間較長的應用程式。在 startupProbe 成功之前，livenessProbe 和 readinessProbe 都不會執行。

containers:
  - name: my-app
    startupProbe:
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 0
      periodSeconds: 10
      timeoutSeconds: 5
      failureThreshold: 30  # 30 * 10 = 300 秒容許啟動時間

適用場景：
- 需要載入大量資料的應用程式
- 舊系統遷移（啟動時間難以預估）
- 避免 livenessProbe 在啟動階段誤判並重啟容器

三種 Probe 的組合建議：

# 啟動慢的應用程式（如 Java）
startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 30
  periodSeconds: 10

# 偵測 deadlock
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  periodSeconds: 10
  failureThreshold: 3

# 偵測是否準備好接收流量
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  periodSeconds: 5
  failureThreshold: 3

完整 YAML 範例

插圖：完整 Deployment YAML 範例圖

場景描述：
Technical illustration showing 完整 Deployment YAML 範例圖. Clean, professional diagram style.

視覺重點：
- Clear presentation of the concept
- Professional technical diagram style
- Easy to understand visual elements

必須出現的元素：
- Relevant technical components
- Clear labels and annotations
- Logical flow or structure

需要顯示的中文字：
無

風格：
Clean flat design, technical illustration, modern infographic style

顏色調性：
Professional blues and grays, with accent colors for emphasis

避免元素：
Cluttered design, realistic photos, complex 3D rendering

以下提供兩個可直接複製使用的 Deployment YAML 範例。

基礎版範例

適合開發環境或簡單的應用程式：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080
          env:
            - name: NODE_ENV
              value: "production"
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "200m"
              memory: "256Mi"

進階版範例（含所有最佳實踐）

適合生產環境，包含完整的健康檢查、部署策略與資源配置：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
  labels:
    app: my-app
    environment: production
    version: v1.2.0
  annotations:
    description: "主要應用程式"
    kubernetes.io/change-cause: "更新至 v1.2.0，修復登入問題"
spec:
  replicas: 3
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: my-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: my-app
        environment: production
        version: v1.2.0
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: my-app
          image: my-registry.com/my-app:1.2.0
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8080
              name: http
              protocol: TCP
          env:
            - name: NODE_ENV
              value: "production"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: app-secrets
                  key: database-url
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
          startupProbe:
            httpGet:
              path: /healthz
              port: 8080
            failureThreshold: 30
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 0
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 0
            periodSeconds: 5
            timeoutSeconds: 3
            failureThreshold: 3
          securityContext:
            runAsNonRoot: true
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false
      imagePullSecrets:
        - name: my-registry-secret
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: my-app
                topologyKey: kubernetes.io/hostname

這個進階版範例包含了：
- 完整的 labels 與 annotations
- RollingUpdate 策略（零停機更新）
- 三種 Health Checks
- 資源限制
- Security Context（安全設定）
- Pod Anti-Affinity（分散到不同節點）

FAQ 常見問題

Q1: replicas 設為 0 會怎樣？

設定 replicas: 0 是完全合法的，Deployment 會存在但沒有任何 Pod 運行。這常用於：
- 暫時停止應用程式而不刪除 Deployment
- 根據排程自動擴展到 0（省成本）

Q2: Deployment 和 StatefulSet 該選哪個？

一般的 Web 應用程式使用 Deployment 即可。

Q3: maxSurge 和 maxUnavailable 可以都設為 0 嗎？

不行。如果兩者都是 0，代表更新時不能增加 Pod、也不能減少 Pod，更新就無法進行。至少一個必須大於 0。

Q4: 為什麼我的 Pod 一直 CrashLoopBackOff？

這通常是 livenessProbe 設定的問題：
- initialDelaySeconds 太短，應用程式還沒啟動完成就被檢查
- 檢查的端點回傳非 2xx 狀態碼
- 容器內的應用程式真的故障了

解決方案：使用 startupProbe，或增加 initialDelaySeconds。

Q5: 如何回滾到上一個版本？

# 查看版本歷史
kubectl rollout history deployment/my-app

# 回滾到上一個版本
kubectl rollout undo deployment/my-app

# 回滾到特定版本
kubectl rollout undo deployment/my-app --to-revision=2

K8s Deployment YAML 設定重點整理

掌握 Kubernetes Deployment YAML 的各項設定，是成為 K8s 進階使用者的必經之路。這篇文章涵蓋了：

• YAML 結構：apiVersion、kind、metadata、spec 四大區塊
• 副本設定：replicas 與 HPA 自動擴展
• 部署策略：RollingUpdate vs Recreate 的選擇
• Container 設定：image、ports、env、resources 詳解
• Health Checks：三種 Probe 的差異與最佳組合

建議你將進階版 YAML 範例存為模板，根據實際專案需求調整使用。

如果你想了解如何在 K8s 上部署完整的多層式架構，可以接著閱讀 K8s 三層式架構部署 教學。

🚀 Kubernetes 部署遇到問題？

從 YAML 設定到效能調校，K8s 有太多細節需要注意。

預約免費諮詢，讓 VibeFix 的工程師幫你診斷並優化 Kubernetes 部署配置。