【IT PROFESSIONAL TRAINING SERIES】YAML完全マスター講座　Docker Compose・GitHub Actions・Kubernetesで 迷わず書ける、読める、直せるようになる

1 2 IT PROFESSIONAL TRAINING SERIES 3 4 YAML完全マスター講座 Docker Compose・GitHub Actions・Kubernetesで 迷わず書ける、読める、直せるようになる 5 6 7 8 9 10 # docker-compose.yml services: 11 web: image: nginx:latest ports: 12 13 - "80:80" うさうさ研修工房 14

COURSE OVERVIEW この講座で身につくこと ① ② ③ 正確な文法理解 実務ツールへの応用 エラーを未然に防ぐ力 インデント・型・構造を体系的に理解し、自己流 Docker Compose、GitHub Actions、Kubernetes Norway問題やインデント崩れなど、事故りやす の思い込みを排除する の実ファイルを読み書きできる い落とし穴を先に知っておく 対象者： インフラ・バックエンド初級〜中級エンジニア、 DevOps未経験からステップアップしたい方 第1章 YAML入門 2

TABLE OF CONTENTS 講座の全体構成 1 YAML入門 定義・用途・JSON/XMLとの比較 2 基本文法 スカラー・シーケンス・マッピング・ネスト 3 応用構文 フロースタイル・アンカー・複数ドキュメント 4 実務での活用 Docker Compose・GitHub Actions・Kubernetes 5 落とし穴と品質管理 頻出エラー・Norway問題・Linter活用 6 まとめと演習 チェックリスト・演習問題・次のステップ 第1章 YAML入門 3

SECTION 1 YAML入門 What Is YAML? 「YAML Ain't Markup Language」——設定ファイルの世界標準になった、人が読み書きしやすいデータ記述言語。まずはその正体 と、なぜここまで普及したのかを理解する。

1-1. DEFINITION YAMLとは何か YAML（ヤムル）は、構造化データをテキストで表現するための言語。もともとは"YAML Ain't Markup Language" の再帰的頭字語で、XMLのような「マークアップ言 語ではない」ことを強調している。 インデントで構造を表現 波括弧やタグを使わず、字下げの深さで階層を表 す 人にもマシンにも読みやすい JSONの上位互換 設定ファイルとして書きやすく、パーサーも軽量 多くのYAMLパーサーは JSONもそのまま読み込める sample.yaml # これがYAML — インデントだけで構造を表す name: usausa-training version: 1.9 topics: - Linux - Docker 第1章 YAML入門 5

1-2. WHY YAML MATTERS なぜ、今 YAMLを学ぶ必要があるのか 1 コンテナ・オーケストレーション 2 Docker Compose、Kubernetesマニフェストの標準記法 3 構成管理・ IaC Ansible Playbook、AWS CloudFormation（YAML形式） CI/CDパイプライン GitHub Actions、GitLab CI、CircleCIの設定ファイル 4 アプリケーション設定 Spring Boot、Rails等、多くのフレームワークの設定ファイル 現場のリアル インフラ・バックエンド職では、YAMLを「読めない・書けない」ことがそのまま作業速度の差になる。JSONより記述量が少なく可読性も高いため、設定ファイルの世界 標準として定着している。 第1章 YAML入門 6

1-3. COMPARISON

YAML vs JSON vs XML

# YAML

// JSON

<!-- XML -->

user:

{

<user>
"user": {

name: Yuki
age: 28
admin: true

<name>Yuki</name>

"name": "Yuki",

<age>28</age>

"age": 28,

<admin>true</admin>

"admin": true

</user>

}
}

観点

YAML

JSON

XML

可読性

◎ 非常に高い

○ 高い

△ 冗長になりがち

コメント

◎ 対応

× 非対応

○ 対応

記述量

◎ 少ない

○ やや多い

△ 多い

主な用途

設定ファイル全般

API通信・データ交換

文書・レガシー連携

第1章 YAML入門

7

SECTION 2 基本文法をマスターする Core Syntax スカラー・シーケンス・マッピングというたった3つの要素の組み合わせで、YAMLのほぼすべての構造は表現できる。ここを正確に 押さえれば、複雑な設定ファイルも怖くなくなる。

