YAML 검증기 — 배포를 망치기 전에 YAML 오류 잡기

유효성 검사를 먼저 하도록 가르쳐준 배포 실패

금요일 오후였습니다 — 이런 일이 일어나기 최악의 시간입니다. Kubernetes 배포가 이틀 동안 리뷰 중이었고, 최종 승인이 나온 후 kubectl apply 명령이 모든 것을 멈추는 오류를 뱉었습니다:

error: error parsing deployment.yaml: error converting YAML to JSON: yaml: line 34: mapping values are not allowed in this context

34번 줄. 200줄짜리 매니페스트에서. 문제는 다음 코드였습니다:

env:
  - name: DATABASE_URL
    value: postgres://user:password@host:5432/db

괜찮아 보이죠? 틀렸습니다. 값 문자열의 콜론 — user:password — 이 YAML 매핑 문법으로 부분적으로 해석되고 있었습니다. 수정은 간단했습니다:

env:
  - name: DATABASE_URL
    value: "postgres://user:password@host:5432/db"

따옴표 한 쌍. 30분의 디버깅. 교훈: 중요한 것에 닿기 전에 YAML을 검증하세요.

---

YAML이 실제로 까다로운 이유

YAML은 평판 문제가 있습니다. 단순해 보입니다 — 괄호도 없고, 중괄호도 없고, 단지 들여쓰기된 키-값 쌍만 있습니다. 그 단순함은 실제이지만, 숨겨진 대가가 있습니다: YAML의 규칙은 엣지 케이스에서 특히 예상외로 복잡합니다.

공백이 문법입니다. 대부분의 언어에서 공백은 장식적입니다. YAML에서 키 앞의 공백 수는 문서 트리에서 그 위치를 정의합니다. 공백 2개는 한 수준의 중첩을 의미하고, 4개는 두 수준을 의미합니다. 잘못되면 파서가 오류를 발생시키거나 의도와 다른 구조를 조용히 만듭니다.

절대 탭 사용하지 않기. 이것은 사람들을 계속 실망시킵니다. 편집기가 Tab 키를 누를 때 탭을 삽입할 수도 있고, 탭을 사용한 블로그 포스트에서 YAML을 붙여넣을 수도 있습니다. YAML 파서는 들여쓰기에 사용된 탭을 found character that cannot start any token과 같은 오류로 거부합니다.

유형 추론이 적극적입니다. YAML은 유형을 추측하여 도우려고 합니다. 이것은 유명한 함정을 만듭니다:

# 이것들은 YAML 1.1에서 문자열이 아닙니다 (대부분의 도구가 사용하는 버전)
version: 1.0      # 문자열이 아닌 부동소수점
enabled: yes      # 문자열 "yes"가 아닌 불리언 true
id: 08            # 8진수 8... 또는 파싱 오류
country: NO       # 불리언 false (노르웨이의 ISO 코드!)

이것들을 문자열로 만들려면 따옴표로 묶어야 합니다. 항상.

여러 줄 문자열은 직관적이지 않습니다. YAML에는 두 가지 여러 줄 스칼라 스타일이 있습니다 — 리터럴 블록(|)과 폴드 블록(>). 리터럴은 줄 바꿈을 보존하고, 폴드는 단일 줄 바꿈을 공백으로 변환합니다.

---

가장 흔한 YAML 오류 (예시 포함)

1. 콜론이 포함된 따옴표 없는 문자열

# 잘못됨 — 콜론이 암시적 매핑을 만듦
message: Error: connection refused

# 올바름
message: "Error: connection refused"

2. 공백 대신 탭

# 잘못됨 (name 앞에 탭)
server:
	name: prod-01   # 탭 문자 — 오류 발생

# 올바름 (공백)
server:
  name: prod-01

3. 일관성 없는 들여쓰기

# 잘못됨 — "port"는 4칸 들여쓰기, "host"는 2칸 사용
database:
  host: localhost
    port: 5432    # 잘못됨 — "port"가 "host"의 자식이 됨

# 올바름
database:
  host: localhost
  port: 5432

4. 따옴표 없는 특수 문자

# 잘못됨 — #이 주석을 시작하여 "value"가 사라짐
description: 이것은 중요합니다 # 여기는 주석이 아님

# 실제로 괜찮음 — 인라인 주석은 유효한 YAML이지만 #을 값에 넣으려면:
description: "이것은 중요합니다 # 문자열의 일부"

5. 중복 키

# 잘못됨 — 두 번째 "host"가 대부분의 파서에서 첫 번째를 조용히 덮어씁니다
database:
  host: localhost
  port: 5432
  host: prod.example.com   # 중복 — 나쁨

6. 잘못된 불리언 및 null 값

# YAML 1.1에서 이것들은 모두 불리언 true입니다:
enabled: true
enabled: yes
enabled: on

# 이것들은 모두 null입니다:
value: ~
value: null

# 문자열 "yes"나 "null"을 원한다면 따옴표로 묶으세요:
status: "yes"
type: "null"

7. 앵커/별칭 실수

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults    # 병합 키 — 유효하지만 혼란스러움
  timeout: 60      # 앵커 값을 덮어씁니다

staging:
  <<: *defaults
  timeout: 15

앵커와 별칭은 DRY 설정에 강력하지만, 앵커에 버그가 있으면 별칭이 사용된 모든 곳에 전파됩니다.

---

YAML 검증기 사용 방법

toolboxhubs.com의 YAML 검증기는 오류를 파이프라인에 도달하기 전에 잡는 워크플로우를 위해 설계되었습니다.

1단계 — YAML 붙여넣기. 설정 파일의 전체 내용을 복사하여 입력 패널에 붙여넣습니다.

