Kubernetes Deployment YAML 清單檔案完整範本與欄位詳解

身為一個常常在寫 K8s manifest 的人，每次要建新的 Deployment 時總是得到處翻舊檔案拼拼湊湊，實在很沒效率。所以我整理了一份涵蓋大部分常用欄位的 Deployment 範本，之後要用的時候直接複製貼上再依需求刪減就好，省下不少時間。

Kubernetes 元件架構概覽（圖片來源：kubernetes.io）

完整 Deployment 範例清單檔案

以下是一個相當完整的 Deployment YAML 範本，基本上日常會用到的欄位都包含在裡面了：

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    version: "1.1.6"
  labels:
    k8s-app: deployment-nginx
  name: deployment-nginx
  namespace: test
spec:
  minReadySeconds: 30
  progressDeadlineSeconds: 600
  replicas: 2
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: nginx
      env: test
  strategy:
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: nginx
        env: test
    spec:
      affinity:
        nodeAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - preference:
              matchExpressions:
              - key: node-memory-size
                operator: Gt
                values:
                - "8"
            weight: 1
      containers:
      - name: nginx
        env:
        - name: MY_ENV
          value: PRO
        image: nginx:1.21.6
        imagePullPolicy: IfNotPresent
        lifecycle:
          postStart:
            exec:
              command:
              - /bin/sh
              - -c
              - echo 'Container was started'
          preStop:
            exec:
              command:
              - /bin/sh
              - -c
              - sleep 10
        livenessProbe:
          failureThreshold: 3
          httpGet:
            path: /index.html
            port: 80
            scheme: HTTP
          initialDelaySeconds: 60
          periodSeconds: 3
          successThreshold: 1
          timeoutSeconds: 2
        ports:
        - containerPort: 80
          protocol: TCP
        readinessProbe:
          failureThreshold: 3
          httpGet:
            path: /index.html
            port: 80
            scheme: HTTP
          initialDelaySeconds: 5
          periodSeconds: 3
          successThreshold: 3
          timeoutSeconds: 2
        resources:
          limits:
            cpu: 500m
            ephemeral-storage: 2000Mi
            memory: 512Mi
          requests:
            cpu: 200m
            ephemeral-storage: 1000Mi
            memory: 512Mi
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
        volumeMounts:
        - mountPath: /tmp
          name: ephemeral
      dnsConfig:
        searches:
        - my-ns.svc.cluster.local
        - test.svc.cluster.local
        - svc.cluster.local
        - cluster.local
      dnsPolicy: ClusterFirst
      hostAliases:
      - hostnames:
        - gray.mylocal.cn
        ip: 192.168.6.16
      hostNetwork: false
      imagePullSecrets:
      - name: my-registry-secret
      initContainers:
      - name: setsysctl
        command:
        - sh
        - -c
        - |
          sysctl -w net.core.somaxconn=65535
          sysctl -w net.ipv4.ip_local_port_range="1024 65535"
          sysctl -w net.ipv4.tcp_tw_reuse=1
          sysctl -w fs.file-max=1048576
        image: busybox
        imagePullPolicy: IfNotPresent
        securityContext:
          privileged: true
      priority: 100
      preemptionPolicy: IfRequired
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      serviceAccount: my-service-account
      serviceAccountName: my-service-account
      shareProcessNamespace: false
      terminationGracePeriodSeconds: 30
      tolerations:
      - effect: NoSchedule
        key: node-role
        operator: Equal
        value: gateway
      volumes:
      - name: ephemeral
        emptyDir: {}

各層級欄位說明

Deployment 頂層欄位

欄位	說明
`apiVersion`	指定所使用的 Kubernetes API 版本，Deployment 使用 `apps/v1`
`kind`	資源類型，這裡固定填 `Deployment`
`metadata`	資源的中繼資料，像是名稱、命名空間等
`spec`	資源的詳細規格定義

deployment.metadata 欄位

欄位	說明
`annotations`	註解資訊，可放版本號、描述等額外標記，對監控和自動化很有幫助
`labels`	標籤，後續可透過 label selector 篩選對應的 Deployment
`name`	Deployment 名稱
`namespace`	所屬命名空間

deployment.spec 欄位