2-1. GOLDEN RULES 基本ルール — 3つの絶対原則 01 02 03 インデントはスペースのみ コロンの後に半角スペース 同じ階層は同じインデント幅 タブ文字は禁止。半角スペース2つが業界標準 「key: value」— コロン直後のスペースは必須 兄弟要素のインデントが1文字でもずれるとエラー 良い例 vs 悪い例 OK NG # ✓ 正しい # ✗ 誤り name: Yuki name:Yuki role: engineer ← スペース無し role: engineer ← 余計な字下げ skills: skills: - Docker ← 3文字インデント - Docker 第2章 基本文法 9

2-2. SCALAR TYPES スカラー型 — 最小単位の値 スカラーとは「それ以上分解できない単一の値」のこと。 YAMLは記法を見て自動的に型を推測する。 types.yaml # 文字列（クォート省略可） title: YAML完全マスター講座 # 整数・浮動小数点数 max_retry: 5 timeout_sec : 2.5 # 真偽値（true/false, yes/no も可） enabled: true debug_mode : false # null（未定義・空を表す 3つの書き方） owner: null backup: ~ 第2章 基本文法 memo: # 何も書かなければ null 10

2-3. STRINGS

文字列の書き方 — クォートは使い分ける
quotes.yaml

# クォートなし（基本形）
app_name: training-app

クォートが必須になるケース
!

url: "http://example.com: 8080"

# シングルクォート
# → エスケープを一切解釈しない

コロン+スペースを含む文字列

!

数字に見える文字列を保持したい

path: 'C:\Users\yuki'
zip_code: "03150"

# ダブルクォート

!

true/falseに見える文字列

# → \n 等のエスケープを解釈する
answer: "yes"

# 文字列の yesを保持

message: "Hello,\nWorld!"
!

特殊記号で始まる文字列
value: "#not-a-comment"

第2章 基本文法

11

2-4. MULTI-LINE STRINGS 複数行文字列 — | と > の使い分け literal | folded > # ブロックスタイル | # フォールドスタイル > # → 改行をそのまま保持 # → 改行をスペースに変換 script: | description : > echo start この講座では npm install YAMLの基礎から npm run build 実務活用まで学びます # 結果：改行込みの 3行の文字列 # 結果：1行に連結された文字列 # "echo start\nnpm install\n # "この講座では YAMLの基礎から # # npm run build\n" 第2章 基本文法 実務活用まで学びます \n" 12

2-5. SEQUENCES シーケンス（配列） — ハイフンで並べる list.yaml # 文字列のリスト ポイント languages : - Python 「- 」（ハイフン＋半角スペース）で1要素を表す - Go - TypeScript ハイフンの列は親キーと同じか、1段深いインデントに置く # オブジェクトのリスト members: - name: Yuki 1つの要素の中にさらにマッピング（key: value）を書ける role: 講師 - name: Theo role: アシスタント 第2章 基本文法 フロースタイルなら [Python, Go, TypeScript] とも書ける（応用編で解説） 13

2-6. MAPPINGS マッピング（連想配列） — key: value の集合 mapping.yaml # マッピング = キーと値のペアの集合（他言語の辞書・オブジェクトに相当） database: host: db.internal port: 5432 credentials : user: admin password : ${DB_PASSWORD} # キーは文字列に限らず、数値や booleanも使える（あまり一般的ではない） 200: OK 404: Not Found 第2章 基本文法 14

2-7. NESTING ネスト構造 — 組み合わせれば何でも表現できる シーケンスの中にマッピング、マッピングの中にシーケンス ——自由に組み合わせて複雑なデータも表現できる。 compose.yaml services: web: image: nginx:latest ports: # マッピングの中のシーケンス - "80:80" - "443:443" environment: - NODE_ENV=production db: image: postgres:16 volumes: # シーケンスの中のマッピングも可 - source: db-data target: /var/lib/postgresql 第2章 基本文法 15

