前一天使用 YAML 格式來建立 pod，k8s 的資源設定皆使用 YAML 格式來表示，在之後叢集的相關操作也都會大量使用這種格式來實作，趁這個機會來好好熟悉 YAML 格式的規範。

除了建立 k8s 元件(deployment、service 和 pod) 會使用到外。Docker 的 docker-compose.yaml 也是使用 YAML 的格式。

YAML

YAML 不是標記式語言，YAML 是資料序列化語言，其資料結構具高可讀性。YAML 與 python 的相似之處在於皆是使用縮進的範圍來表示結構，被廣泛用於設定、資料儲存、及應用程式間的資料交換。

相關規範

• 縮排時使用「空白」、不允許用 Tab
• 縮排時，同一層的空格要空幾格都行、同一層的空格數量必須一致。(空格數必須大於父節點的空格數，並靠左對齊)
• 區分大小寫
• 副檔名可使用 .yaml 或 .yml
• 編碼允許為 UTF-8、UTF-16 和 UTF-32

我們直接以例子來學習 YAML，底下是 k8s 在建立 pod 使用的設定檔：

apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  containers:
  - name: nginx
    image: nginx:latest
    ports:
    - containerPort: 80

在使用 yaml 來建立 pods、replica、deployment 或 services 時，一定會有四個屬性 apiVersion、kind、metadata 與 spec，這些屬性是最靠左、最上層的屬性。

純量 (Scalars) 或稱 key-value pair

YAML 使用 key 和 value 的形式來表現資料，值可以是字串或數字。

需要注意的是 key 之後的「帽號:」後一定要留一個空白，再填上 value。

# key: value
# 字串
apiVersion: v1

# 數字
- containerPort: 80

以下是錯誤示範：

# 錯誤示範，沒有空白格
apiVersion:v1 

縮排

YAML 以不同數量的縮進來表示資料的「層級」與「範圍」：

apiVersion: v1
kind: Pod
metadata:
  name: my-pod

apiVersion、kind、metadata 為同一層，而 metadata 是一個巢狀物件，裡面包含下一層的屬性 name。

註解

有單行與行內註解，但沒有區塊註解。

• 單行註解

  # 資源的版本，目的是告訴 k8s 要使用哪個 API 版本。
  # 因隨著 k8s 的發展，API 版本會不斷更新。
  apiVersion: v1
  

• 行內註解

  apiVersion: v1
  kind: Pod # 告訴 Kubernetes 這份 config 檔案是用於建立哪種資源，這邊是指 Pod
  metadata:
    name: my-pod # 這邊是定義 pod 的名稱
  

Dicontionary

YAML 除了字串與數字型別外，還有 dictionary(字典)與 array(陣列)的型別。

metadata 為包含一組 key-value 的字典。

...
metadata:
  name: mypod

另一個例子，底下為包含兩組 key-value 的字典，以縮進來表示包含的屬性 name 與 age。

user:
  name: Mike
  age: 25

Nested Dictionaries

字典裡面也可以包含字典，底下為 user 的字典，該字典包含一個子字典 address。

user:
  name: Mike
  age: 25
  address:
    country: Taiwan
    city: Taoyuan

List of Dictionary

字典裡也可以包含陣列，底下為 spec 字典，該字典包含一個 containers 陣列。

...
spec:
  containers:
  - name: nginx
    image: nginx:latest

Array list

陣列的表示為 key 去對應到多個 values，使用符號 - 與一格空白，後面為 value。
底下為 color 陣列的範例。

colors:
- red
- green
- blue

YAML 還可以用來表示更複雜的陣列，例如包含陣列的陣列、物件的陣列。

Nested Arrays (Arrays of Arrays)

定義一個 web 的陣列，該陣列包含兩個子陣列：frontend 和 backend，frontend 陣列包含三個字串。

web:
- frontend:
  - html
  - css
  - javascript
- backend:
  - python
  - java
  - csharp
  - php

Array of Object (nested array)

以下範例定義了一個 containers 的陣列，該陣列包含一個容器物件。每個容器都有一個 name 與 image 屬性。

...
  containers:
  - name: nginx
    image: nginx:latest

Multi Line Strings

當屬性的資料太多難以以一行來顯示時，可以換行來表示。有兩種換行形式：| 與 > 。

• 使用 | 符號會保留每一行的換行符號(\n)。

string: |
  The quick brown fox
  jumps over the lazy dog.

產出結果:
The quick brown fox\n
jumps over the lazy dog.

• 使用 > 符號以空格來取代每一行的換行符號(\n)。

string: >
  The quick brown fox
  jumps over the lazy dog.

產出結果:
The quick brown fox jumps over the lazy dog.

另外可搭配使用 - 與 + 來處理結尾(最後一行與之後)的換行符號。

• 使用 - 來刪除結尾換行符號。
• 使用 + 來保留所有的結尾換行符號。
• 若不使用則僅保留結尾文字那行的換行符號。

使用 >- 不保留結尾的換行符號，因為會看不到換行，另外標示出 \n。

string: >-\n
  The quick brown fox\n
  jumps over the lazy dog.\n

產出結果(最後一行不保留換行):
The quick brown fox\n
jumps over the lazy dog.

其他可以參考 YAML Multiline 網站。

線上 yaml 格式驗證

YAMLlint 可以驗證 YAML 檔格式是否正確。

參考來源

1. w3schools.io - YAML Tutorial
2. YAML Multiline