欄位	說明
`minReadySeconds`	Pod 就緒後需等待多少秒才視為可用（Available），預設 0
`paused`	是否暫停此 Deployment 的操作，預設 `false`
`progressDeadlineSeconds`	等待升級進度的逾時時間，超過則視為升級失敗
`replicas`	要建立的 Pod 副本數量
`revisionHistoryLimit`	保留多少份舊的 ReplicaSet 歷史紀錄，供回滾使用
`selector`	用來挑選歸屬於此 Deployment 的 Pod 的標籤選擇器
`strategy`	更新策略，`RollingUpdate`（滾動更新）或 `Recreate`（先砍後建）
`template`	Pod 範本定義，語法跟 Pod spec 完全相同，只是不需要 `apiVersion` 和 `kind`

Deployment 透過 ReplicaSet 管理 Pod 副本

deployment.spec.template 欄位

欄位	說明
`metadata`	Pod 的中繼資料，作為範本時只需設定 `annotations` 和 `labels`
`spec`	Pod 的詳細規格設定

deployment.spec.template.spec 欄位

這一層的欄位比較多，我用表格整理如下：

欄位	說明
`activeDeadlineSeconds`	Pod 啟動後最長可運作的秒數，超過就會被終止，預設 0（不限）
`affinity`	親和性設定，控制 Pod 與節點或其他 Pod 之間的調度偏好
`containers`	定義 Pod 內的一個或多個容器，每個容器有自己的映像檔、環境變數等設定
`dnsConfig`	自訂 Pod 的 DNS 組態
`dnsPolicy`	DNS 策略：`Default`、`ClusterFirst`（優先叢集內 DNS）、`ClusterFirstWithHostNet`
`hostAliases`	設定主機別名，等同直接改 `/etc/hosts`
`hostNetwork`	是否使用主機網路，設為 `true` 時容器直接綁定主機網路介面
`imagePullSecrets`	拉取私有映像檔時需要的認證憑證
`initContainers`	初始化容器，會在主容器啟動前依序執行，全部成功才啟動主容器
`nodeName`	直接指定 Pod 要跑在哪個節點上
`nodeSelector`	透過標籤選擇器指定 Pod 可以調度到哪些節點
`priority`	優先權值，數值越高越優先被調度
`preemptionPolicy`	搶佔策略：`PreemptLowerPriority`（可搶佔低優先權 Pod）或 `Never`
`restartPolicy`	重啟策略：`Always`、`OnFailure`、`Never`
`schedulerName`	指定使用哪個調度器
`securityContext`	安全上下文設定，可指定使用者 ID、權限等
`serviceAccount` / `serviceAccountName`	為 Pod 指定 Service Account，用於 API 存取授權
`shareProcessNamespace`	設為 `true` 時所有容器共用 process namespace
`terminationGracePeriodSeconds`	優雅終止的等待時間（秒）
`tolerations`	容忍度設定，讓 Pod 可以調度到帶有對應污點（Taint）的節點上
`volumes`	定義儲存卷的設定

deployment.spec.template.spec.containers 欄位

欄位	說明
`args`	容器的命令列參數
`command`	容器的入口點指令，會覆蓋映像檔中的預設命令
`env`	環境變數設定
`image`	使用的映像檔及版本
`imagePullPolicy`	拉取策略：`Always`（每次都拉）、`IfNotPresent`（本地沒有才拉）、`Never`（只用本地的）
`lifecycle`	生命週期 Hook：`postStart`（建立後執行）和 `preStop`（終止前執行）
`livenessProbe`	存活探針，用來偵測容器是否還活著
`name`	容器名稱
`ports`	容器的連接埠設定
`readinessProbe`	就緒探針，偵測容器是否已準備好接收流量
`resources`	資源需求（requests）和限制（limits），包含 CPU、記憶體、ephemeral-storage
`startupProbe`	啟動探針，在容器啟動階段做健康檢查
`terminationMessagePath`	終止訊息儲存路徑，預設 `/dev/termination-log`
`terminationMessagePolicy`	終止訊息策略：`File` 或 `FallbackToLogsOnError`
`volumeMounts`	將 Volume 掛載到容器內的指定路徑

小結

這份範本基本上覆蓋了日常撰寫 Deployment 時會碰到的絕大多數欄位。實際使用時不需要全部都寫上，依據自己的需求擷取對應區塊即可。像我自己平常最常用的就是 resources、livenessProbe/readinessProbe、strategy 和 affinity 這幾個區塊，其他的看情境再加就好。

希望這份整理對你有幫助，之後寫 manifest 就不用再到處翻了！