2-8. COMMENTS コメントの書き方 comment.yaml 注意点 # 行頭コメント name: training-app # 行末コメントも可 # の前には半角スペースを入れる（詰めて書くと文字列の一部と誤認される ことがある） # JSONと違い、YAMLはコメントを # ネイティブにサポートしている # → 設定ファイルとして選ばれる # 理由のひとつ 文字列の中の # はコメントにならない（クォートで囲まれていれば安全） 💡 現場のコツ： 「なぜこの値なのか」をコメントで残しておくと、半年後の自分やチームメンバーが助かる。設定ファイルはコードと同じくらい読まれる。 第2章 基本文法 16

SECTION 3 一歩進んだ構文 Advanced Syntax 基本文法をマスターしたら、次は現場のYAMLファイルでよく見かける応用構文へ。アンカーや複数ドキュメントを知っておくと、他 人の書いたYAMLも迷わず読める。

3-1. FLOW STYLE フロースタイル — 1行で書く YAML ここまでのインデント形式は「ブロックスタイル」。 JSONのように波括弧・角括弧で 1行にまとめる「フロースタイル」も使える。 block flow # ブロックスタイル # フロースタイル（結果は同じ） fruits: fruits: [apple, banana] - apple - banana point: point: {x: 10, y: 20} # 短い配列・小さなオブジェクトで便利 x: 10 # GitHub Actionsの on: [push, pull_request] y: 20 # などでよく見かける 第3章 応用構文 18

3-2. ANCHORS & ALIASES アンカーとエイリアス — 繰り返しを 1箇所にまとめる anchor.yaml # & でアンカー（印）を付け、* で再利用する defaults: &app_defaults restart: always logging: json-file services: web: <<: *app_defaults # マージキーで丸ごと展開 image: nginx:latest worker: <<: *app_defaults # 同じ設定を再利用 image: worker:latest 第3章 応用構文 19

3-3. MULTIPLE DOCUMENTS 複数ドキュメント — 1ファイルに複数の YAMLをまとめる k8s.yaml # --- で区切ると、1つのファイルに複数のYAML文書を書ける # Kubernetesマニフェストでよく使われる apiVersion: v1 kind: Service metadata: name: web-service --apiVersion: apps/v1 kind: Deployment metadata: name: web-deployment ... 第3章 応用構文 # 明示的な終端（省略可） 20

SECTION 4 実務で使う YAML YAML in the Real World 文法を理解したら、実際のツールで使われている本物のYAMLファイルを読み解いていく。ここからは「読める」から「実務で使え る」へのステップアップ。

4-1. DOCKER COMPOSE 実例①： docker-compose.yml docker-compose.yml 読み解きポイント services: web: build : . services 配下が各コンテナの定義 ports : - "3000:3000" depends_on : - db depends_on で起動順序を制御 environment : DATABASE_URL : postgres://db:5432 db: image : postgres:16 environment はマッピング形式でもシーケンス形式でも書け る volumes : - db_data:/var/lib/postgresql volumes: volumes はトップレベルで名前付きボリュームを宣言 db_data : 第4章 実務での活用 22

4-2. GITHUB ACTIONS 実例②： CIワークフロー .github/workflows/ci.yml 読み解きポイント name: CI on: [push, pull_request ] on はフロースタイルの配列で複数トリガーを指定 jobs: test: runs-on : ubuntu-latest jobs → 各ジョブ → steps という3階層構造 steps : - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: steps はシーケンス。各要素が1つの操作 node-version : "20" - run: npm ci && npm test with は uses したアクションへの引数 第4章 実務での活用 23

4-3. KUBERNETES 実例③： Deploymentマニフェスト deployment.yaml 読み解きポイント apiVersion: apps/v1 kind: Deployment 深いネストが特徴。インデントのズレが命取りになりやすい metadata: name: web-app spec: replicas: 3 selector: replicas: 3 でPodの複製数を指定 matchLabels: app: web-app template: spec: containers はシーケンス。複数コンテナも1つのPodに定義 できる containers: - name: web image: web-app:1.2 第4章 実務での活用 エディタのYAML拡張機能でインデントガイドを表示すると安 全 24

SECTION 5 落とし穴と品質管理 Pitfalls & Quality Control YAMLは書きやすい一方、静かに壊れるファイルでもある。事故が起きやすいポイントを先に知り、 Linterで機械的に守る仕組みを 持つことが、プロと初心者の分かれ目。

