YAML 검증 도구 추천과 활용법 - 설정 파일 오류 빠르게 잡는 방법
들여쓰기 하나로 서버가 멈춘 경험이 있다면 필독. YAML 검증 도구를 활용해 배포 전 오류를 사전에 차단하는 실전 방법을 정리했습니다.
Docker Compose 파일을 수정하고 배포했는데 컨테이너가 올라오지 않습니다. 로그를 뒤져보니 원인은 들여쓰기 한 칸 차이. YAML을 다루는 개발자라면 한 번쯤 겪어본 상황입니다. 공백 하나, 탭 하나에 전체 서비스가 멈출 수 있는 것이 YAML의 특성이죠. 이런 사고를 막으려면 YAML 검증 도구를 작업 흐름에 포함시키는 것이 가장 확실한 방법입니다.
YAML 파일에서 오류가 자주 발생하는 이유
YAML은 JSON이나 XML과 달리 들여쓰기로 구조를 표현합니다. 사람이 읽기에는 편하지만, 작성할 때는 실수가 잦습니다. Stack Overflow의 2024년 개발자 설문에 따르면 설정 파일 관련 오류의 약 38%가 YAML 문법 문제에서 비롯된다고 합니다.
- 탭과 스페이스 혼용 - YAML 명세는 탭 문자를 허용하지 않습니다. 에디터 설정에 따라 탭이 섞이면 파싱 에러가 발생합니다.
- 잘못된 들여쓰기 깊이 - 상위 키 대비 하위 키의 들여쓰기가 일관되지 않으면 구조 자체가 깨집니다.
- 특수문자 미이스케이프 - 콜론(:), 앰퍼샌드(&), 별표(*) 등을 따옴표 없이 값에 넣으면 파서가 오해합니다.
- 불리언 자동 변환 - yes, no, on, off 같은 문자열이 의도치 않게 불리언으로 해석됩니다. 노르웨이 국가코드 NO가 false로 바뀌는 유명한 사례가 있습니다.
YAML 오류의 80% 이상은 문법(syntax) 단계에서 발생합니다. 검증 도구 하나만 추가해도 배포 장애의 상당수를 예방할 수 있습니다.
온라인 YAML 검증 도구 비교
별도 설치 없이 브라우저에서 바로 쓸 수 있는 YAML 검증 도구는 빠른 확인에 적합합니다. 대표적인 서비스 4가지를 비교했습니다.
| 도구 | 주요 기능 | JSON 변환 | 에러 위치 표시 | 비용 |
|---|---|---|---|---|
| YAML Lint (yamllint.com) | 문법 검증, 포맷팅 | 지원 | 줄 번호 표시 | 무료 |
| Code Beautify YAML Validator | 검증, 미니파이, 트리뷰 | 지원 | 줄 번호 + 하이라이트 | 무료 |
| JSON Formatter YAML 탭 | 검증, JSON 양방향 변환 | 지원 | 줄 번호 표시 | 무료 |
| Better YAML (onlineyamltools.com) | 검증, 정렬, 키 추출 | 지원 | 상세 메시지 | 무료 |
간단한 Kubernetes 매니페스트나 docker-compose.yml을 수정한 뒤 붙여넣기로 빠르게 확인하기에 좋습니다. 다만 민감한 설정 파일(API 키, DB 비밀번호 포함)은 온라인 도구에 직접 붙여넣지 않는 것이 안전합니다.
CLI 기반 YAML 검증 도구
로컬 환경에서 반복적으로 검증해야 한다면 CLI 도구가 효율적입니다. 터미널에서 바로 실행할 수 있고, 스크립트나 Git Hook에 연동하기도 쉽습니다.
yamllint (Python)
가장 널리 쓰이는 YAML 린터입니다. 문법 오류뿐 아니라 스타일 규칙까지 검사합니다.
- 설치: pip install yamllint
- 사용: yamllint config.yml
- 설정 파일(.yamllint)로 규칙 커스터마이징 가능
- 들여쓰기 크기, 줄 길이 제한, 주석 규칙 등 세밀한 제어
yq (Go)
YAML을 파싱하고 쿼리하는 도구입니다. 검증 자체보다는 값 추출과 변환에 강점이 있지만, 파싱 과정에서 문법 오류를 자동으로 잡아줍니다.
- 설치: brew install yq 또는 바이너리 다운로드
- 사용: yq eval '.' config.yml
- 파이프라인에서 YAML 값을 동적으로 수정할 때 유용
kube-score / kubeval
Kubernetes YAML을 다룬다면 문법 검증에 더해 스키마 검증이 필요합니다. kubeval은 공식 K8s JSON 스키마와 대조해 apiVersion, kind, 필수 필드 누락 여부를 확인합니다.
IDE 플러그인으로 실시간 검증하기
가장 이상적인 방법은 코드를 작성하는 시점에 오류를 바로 확인하는 것입니다. 주요 IDE별 YAML 검증 플러그인을 정리했습니다.
| IDE | 플러그인 | 주요 기능 |
|---|---|---|
| VS Code | YAML (Red Hat) | 자동 완성, 스키마 검증, 에러 하이라이트 |
| JetBrains (IntelliJ 등) | 기본 내장 | 문법 검사, 스키마 매핑, 리팩토링 |
| Vim/Neovim | ale + yamllint | 저장 시 자동 린트, quickfix 연동 |
| Sublime Text | SublimeLinter-contrib-yamllint | 인라인 에러 표시 |
VS Code의 Red Hat YAML 확장은 월간 다운로드 수가 2,500만 건을 넘을 정도로 사실상 표준입니다. JSON 스키마를 연결하면 키 자동 완성까지 지원되어 오타를 원천적으로 줄일 수 있습니다. 설정 방법은 settings.json에 yaml.schemas 항목을 추가하는 것만으로 충분합니다.
YAML 작성 시 흔한 실수와 해결법
YAML 검증 도구를 쓰더라도 반복적으로 발생하는 실수 패턴을 알아두면 작성 단계에서 오류를 줄일 수 있습니다.
1. 문자열에 콜론 포함
잘못된 예: message: 시간: 오후 3시
올바른 예: message: "시간: 오후 3시"
콜론 뒤에 공백이 오면 YAML은 이를 키-값 구분자로 인식합니다. 따옴표로 감싸야 합니다.
2. 앵커(&)와 별칭(*) 오용
앵커를 정의하지 않고 별칭을 참조하면 파서가 에러를 냅니다. 대규모 설정에서는 앵커 이름을 명확하게 짓고, 정의 위치를 파일 상단에 모아두는 것이 관리에 유리합니다.
3. 멀티라인 문자열 표기 혼동
- | (리터럴 블록) - 줄바꿈을 그대로 유지합니다.
- > (폴디드 블록) - 줄바꿈을 공백으로 치환합니다.
- 용도에 맞지 않는 표기를 쓰면 의도와 다른 값이 들어갑니다.
4. 빈 값 처리
키만 쓰고 값을 비워두면 null로 해석됩니다. 빈 문자열을 의도했다면 key: ""로 명시해야 합니다.
CI/CD 파이프라인에 YAML 검증 통합하기
수동 검증만으로는 실수를 완전히 막을 수 없습니다. CI/CD 파이프라인에 YAML 검증 단계를 추가하면 잘못된 설정이 배포되는 것을 자동으로 차단할 수 있습니다.
GitHub Actions 예시
워크플로우 파일에 yamllint 단계를 추가하면 PR마다 자동 검증이 이루어집니다. 아래와 같은 구성이 일반적입니다.
- Step 1: 체크아웃
- Step 2: pip install yamllint
- Step 3: yamllint -d "{extends: default, rules: {line-length: {max: 150}}}" ./config/
이렇게 하면 config 디렉토리 내 모든 YAML 파일을 검사하고, 오류가 있으면 PR 머지가 차단됩니다. GitLab CI나 Jenkins에서도 동일한 방식으로 적용할 수 있습니다.
Git pre-commit Hook 활용
커밋 전에 로컬에서 먼저 검증하고 싶다면 pre-commit 프레임워크를 활용하세요. .pre-commit-config.yaml에 yamllint 훅을 등록하면 커밋할 때마다 자동으로 검사가 실행됩니다. 원격 CI까지 가기 전에 오류를 잡아주므로 피드백 루프가 짧아집니다.
개발 환경에서 다양한 온라인 도구를 병행하면 생산성이 올라갑니다. 예를 들어 건강 관련 데이터를 다루는 서비스를 개발할 때는 BMI 계산기 같은 레퍼런스 도구를 참고해 입력값 검증 로직을 설계하기도 합니다.
정리하면, YAML 검증은 도구 선택보다 습관화가 핵심입니다. 지금 당장 할 수 있는 두 가지를 권합니다. 첫째, 사용 중인 IDE에 YAML 플러그인이 설치되어 있는지 확인하세요. 둘째, 프로젝트의 CI 파이프라인에 yamllint 단계가 없다면 오늘 추가하세요. 이 두 가지만으로도 YAML로 인한 배포 장애를 크게 줄일 수 있습니다.
