kubectl diff --server-side, 이거 모르는 분 꽤 많더라

오늘 알게 된 건데, kubectl diff에 --server-side 플래그가 있다. 그냥 kubectl diff -f app.yaml 만 써왔던 사람 손! (나도 어제까지 그랬다.)

일반 kubectl diff는 클라이언트 사이드 dry-run 결과를 보여준다. 그래서 SSA(Server-Side Apply)로 관리되는 클러스터에서는 실제 apply했을 때 나오는 결과와 미묘하게 달라지는 경우가 있다. 특히 다른 컨트롤러가 소유하고 있는 필드를 건드릴 때 그렇다.

뭐가 다른가

같은 매니페스트를 두 방식으로 diff 걸어보면 이렇게 나온다.

# 기존 방식 — 클라이언트 dry-run
kubectl diff -f deploy.yaml

# 서버사이드 dry-run — SSA 필드 소유권까지 반영
kubectl diff -f deploy.yaml --server-side --field-manager=me

두 번째 명령은 API 서버가 실제로 SSA를 dry-run으로 돌린 결과를 반환한다. 그래서 만약 HPA가 소유하고 있는 spec.replicas 를 내가 매니페스트에 박아넣었다면, 여기서 conflict가 미리 잡힌다. 실제 apply 하기 전에.

언제 유용한가

우리 팀에서는 GitOps로 ArgoCD가 SSA 모드로 apply하는 구조인데, 로컬에서 매니페스트 수정한 뒤 PR 올리기 전에 이 명령으로 한 번 확인한다. Argo가 실제로 sync 돌렸을 때 어떤 필드가 바뀌는지, 다른 매니저(HPA, VPA, keda operator 등)와 충돌은 없는지 미리 볼 수 있다.

특히 이런 상황에서 진가를 발휘한다.

• Deployment의 replicas를 HPA에게 넘겼는데 매니페스트에 아직 값이 남아있을 때
• StatefulSet의 volumeClaimTemplates를 손댔는데 다른 오퍼레이터가 라벨을 붙여놨을 때
• 여러 팀이 같은 리소스의 다른 필드를 소유하는 상황

Client-side diff는 이런 걸 못 잡는다. 그냥 "너 이거 바꾸려는 것 같다"만 보여준다. Server-side는 "너 이거 바꾸려는데 저 매니저랑 싸운다"까지 알려준다.

주의할 점

--field-manager 인자를 안 넣으면 기본값이 kubectl이 된다. CI에서 돌릴 때는 실제 apply할 때 쓰는 field manager 이름을 넣어줘야 결과가 정확하다. ArgoCD면 argocd-controller, Flux면 flux-client-side-apply 이런 식으로.

그리고 SSA 자체는 Kubernetes 1.22부터 stable이라 요즘 클러스터라면 걱정 없이 쓸 수 있다. 1.34에서도 동작 동일하다.

마무리

한 줄짜리 플래그인데 CI 파이프라인에 넣어두면 배포 사고 하나쯤은 막아준다. 다들 한 번 써보시길.

혹시 다른 SSA 관련 팁 있으신 분 계시면 댓글 달아주세요.