單元 4 · 序列與巢狀

4.1 定義：兩種容器

YAML 的資料只有兩種容器：對映 mapping（鍵值組，即 dict / object）與 序列 sequence（有序清單，即 list / array）。其他一切都是「值」。掌握這兩種容器的組合，就掌握 YAML 的 90%。

4.2 序列 · Sequences

用 - （橫槓 + 空格）表示清單項，同一層的 - 對齊。

fruits:
  - apple
  - banana
  - cherry

{"fruits": ["apple",
             "banana",
             "cherry"]}

4.3 巢狀：對映裡的序列

對映的值可以是另一個序列。

server:
  ports:
    - 80
    - 443
  tls: true

4.4 巢狀：序列裡的對映（最易錯）

清單的每個元素可以是一組鍵值——這是設定檔最常見的形狀（服務清單、容器清單）。關鍵在對齊：- 與第一個鍵同層，後續鍵值與第一個鍵同縮排。

services:
  - name: web
    port: 8080
  - name: db
    port: 5432

{"services": [
  {"name": "web", "port": 8080},
  {"name": "db",  "port": 5432}]}

4.5 巢狀：多層混用

三種結構可以任意組合到任意深度——這是 YAML 描述複雜系統的方式。

pipeline:
  - name: build
    steps:
      - checkout
      - test
    env:
      DEBUG: false

{"pipeline": [{
    "name":  "build",
    "steps": ["checkout","test"],
    "env":   {"DEBUG": false}}]}

4.6 Flow style · 精簡式

想要「一行寫完」時，用 JSON 風格：序列 [ ]、對映 { }。

aliases: [prod, production]
limits: {cpu: "1.5", mem: "512Mi"}

{"aliases": ["prod","production"],
 "limits":  {"cpu": "1.5",
              "mem": "512Mi"}}

4.7 Worked Example：一次讀懂 CI 片段

