YAML 린팅 모범 사례: 배포 전에 오류 잡기

YAML 파일의 잘못된 공백 하나가 프로덕션 배포를 중단시킬 수 있습니다. 구문 오류 시 크게 실패하는 JSON과 달리, YAML은 잘못된 들여쓰기를 예상치 못한 데이터 구조로 조용히 파싱할 수 있습니다. 린팅은 이러한 문제가 프로덕션에 도달하기 전에 잡아냅니다.

왜 YAML을 린트해야 하나요?

YAML의 유연성은 강점이자 약점입니다:

# 이것은 유효한 YAML이지만 아마 잘못됨
ports:
  - 80
  - 443
  name: webserver  # 이것은 매핑의 키가 아니라 두 번째 목록 항목의 키입니다!

위는 두 번째 항목이 {443: null, name: webserver} 매핑인 목록을 만듭니다. 린터가 이 들여쓰기 문제를 잡아냈을 것입니다. 린팅 없이 이런 종류의 버그는 진단에 수시간이 걸릴 수 있습니다.

yamllint: 표준 린터

yamllint는 가장 널리 사용되는 YAML 린터입니다. 구문 유효성과 스타일 일관성 모두를 검사합니다.

설치

pip install yamllint

기본 사용법

# 단일 파일 린트
yamllint config.yaml

# 디렉토리 린트
yamllint .

# 특정 설정으로 린트
yamllint -c .yamllint.yml .

설정

프로젝트 루트에 .yamllint.yml을 생성하세요:

extends: default

rules:
  line-length:
    max: 120
    level: warning
  indentation:
    spaces: 2
    indent-sequences: true
  truthy:
    allowed-values: ['true', 'false', 'yes', 'no']
  comments:
    require-starting-space: true
    min-spaces-from-content: 2
  document-start: disable
  empty-lines:
    max: 1

주요 규칙 설명

린팅으로 잡히는 일반적인 오류

1. 탭 문자

YAML은 들여쓰기에 탭을 금지하지만 편집기가 때때로 삽입합니다:

# 오류: 탭 문자
server:
port: 8080  # 공백 대신 탭!

2. 일관되지 않은 들여쓰기

# 오류: 2칸과 4칸 들여쓰기 혼용
database:
  host: localhost
    port: 5432  # 잘못됨: 2칸 대신 4칸

3. 중복 키

# 오류: 중복 키 (두 번째가 첫 번째를 조용히 오버라이드)
server:
  port: 8080
  host: localhost
  port: 9090  # 중복! 어떤 포트가 사용되나요?

4. 후행 공백

보이지 않는 후행 공백은 특히 멀티라인 문자열에서 놀라운 동작을 유발할 수 있습니다. 린터가 이를 즉시 플래그합니다.

설치 없이 빠른 검증: YAML 검증기에 YAML을 붙여넣으세요.

CI/CD 통합

GitHub Actions

name: YAML Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint YAML files
        run: yamllint .

Pre-commit 훅

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

pip install pre-commit
pre-commit install

이제 모든 커밋 전에 YAML이 자동으로 린트됩니다.

GitLab CI

yaml-lint:
  image: python:3.12-slim
  script:
    - pip install yamllint
    - yamllint .
  rules:
    - changes:
        - "**/*.yaml"
        - "**/*.yml"

편집기 통합

대부분의 편집기가 실시간 YAML 린팅을 지원합니다:

• VS Code: Red Hat의 "YAML" 확장 설치 (yamllint 사용)
• Vim/Neovim: ALE 또는 coc-yaml 사용
• JetBrains IDE: 구성 가능한 검사가 있는 내장 YAML 지원

YAML 파일에 대해 저장 시 포맷을 활성화하여 공백 문제를 자동으로 수정하세요.

도구별 린팅

범용 YAML 린팅은 구문 오류를 잡지만, 도구별 린터는 시맨틱 정확성을 검증합니다:

Kubernetes

# kubeval - K8s 스키마에 대해 검증
kubeval deployment.yaml

# kubeconform - 더 빠른 대안
kubeconform -strict deployment.yaml

Docker Compose

docker compose config --quiet

GitHub Actions

# actionlint - 워크플로 구문 검증
actionlint .github/workflows/*.yml

Ansible

ansible-lint playbook.yml

YAML 구문 규칙에 대한 더 깊은 이해는 YAML 구문 튜토리얼을 참조하세요.

모범 사례 요약

1. CI에 yamllint 추가 — 모든 YAML 변경이 린팅을 통과해야 함
2. pre-commit 훅 사용 — 저장소에 도달하기 전에 오류 잡기
3. 2칸 들여쓰기로 표준화 — DevOps 관례
4. truthy 규칙 비활성화 또는 제한 — yes/no 불리언 문제는 실제 버그를 유발
5. 합리적인 줄 길이 설정 — 120자가 대부분의 경우를 커버
6. 도구별 검증기 사용 — 범용 린팅 + K8s/Docker/Actions별 검증
7. 편집기 구성 — 실시간 피드백이 CI 실패보다 빠름

FAQ

설정 파일에 YAML을 사용해야 하나요, JSON을 사용해야 하나요?

사람이 편집하는 설정 파일에는 가독성, 주석 지원, 간결한 구문으로 인해 YAML이 선호됩니다. JSON은 기계 생성 데이터와 API 통신에 더 적합합니다. 상세한 비교는 YAML vs JSON 가이드를 참조하세요.

yamllint 경고와 오류를 어떻게 처리하나요?

중요한 규칙 (들여쓰기, 구문)은 CI를 차단하는 오류로 설정하세요. 스타일 규칙 (줄 길이, 주석)은 나타나지만 차단하지 않는 경고로 설정하세요. 이것이 엄격성과 개발자 생산성의 균형을 맞춥니다.

관련 리소스

• YAML 검증기 — 온라인에서 즉시 YAML 구문 검증
• YAML 구문 튜토리얼 — YAML을 처음부터 배우기
• Docker Compose를 위한 YAML — Docker 전용 YAML 패턴