주석과 multi-document 파일

YAML 엔 있는 주석, JSON 엔 없음

YAML 이 줄 주석에 # 지원. # 부터 줄 끝까지 무시. 주석은 데이터 모델 부분 아님 — 대부분 파서로 라운드트립 시 잃음. (Python 에서 주석 보존 중요하면 ruamel.yaml 사용.)

Multi-document 파일

한 파일에 여러 YAML 문서 가능, 자체 줄의 --- 로 구분. 문서 끝 마커 ... 는 드물지만 유효. multi-document 파일이 Kubernetes 가 Deployment + Service + ConfigMap 을 한 kubectl apply -f 타깃으로 보내는 방법.

Multi-document YAML 읽기

대부분 파서가 stream/iterator 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 count 변경) 후 safe_dump_all 로 다시 쓰기. before/after diff — 주석 사라진 거 확인. 이제 ruamel.yaml 로 재시도. diff 가 ruamel 의 case.

주석과 multi-document 파일

YAML 엔 있는 주석, JSON 엔 없음

Multi-document 파일

Multi-document YAML 읽기

Code

External links

Exercise

Progress

댓글 0