jobs:
  - name: lint
    commands:
      - npm run lint
  - name: deploy
    when: main
    env: {URL: https://example.com}

練習：設計一個「學生清單」設定：每個學生有姓名、年級與選課序列（至少三個），用序列裡的對映寫出，再用 JSON 對照驗證。

延伸閱讀

• 上一篇：單元 3 · 字串與引號。
• 下一篇：單元 5 · 資料型別。
• 術語表：複習全站。

進階真實情境 Worked Example：Terraform + Helm 的 values 混合結構

DevOps 中常見「序列裡有深層巢狀對映、對映裡又包序列」的結構。以下是一份含多層混用的真實場景：

clusters:
  - name: prod-us
    node_pools:
      - name: general
        autoscaling:
          min: 3
          max: 10
        labels: [web, api]
      - name: gpu
        taints:
          - key: nvidia.com/gpu
            value: "true"
            effect: NoSchedule
  - name: staging-eu
    node_pools:
      - name: general
        autoscaling: {min: 1, max: 5}

clusters (sequence)
 ├─ {name: "prod-us", node_pools:
 │    ├─ {name: "general",
 │    │    autoscaling: {min:3, max:10},
 │    │    labels: ["web","api"]}
 │    └─ {name: "gpu",
 │         taints: [{key:"nvidia.com/gpu",
                    value:"true",
                    effect:"NoSchedule"}]}}
 └─ {name: "staging-eu", node_pools:
      └─ {name: "general",
           autoscaling: {min:1, max:5}}}

為什麼這樣設計而非替代方案：labels 用 flow 序列 [web, api] 是因為它短而扁平；taints 用 block 序列是因為每個元素有三個鍵值對，block 更清晰。autoscaling 在 staging 用 flow 是因為只有兩欄——同一份設定檔中根據內容複雜度選擇最適合的風格是 YAML 的最佳實踐。

深入原理擴充

Block vs Flow 的隱含規則

YAML 規範中，flow style 的對映中，冒號後的空格是可選的（例如 {a:1} 合法），但block style 中冒號後一定要有空格（a: 1）。這就是為什麼很多從 flow 風格複製到 block 風格的值會突然報錯——漏加了空格。

大家以為是這樣但其實不是……

診斷式疑難排解表

進階挑戰題

1. 三層巢狀挑戰：設計一個結構：序列 → 對映 → 序列 → 對映（共四層），用 block style 寫出。再用 flow style 重寫最內兩層，比較可讀性。
2. Style 選擇器：同一份資料有 block 與 flow 兩種寫法——寫出 Kubernetes containers spec（含 name、image、ports、env），然後把 env 改成 flow style。哪種更清晰？為什麼？
3. 錯位偵測遊戲：故意寫錯一個「序列裡的對映」的縮排（讓某個鍵落到錯誤層級），用 yaml.safe_load 解析並觀察結果如何變化。畫出正確 vs 錯誤的結構樹。

① 專案級端到端 Worked Example：Kubernetes 完整部署專案

K8s 是「序列與巢狀」的極致考場——containers（序列裡的對映）、env（對映裡包序列）、strategy（多層巢狀）。配合 Kustomize overlay 做多環境管理：

產出檔案樹

k8s-app/
├── base/
│   ├── namespace.yaml      # 命名空間
│   ├── deployment.yaml     # 深層巢狀主檔
│   ├── service.yaml        # 服務暴露
│   └── kustomization.yaml  # 組合 base 資源
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml   # 覆寫 replicas / 資源

關鍵檔案內容

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 1
  selector:
    matchLabels: {app: api}
  template:
    metadata:
      labels: {app: api}
    spec:
      containers:
        - name: api
          image: myapi:1.0
          ports:
            - containerPort: 8080
          env:
            - name: LOG_LEVEL
              value: info
          resources:
            limits: {cpu: "100m", memory: "128Mi"}

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - target: {kind: Deployment, name: api}
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

$ kustomize build overlays/prod | kubectl apply --dry-run=client -f - -o name
deployment.apps/api
namespace/api
service/api

$ kustomize build overlays/prod | kubectl apply --server-side --dry-run=server -f - && echo VALID
deployment.apps/api configured (server dry run)
VALID

$ kubeconform -strict -summary <(kustomize build overlays/prod)
Result: PASS

端到端流程：base/ 放標準資源 → overlays/prod 覆寫 replicas: 5 → kustomize build 產生最終 manifest → kubectl apply --dry-run=server 在 API server 驗證。整個管線的每一步都在處理「序列與巢狀」的正確性。

② 效能/品質/安全深度

品質：深度巢狀的可讀性危機

K8s Deployment 的 spec.template.spec.containers[].env[].valueFrom 可達 6–7 層縮排，這是 YAML 可讀性的極限。品質策略：

• 超過 5 層就改用 flow style 壓縮無關緊要的分支。
• 用 kubeconform / kubeval + 官方 JSON Schema 驗證欄位（攔截拼錯的欄位名）。
• 把可變欄位抽到 Kustomize patch / Helm values，讓主檔保持穩定。

效能：深層巢狀的解析深度

解析器對巢狀深度有實作上限（PyYAML 預設 ~1000 層，超過拋 maximum recursion depth exceeded）。實務上沒人會寫到 100 層，但「程式產生的 YAML」可能踩到——生成器要設定合理上限並在輸出前驗證。

安全：巢狀與權限邊界

③ 站際比較對照表

④ 互動式檢核清單

• 能寫出「序列裡的對映」並正確對齊，用 yaml.safe_load 驗證結構與預期相符。
• 能在 block 與 flow style 之間轉換，並說明各自適合的場景。
• 能讀懂 K8s Deployment 的 containers / env 深層巢狀，並指出每一層的容器類型。
• 能用 kustomize build + kubectl apply --dry-run=server 驗證一份 K8s 專案。
• 能說明 YAML 解析深度上限的存在，並知道生成器該如何防範。
• 能列出深層巢狀中「容易藏權限問題」的欄位（securityContext 等），並用掃描工具檢查。