K8s YAML 完整教學：apiVersion、kind、metadata、spec 四大區塊

K8s 為什麼要學 YAML？

K8s 所有東西都是 YAML 寫的。Pod、Deployment、Service、ConfigMap... 全部是 YAML。

比喻：YAML 是你發給 K8s 的「訂單」。你用 YAML 描述「我要 3 個 nginx Pod、開 80 port、用這個 image」，K8s 照著做。

很多新手看到 YAML 一堆縮排就放棄。其實只要記住四個區塊，所有 K8s YAML 都看得懂。

四大區塊：所有 YAML 都長這樣

apiVersion: v1          # 1️⃣ 用哪一版 API
kind: Pod               # 2️⃣ 要建什麼
metadata:               # 3️⃣ 叫什麼名字、有什麼標籤
  name: my-nginx
  labels:
    app: web
spec:                   # 4️⃣ 規格——真正的「內容」
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

全部 K8s YAML 都是這四個區塊。記住這個模板就贏一半。

1️⃣ apiVersion — 用哪一版 API

K8s 持續演進，每種資源的 API 有版本號。常見的：

kubectl explain pod                      # 看 Pod 的 apiVersion
kubectl explain deployment               # 看 Deployment 的
kubectl api-resources                    # 看全部資源跟它們的 apiVersion

新手最常踩：寫 Deployment 用了 v1 → ✗（要 apps/v1）。不確定先 kubectl explain 一下。

2️⃣ kind — 要建什麼

宣告資源類型，字母大小寫嚴格：

3️⃣ metadata — 名片資訊

「這個資源叫什麼？貼什麼標籤？」

metadata:
  name: my-nginx                    # 必填，namespace 內唯一
  namespace: default                # 沒寫預設就 default
  labels:
    app: web                        # 標籤——後面 Service 用 selector 找 Pod 就靠這個
    env: production
  annotations:
    description: "frontend nginx"   # 註解，給人看，不是給程式邏輯用

重點：

• name：必填，同 namespace + 同 kind 內唯一
• labels：後面 Service 找 Pod、Deployment 認 ReplicaSet 全靠它——超重要
• annotations：放給工具或人看的註解（如 deployer 是誰、change ticket 編號）

4️⃣ spec — 真正的內容

這個區塊每種資源都不一樣。Pod 的 spec 寫 container；Deployment 的 spec 寫 replicas + template；Service 的 spec 寫 selector + ports。

最簡單的 Pod spec：

spec:
  containers:
    - name: nginx                   # container 名字
      image: nginx:1.25             # 用哪個 image
      ports:
        - containerPort: 80         # 容器內開哪個 port
      env:                          # 環境變數
        - name: GREETING
          value: "Hello"
      resources:                    # 資源限制
        requests:
          memory: "128Mi"
          cpu: "100m"
        limits:
          memory: "256Mi"
          cpu: "200m"

kubectl explain pod.spec 會列出所有可用欄位——這個指令是 K8s 自帶的最強學習工具。

完整範例：寫第一個 Pod

把四個區塊湊起來：

apiVersion: v1
kind: Pod
metadata:
  name: my-first-pod
  labels:
    app: nginx
spec:
  containers:
    - name: web
      image: nginx:1.25-alpine
      ports:
        - containerPort: 80

存成 pod.yaml，跑：

kubectl apply -f pod.yaml          # 建立
kubectl get pods                    # 確認
kubectl delete -f pod.yaml         # 刪除

會這個你就會 K8s 一半了。

YAML 的 5 個踩坑

1. 縮排只能用「空格」，不能用 Tab

spec:
  containers:        # 用 2 個空格 ✅
    - name: nginx    # 用 4 個空格 ✅
spec:
\tcontainers:        # 用 Tab ❌ K8s 直接拒絕

VS Code 設定 editor.tabSize: 2 + editor.insertSpaces: true 一勞永逸。

2. 冒號後面一定要有空格

name: nginx        ✅
name:nginx         ❌

3. 列表用 -，- 後面也要空格

containers:
  - name: nginx          ✅
  -name: nginx           ❌

4. 字串裡有特殊字元要加引號

value: "true"            ✅（因為 true 會被當成 boolean）
value: "192.168.1.1"     ✅（IP 字串建議加引號）
value: "$(ENV_NAME)"     ✅（有 $ 的）

5. 一個檔案放多個資源用 --- 隔開

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  key: value
---
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  ...

--- 是 YAML 標準的「文件分隔符」——一個檔案放整個應用全部 YAML 很方便。

看不懂某個欄位？這個指令救命

最重要的學習工具：

kubectl explain pod                      # Pod 整體
kubectl explain pod.spec                 # 看 spec 有哪些欄位
kubectl explain pod.spec.containers      # 看 container 有哪些欄位
kubectl explain deployment.spec.template # 階層深沒關係，一直 . 下去

kubectl explain --recursive 會把整個樹狀結構一次列出來——遇到不會寫的 YAML 一定先 explain。

不想自己寫怎麼辦？讓 K8s 給你模板

# 用 --dry-run 產生 Deployment YAML 範本
kubectl create deployment nginx --image=nginx --replicas=3 --dry-run=client -o yaml > deploy.yaml
# 用 expose 產生 Service YAML
kubectl expose deployment nginx --port=80 --dry-run=client -o yaml > svc.yaml

--dry-run=client 表示「不真的建，只生 YAML 給我看」。新手寫 YAML 就靠這招——產生模板再改。

重點整理

• K8s 所有資源都是 YAML，永遠四個區塊：apiVersion + kind + metadata + spec
• apiVersion 不同資源不同版本，不確定就 kubectl explain
• kind 字母大小寫嚴格（Pod 不是 pod）
• metadata 的 labels 後面 Service 認 Pod 全靠它
• spec 各資源不一樣，kubectl explain 是最強的查詢工具
• 5 個坑：用空格不用 Tab、冒號要空格、- 要空格、特殊字元加引號、多資源用 --- 分隔
• 不想自己寫用 kubectl ... --dry-run=client -o yaml 生模板

下一步

YAML 文法看懂了，下一篇直接動手：第一個 Pod 完整 CRUD——apply / get / describe / logs / exec / delete 五招完整跑一遍，做完你就有 K8s 基礎實戰能力。