2단계 — 검증 실행. 검증기가 YAML을 즉시 파싱하고 발견된 첫 번째 구문 오류를 줄 번호와 함께 보고합니다. 수정하고 다시 실행하세요.

3단계 — 파싱된 출력 검토. 오류를 잡는 것 외에도, 검증기는 파싱된 구조를 트리로 보여줍니다. 여기서 논리적 오류를 잡을 수 있습니다 — 키가 문법적으로 올바른 위치에 있지만 잘못된 중첩 수준에 있을 수 있습니다.

4단계 — 유형 확인. 문자열이 문자열로, 불리언이 불리언으로, 숫자가 숫자로 표시되는지 주의하세요. version: 3.8이 문자열 대신 부동소수점으로 파싱되고 있다면, 다운스트림 문제를 일으키기 전에 여기서 볼 수 있습니다.

형식 간에 변환이 필요하다면, JSON to YAML 변환기가 두 형식 간의 왕복을 처리하고, JSON 포매터는 같은 프로젝트에서 두 형식을 모두 다룰 때 유용합니다.

---

YAML 대 JSON — 언제 무엇을 선택해야 하는가

YAML을 사용해야 할 때:

• 사람이 파일을 자주 편집할 때 (CI 설정, Kubernetes 매니페스트, Ansible 플레이북)
• 주석이 중요할 때 — YAML은 # 주석을 지원하고 JSON은 그렇지 않습니다
• 중첩 구조에서 시각적 노이즈를 줄이고 싶을 때

JSON을 사용해야 할 때:

• 파일이 코드에 의해 생성되고 코드로 읽힐 때 — 사람이 거의 건드리지 않을 때
• 엄격한 유형 보장이 필요할 때 (yes/no 모호성 없음)
• API가 JSON을 기대할 때
• 가장 단순한 도구를 원할 때 — 모든 언어에 JSON 파서가 있습니다

---

특정 도구에서의 YAML

GitHub Actions

GitHub Actions 워크플로우는 YAML이며 표준 YAML을 넘어서는 몇 가지 특이점이 있습니다:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 테스트 실행
        run: npm test
        env:
          NODE_ENV: test
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

${{ }} 표현식 문법은 YAML 문법이 아닙니다 — Actions에 의해 YAML 파싱 전에 평가됩니다.

Docker Compose

services:
  app:
    image: node:20-alpine
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    volumes:
      - ./src:/app/src:ro

"3000:3000"이 따옴표로 묶인 것에 주목하세요 — 콜론 때문에 필요합니다.

Kubernetes 매니페스트

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-app:latest
          ports:
            - containerPort: 8080

spec.template.spec 이중 중첩은 자주 혼란을 줍니다. 내부 spec는 Pod 사양이고 외부는 Deployment 사양입니다.

---

오류 없이 YAML을 작성하는 팁

1. 검증기뿐 아니라 린터를 사용하세요. 검증기는 YAML이 구문적으로 유효한지 알려줍니다. yamllint 같은 린터는 일관된 들여쓰기, 후행 공백, 줄 길이 및 미래 버그를 방지하는 다른 스타일 규칙도 적용합니다.

2. 편집기를 올바르게 설정하세요. .yml 및 .yaml 파일에 탭이 아닌 공백을 사용하도록 편집기를 설정하고 2칸 들여쓰기를 사용하세요. VS Code의 YAML 확장(Red Hat 제공)은 즉시 유효성 검사를 하고 Kubernetes, GitHub Actions, Docker Compose 파일을 자동으로 스키마 검증합니다.

3. 방어적으로 문자열을 따옴표로 묶으세요. 문자열 값이 :, #, {, }, [, ], *, &, !를 포함하면 따옴표로 묶으세요. 불리언이나 null로 잘못 해석될 수 있다면 따옴표로 묶으세요.

4. 푸시 전에 검증하세요. pre-commit 훅에 YAML 검증을 추가하세요:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [-d, relaxed]

5. 노르웨이 문제를 운영환경에서 주의하세요. 2글자 국가 코드, 요일 약어, 월 약어를 일반 YAML 스칼라로 저장하는 설정은 YAML 1.1에서 조용히 false로 변환될 위험이 있습니다. 무조건 따옴표로 묶으세요.

6. 파서의 YAML 버전을 확인하세요. Python의 PyYAML은 기본적으로 1.1을 사용합니다(yes/no/on/off가 불리언인 문제 있는 버전). Go의 gopkg.in/yaml.v3는 1.2를 구현합니다. JavaScript의 js-yaml도 기본적으로 1.2를 사용합니다.

---

결론

YAML은 현대 인프라 도구의 주요 설정 언어입니다 — Kubernetes, GitHub Actions, Docker Compose, Ansible, 그리고 대부분의 CI/CD 시스템이 YAML을 기반으로 구축되어 있습니다. 그것이 YAML의 실패 원인을 아는 것이 학문적으로 흥미로운 것이 아니라 실질적으로 중요한 이유입니다.

실용적인 워크플로우는 간단합니다: 특히 배포 파이프라인에 닿는 것에는 푸시 전에 YAML 검증기에 설정을 붙여넣으세요. 10초면 충분하고 금요일 오후 200줄짜리 매니페스트에서 알 수 없는 줄 번호를 쫓아다니게 하는 오류 클래스를 잡아줍니다.

형식 간에 설정을 변환하고 있다면, JSON to YAML이 변환을 깔끔하게 처리하고, JSON 포매터는 방정식의 JSON 쪽을 검증하는 데 유용합니다. 먼저 검증하는 습관을 들이세요 — 미래의 자신이 고마워할 것입니다.