kubectl -o kyaml, 이거 모르는 분 꽤 많더라

오늘 알게 된 건데, 요즘 팀 내부에서 kubectl get -o yaml로 뽑은 매니페스트를 그대로 GitOps 저장소에 붙여넣는 걸 좀 조심하자는 얘기가 나왔다. 이유는 뻔한데, YAML의 그 유명한 "노르웨이 문제(no가 false로 파싱되는 그거)"랑 문자열 따옴표 누락 때문이다. 근데 나만 몰랐던 게, 이걸 상당 부분 해결해주는 kyaml 출력 포맷이 이미 kubectl에 들어와 있었다.

KYAML이 뭔데

Kubernetes 1.34에서 alpha로 들어온 YAML의 엄격한 서브셋(dialect)이다. 큰 특징 세 가지만 기억하면 된다.

• 모든 문자열은 큰따옴표로 강제 인용된다. no, yes, on, off 같은 값이 실수로 boolean으로 캐스팅되지 않는다.
• 리스트/맵은 flow 스타일([], {})을 명시적으로 사용한다. 들여쓰기 실수로 스코프가 바뀌는 사고를 원천 차단한다.
• 기존 YAML 파서들이 그대로 읽을 수 있다. 별도 파서 없이도 되기 때문에 도입 부담이 거의 없다.

1.34에서는 alpha라서 환경변수로 켜야 하고, 1.35부터는 beta로 승격돼서 별도 opt-in 없이 -o kyaml만 붙이면 된다. 우리 팀은 아직 1.33 클러스터가 절반이라 조금 더 기다렸다가 굴리기로 했다.

써보기

1.34 이상 kubectl에서 이렇게 켠다.

export KUBECTL_KYAML=true
kubectl get deployment my-app -o kyaml

출력이 대충 이런 식이다.

apiVersion: "apps/v1"
kind: "Deployment"
metadata: {
  name: "my-app",
  namespace: "prod",
  labels: {
    app: "my-app",
    version: "v2",
  },
}
spec: {
  replicas: 3,
  selector: {
    matchLabels: {app: "my-app"},
  },
}

처음 보면 좀 못생겼다고 느낄 수 있는데, diff 뜰 때 훨씬 안정적이라는 게 실제 장점이다. 특히 helm template 결과랑 kubectl get 결과를 서로 비교할 때, 기존 YAML은 따옴표 유무나 flow/block 스타일 때문에 의미 없는 diff가 잔뜩 생겼는데 kyaml로 통일하면 그게 사라진다.

어디에 쓰면 좋을까

내 기준으로는 세 군데다.

• GitOps 저장소에 배포 스냅샷을 적재할 때. 오퍼레이터가 필드를 채워넣고 나서 그걸 다시 저장할 때 특히 유용하다.
• 매니페스트 리뷰할 때. PR에서 문자열 인용 실수를 잡기 편하다.
• kubectl diff 스크립트에 넣을 때. 파이프라인에서 clean diff를 뽑아야 하는 경우 노이즈가 확 줄어든다.

반대로 사람이 직접 손으로 쓰는 매니페스트에는 굳이 kyaml을 쓸 이유가 없다. 예쁜 block 스타일 YAML이 더 읽기 편하다. 이건 어디까지나 "기계가 뽑아주는 YAML"을 안전하게 만들기 위한 옵션이다.

참고

kubectl 1.34 이상에서만 동작하고, 클러스터 버전은 상관없다. CI 러너에 이 버전 이상이 있는지만 확인하면 된다. 우리 팀 러너 이미지에는 아직 1.33이 박혀 있어서 러너 이미지부터 올려야 한다는 게 함정.

혹시 이미 프로덕션 파이프라인에 kyaml 붙여서 굴리시는 분 있으면 후기 댓글로 좁 남겨주세요. 특히 kubectl diff 결과가 실제로 얼마나 깔끔해지는지 궁금하다.

---

태그: kubernetes, kubectl, KYAML, GitOps, YAML, k8s-1.34