주석과 multi-document 파일

YAML 엔 있는 주석, JSON 엔 없음

YAML 은 # 로 줄 주석을 쓸 수 있어. # 부터 줄 끝까지는 그냥 무시돼. 다만 주석은 데이터 모델에 안 들어가. 그래서 파서 대부분을 거쳐 한 바퀴 돌고 나면 사라져. Python 에서 주석을 꼭 살려야 하면 ruamel.yaml 을 써.

Multi-document 파일

한 파일에 YAML 문서를 여러 개 담을 수 있어. 구분은 한 줄에 혼자 놓은 --- 가 해. 문서 끝을 알리는 ... 도 유효한데 실제로는 잘 안 써. Kubernetes 가 Deployment 와 Service, ConfigMap 을 한 번의 kubectl apply -f 로 보내는 방식이 바로 이 multi-document 파일이야.

Multi-document YAML 읽기

파서 대부분이 스트림이나 반복자 형태의 API 를 따로 열어둬. PyYAML 은 yaml.safe_load_all(text), js-yaml 은 yaml.loadAll(text), yq 는 yq 'select(.kind == "Service")' multi.yaml 이렇게 쓰면 돼.

원칙: 데이터 모양만으로는 전해지지 않는 이유를 주석에 담아. 관련 incident 링크, 이 기본값을 고른 근거, 이 값이 언제쯤 바뀔지 같은 것들. 키가 이미 하고 있는 말을 되풀이하지는 마. port: 8000 옆의 # 서버 포트 는 소음이고, # auth 게이트웨이 때문에 1024 밑으로 유지, RFC-12 참고 는 신호야.

Code

주석·yaml

#  파일 맨 위 주석 — 소유자, 마지막 리뷰 등.
version: 1

#  데이터베이스 설정
database:
  host: localhost
  port: 5432       # PostgreSQL default
  pool_size: 5    # incident 2025-11-04 참고 — 반드시 ≤ 10

Multi-document 파일 (Kubernetes 패턴)·yaml

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  ENV: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
---
apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  ports:
    - port: 80

Python 에서 multi-document YAML 읽기·python

import yaml

with open('manifests.yaml') as f:
    docs = list(yaml.safe_load_all(f))

print(f'Loaded {len(docs)} documents')
for doc in docs:
    if doc is None:
        continue
    print(f'  - kind={doc.get("kind")}, name={doc["metadata"]["name"]}')

yq 로 필터링·bash

# multi-doc 파일에서 Service 문서만:
yq 'select(.kind == "Service")' manifests.yaml

# 문서 개수:
yq -s 'length' manifests.yaml

# 한 문서 교체, 다른 건 유지:
yq '(select(.kind == "Deployment") | .spec.replicas) = 5' manifests.yaml

Exercise

문서가 여럿 든 진짜 Kubernetes manifest 를 골라. Python 에서 yaml.safe_load_all 로 읽고 문서가 몇 개인지 세봐. 그중 하나를 코드로 고치고 (replica 수를 바꿔) safe_dump_all 로 다시 써. 전후를 diff 해보면 주석이 사라진 게 보일 거야. 이제 ruamel.yaml 로 똑같이 해봐. 그 두 diff 의 차이가 ruamel 을 쓰는 이유야.

YAML 엔 있는 주석, JSON 엔 없음

Multi-document 파일

Multi-document YAML 읽기

Code

External links

Exercise

Progress

댓글 0