YAML 구문 튜토리얼: 실용적인 입문

YAML (YAML Ain't Markup Language)은 설정 파일, CI/CD 파이프라인, 인프라 코드에 광범위하게 사용되는 사람이 읽을 수 있는 데이터 직렬화 포맷입니다. Docker Compose, Kubernetes, GitHub Actions, 또는 Ansible을 다루고 있다면 이미 매일 YAML을 사용하고 있습니다. 이 튜토리얼은 YAML을 자신있게 작성하기 위해 필요한 모든 것을 다룹니다.

왜 YAML인가?

YAML의 주요 장점은 가독성입니다. JSON과 YAML에서 동일한 데이터를 비교하세요:

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML은 더 적은 구두점으로 동일한 구조를 달성합니다. 중괄호 없음, 단순한 경우에 대괄호 없음, 필수 따옴표 없음. 이것이 설정 파일을 손으로 읽고 편집하기 쉽게 만듭니다.

기본 데이터 유형

스칼라

YAML은 값에서 자동으로 유형을 추론합니다:

string: hello world          # 문자열 (따옴표 불필요)
quoted: "hello world"        # 명시적 문자열
integer: 42                  # 정수
float: 3.14                  # 부동소수점
boolean: true                # 불리언 (true/false, yes/no, on/off)
null_value: null             # Null (~이나 빈 값도 가능)
date: 2025-01-15             # 날짜 (ISO 8601)

일반적인 함정: yes, no, on, off 같은 값은 불리언으로 해석됩니다. "yes" 문자열을 의미한다면 따옴표를 사용하세요: "yes".

문자열과 따옴표

문자열에 따옴표가 거의 필요하지 않지만 일부 경우에는 필요합니다:

plain: 이것은 일반 문자열입니다
single: '\n을 리터럴 백슬래시-n으로 유지'
double: "\n을 개행으로 해석"
colon: "값: 콜론이 있으면 따옴표 필요"
hash: "값 # 해시가 있으면 따옴표 필요"

멀티라인 문자열

YAML에는 두 가지 멀티라인 스타일이 있습니다:

리터럴 블록 (|) — 줄 바꿈 유지:

description: |
  이것은 첫 번째 줄입니다.
  이것은 두 번째 줄입니다.
  
  이것은 네 번째 줄입니다 (빈 줄 이후).

접힌 블록 (>) — 줄을 공백으로 연결:

description: >
  이것은 하나의 줄로
  접히는 긴 문단
  입니다.

후행 개행을 제거하려면 -를 추가하고 (|-, >-), 유지하려면 +를 사용하세요 (|+, >+).

컬렉션

목록 (시퀀스)

# Block 스타일
fruits:
  - apple
  - banana
  - cherry

# Flow 스타일 (인라인)
fruits: [apple, banana, cherry]

맵 (매핑)

# Block 스타일
person:
  name: Alice
  age: 30
  city: London

# Flow 스타일
person: {name: Alice, age: 30, city: London}

중첩 구조

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

앵커와 별칭

앵커 (&)와 별칭 (*)으로 값을 재사용할 수 있습니다:

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # 기본값 오버라이드

<< 병합 키는 앵커의 모든 속성을 포함합니다. 병합 후 정의된 속성이 앵커된 값을 오버라이드합니다. 고급 앵커 패턴에 대해서는 YAML 앵커와 별칭 가이드를 참조하세요.

다중 문서

단일 YAML 파일이 ---로 구분된 여러 문서를 포함할 수 있습니다:

---
# 문서 1: 설정
apiVersion: v1
kind: ConfigMap
---
# 문서 2: 서비스
apiVersion: v1
kind: Service

이것은 Kubernetes 매니페스트에서 일반적으로 사용됩니다.

일반적인 함정

1. 들여쓰기 오류

YAML은 공백을 사용하며 탭은 절대 사용하지 않습니다. 일관되지 않은 들여쓰기가 가장 흔한 오류입니다:

# 잘못됨 - 혼합 들여쓰기
server:
  host: localhost
    port: 8080  # 오류: 예상치 못한 들여쓰기

# 올바름
server:
  host: localhost
  port: 8080

YAML 포매터를 사용하여 들여쓰기 문제를 자동으로 수정하세요.

2. 노르웨이 문제

NO (노르웨이) 같은 국가 코드가 불리언 false로 해석됩니다:

# 잘못됨
countries:
  - NO  # false로 해석됨!
  - SE
  - DK

# 올바름
countries:
  - "NO"
  - SE
  - DK

3. 따옴표 없는 특수 문자

값의 콜론, 해시, 대괄호는 따옴표가 필요합니다:

# 잘못됨
message: Error: file not found
url: http://example.com  # 깨질 수 있음

# 올바름
message: "Error: file not found"
url: "http://example.com"

4. 버전 번호 함정

1.0 같은 버전 번호가 부동소수점으로 파싱됩니다:

# 잘못됨
version: 1.0  # 1이 됨 (부동소수점)

# 올바름
version: "1.0"  # 문자열

YAML 검증

배포 전에 항상 YAML을 검증하세요. YAML 구문 오류는 애플리케이션에서 이해하기 어려운 실패를 유발할 수 있습니다. YAML 검증기가 오류의 정확한 줄과 열을 하이라이트하여 즉시 구문을 검사합니다.

YAML과 JSON의 차이에 대한 더 깊은 분석은 YAML vs JSON 비교를 참조하세요.

FAQ

YAML 들여쓰기에 몇 칸을 사용해야 하나요?

2칸이 가장 일반적인 관례로, Kubernetes, Docker Compose, GitHub Actions, 대부분의 DevOps 도구에서 사용됩니다. 일부 프로젝트는 4칸을 사용합니다. 핵심 규칙은 파일 내 일관성입니다 — 들여쓰기 레벨을 절대 혼합하지 마세요.

YAML에 주석을 포함할 수 있나요?

네, YAML은 #으로 한 줄 주석을 지원합니다. 여러 줄 주석 구문은 없습니다. 주석은 파싱 중에 제거되며 로드된 데이터 구조에서 사용할 수 없습니다.