5-1. COMMON MISTAKES よくある間違い TOP4 タブ文字の混入 1 対策： エディタでタブ→スペース自動変換を設定 エディタの自動インデントがタブを挿入し、パースエラーになる インデント幅の不統一 2 対策： .editorconfig でプロジェクト全体を統一 同じ階層なのに2スペースと4スペースが混在している コロンの後のスペース忘れ 3 対策： Linter・フォーマッタで自動チェック key:value と書いてしまい、キー全体が1つの文字列と解釈される 全角スペースの混入 4 対策： エディタの不可視文字表示を有効化 コピペ時に紛れ込み、見た目は正常なのにエラーになる 第5章 落とし穴と品質管理 26

5-2. THE NORWAY PROBLEM 「ノルウェー問題」 — 意図しない型変換 YAML 1.1 では、クォートなしの NO が国名の「ノルウェー」ではなく真偽値false と解釈されてしまう、有名な落とし穴。 NG OK # 国名リストのつもりが …… # クォートで囲んで文字列だと countries : # 明示すれば安全 - Japan - NO countries : # ← false と解釈される！ - France - Japan - "NO" # 文字列として保持 - France # YAML1.1 では NO, Off, Y, On も # 真偽値として予約されている # YAML1.2 ではtrue/false のみに # 制限されたが、パーサー実装に # よって挙動が異なるため過信は禁物 第5章 落とし穴と品質管理 27

5-3. LINTING & VALIDATION Linter・検証ツールの活用 yamllint エディタ拡張機能 各ツール専用の検証コマンド インデント・行末スペース・重複キーなどを静的に検 VS Codeの「YAML」拡張等。リアルタイムでスキーマ docker compose config、kubectl apply 査するCLIツール。CIに組み込みやすい 検証・補完が効く --dry-run=client 等でツール固有の検証も併用 terminal $ yamllint docker-compose.yml docker-compose.yml 12:8 error wrong indentation: expected 6 but found 8 18:1 warning missing document start "---" $ docker compose config --quiet 第5章 落とし穴と品質管理 (indentation) (document-start) # 構文だけでなく解釈結果まで検証 28

6-1. CHECKLIST 学習チェックリスト まとめ ✓ スペースとタブの違いを説明できる ✓ アンカー（&）とエイリアス（*）を使える ✓ スカラー・シーケンス・マッピングの違いを説明できる ✓ docker-compose.ymlを自力で読み解ける ✓ | と > の使い分けを説明できる ✓ Norway問題のようなクォート漏れリスクを知っている ✓ クォートが必要になるケースを3つ挙げられる ✓ yamllintなどのLinterを実行できる 29

6-2. EXERCISE 演習問題 — このYAMLの間違いを見つけよう quiz.yaml ヒント：3箇所の誤りがあります 1 services: 2 web: 3 image:nginx:latest 4 ports: 5 - "80:80" 6 environment: 7 DEBUG: NO 8 db: 9 image: postgres:16 1 3行目に着目してみましょう 2 5行目に着目してみましょう 3 7〜9行目に着目してみましょう 解答はテキスト教材の巻末に掲載しています。 まとめ 30

6-3. NEXT STEPS 参考資料と、次に学ぶべきこと YAML公式仕様 yaml.org — YAML 1.2の正式な仕様書 yamllintドキュメント Linterの詳細なルール一覧と設定方法 各ツールの公式リファレンス Docker Compose / GitHub Actions / Kubernetesの公式YAMLスキーマ 次に学ぶと良いトピック Docker / Docker Compose入門 → 本講座の知識をコンテナ実践へ GitHub Actions実践 → CI/CDパイプラインの自動化 Kubernetes基礎 → コンテナオーケストレーションの世界へ まとめ 31

1 2 3 COURSE COMPLETE 4 お疲れさまでした 5 6 7 あなたはもう、YAMLを「なんとなく」ではなく 「理解して」書ける段階にいます。 8 9 10 status: completed next_action: practice_in_your_own_project 11 confidence_level: up 12 13 うさうさ研修工房 14