We Ignored the Constant OutOfSync, and Real Drift Vanished Too

한국어 원문으로 표시합니다.

목표

argocd-cm 과 Application 두 자리의 무시 규칙을 직접 쓰고, 규칙이 실제로 어떤 줄을 비교에서 빼는지 CLI 의 diff 로 확인한다. 너무 넓게 무시했을 때 무엇이 함께 사라지는지 눈으로 본다.

왜 중요한가

자동 동기화를 켜면 곧 '늘 OutOfSync' 를 만난다. HPA 가 바꾼 replicas, 웹훅이 끼워 넣은 사이드카, 컨트롤러가 붙인 주석처럼 저장소에 적을 수 없는데 클러스터에는 반드시 생기는 것들 때문이다. 무시 규칙은 이것을 다루는 도구인데, 여기에는 한쪽으로만 기우는 힘이 있다 — 넓게 무시하면 화면이 조용해지고, 좁게 무시하면 계속 시끄럽다. 그래서 누구나 넓은 쪽으로 간다. 넓은 규칙의 대가는 당장 보이지 않는다. 몇 달 뒤 누가 손으로 이미지를 바꿔도 아무도 모르는 날에야 드러난다. 규칙을 짐작으로 쓰지 않고 '이 규칙이 지우는 줄' 을 눈으로 확인하고 커밋하는 습관이 이 대가를 막는다.

단계

/root/ga-ignore/live.yaml 에 ga-ignore 네임스페이스의 Deployment web 을 만드세요 — spec.replicas 는 4, 컨테이너는 app(이미지 nginx:1.25)과 sidecar(이미지 envoy:1.31) 두 개, metadata.annotations 에 deployment.kubernetes.io/revision: "7" 를 둡니다. /root/ga-ignore/argocd-cm.yaml 은 data: {} 인 빈 ConfigMap 입니다. argocd admin settings resource-overrides ignore-differences /root/ga-ignore/live.yaml --argocd-cm-path /root/ga-ignore/argocd-cm.yaml 의 출력을 /root/ga-ignore/none.txt 에 저장하세요.
/root/ga-ignore/argocd-cm-pointer.yaml 에 키 resource.customizations.ignoreDifferences.apps_Deployment 를 두고 jsonPointers 로 /spec/replicas 하나만 무시하게 하세요. /root/ga-ignore/live.yaml 에 대한 출력을 /root/ga-ignore/pointer.txt 에 저장하세요.
/root/ga-ignore/argocd-cm-jq.yaml 에 jqPathExpressions 하나로 이름이 sidecar 인 컨테이너의 image 만 무시하게 하세요. 출력을 /root/ga-ignore/jq.txt 에 저장합니다. app 컨테이너의 이미지는 빠지면 안 됩니다.
/root/ga-ignore/argocd-cm-both.yaml 하나에 jsonPointers(/spec/replicas)와 jqPathExpressions(sidecar 이미지)를 함께 두고, 출력을 /root/ga-ignore/both.txt 에 저장하세요. 두 가지가 모두 빠지고 app 컨테이너의 이미지는 남아야 합니다.
/root/ga-ignore/argocd-cm-wide.yaml 에 jsonPointers 로 /spec 통째로를 무시하게 하고 출력을 /root/ga-ignore/wide.txt 에 저장하세요. 이 출력에는 컨테이너 이미지 줄까지 들어 있습니다 — 즉 누가 이미지를 몰래 바꿔도 비교에 걸리지 않는다는 뜻입니다.
/root/ga-ignore/argocd-cm-mfm.yaml 에 managedFieldsManagers 로 kubectl 하나만 두고 출력을 /root/ga-ignore/mfm-only.txt 에 저장하세요. 이어서 /root/ga-ignore/argocd-cm-mfm2.yaml 에 같은 managedFieldsManagers 와 jsonPointers(/metadata/annotations)를 함께 두고 출력을 /root/ga-ignore/mfm-plus.txt 에 저장하세요. 두 출력이 어떻게 다른지 보세요.
/root/ga-ignore/argocd-cm-updates.yaml 한 장에 키 두 개를 두세요 — resource.customizations.ignoreDifferences.apps_Deployment 는 jsonPointers 로 /spec/replicas 를, resource.customizations.ignoreResourceUpdates.apps_Deployment 는 jsonPointers 로 /metadata/annotations 를 무시합니다. 같은 파일에 대해 ignore-differences 출력을 /root/ga-ignore/updates-diff.txt 에, ignore-resource-updates 출력을 /root/ga-ignore/updates-upd.txt 에 저장하세요.
/root/ga-ignore/application.yaml 에 Application ga-ignore-web(네임스페이스 argocd, 프로젝트 default)을 만들어 kwok 클러스터에 적용하세요. spec.ignoreDifferences 에 group apps, kind Deployment 인 항목 하나를 두고 그 안에 /spec/replicas 포인터와 sidecar 이미지를 고르는 jq 식을 함께 넣습니다. 그리고 /root/ga-ignore/ignore-matrix.tsv 에 <ConfigMap파일>\t<찾을 글자>\t<yes|no> 네 줄 이상을 적고, /root/ga-ignore/check-ignore.sh 로 전부 검사해 출력을 /root/ga-ignore/ignore-result.txt 에 저장하세요. 스크립트는 표준출력에만 쓰고 한 줄이라도 틀리면 0 이 아닌 코드로 끝나야 합니다.

참고

키 이름은 resource.customizations.ignoreDifferences.<그룹>_<종류> 이고 구분자는 밑줄입니다.
출력에서 < 로 시작하는 줄이 비교에서 빠지는 줄입니다.
배열 원소를 조건으로 고르려면 jqPathExpressions 를 씁니다. JSON 포인터는 자리 번호만 가리킵니다.
흔한 실수: 한 종류에 규칙 블록을 두 번 적는다 — 키가 겹쳐 뒤엣것만 남습니다.
흔한 실수: OutOfSync 를 없애려고 /spec 을 통째로 무시한다.
참고: https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/

규칙이 없을 때의 출력부터 본다

/root/ga-ignore/live.yaml 에 ga-ignore 네임스페이스의 Deployment web 을 만드세요 — spec.replicas 는 4, 컨테이너는 app(이미지 nginx:1.25)과 sidecar(이미지 envoy:1.31) 두 개, metadata.annotations 에 deployment.kubernetes.io/revision: "7" 를 둡니다. /root/ga-ignore/argocd-cm.yaml 은 data: {} 인 빈 ConfigMap 입니다. argocd admin settings resource-overrides ignore-differences /root/ga-ignore/live.yaml --argocd-cm-path /root/ga-ignore/argocd-cm.yaml 의 출력을 /root/ga-ignore/none.txt 에 저장하세요.

규칙이 하나도 없으면 이 명령은 판정을 지어내지 않고 '설정돼 있지 않다' 고 말합니다. 뒤 단계들이 이 파일 하나를 계속 재료로 쓰니 값을 정확히 맞춰 두세요.

필드 하나를 가리켜 빼낸다

/root/ga-ignore/argocd-cm-pointer.yaml 에 키 resource.customizations.ignoreDifferences.apps_Deployment 를 두고 jsonPointers 로 /spec/replicas 하나만 무시하게 하세요. /root/ga-ignore/live.yaml 에 대한 출력을 /root/ga-ignore/pointer.txt 에 저장하세요.

JSON 포인터는 슬래시로 내려가는 경로입니다. 출력의 < 로 시작하는 줄이 '비교에서 빠지는 줄' 입니다 — replicas 한 줄만 빠지고 컨테이너 이미지는 그대로 남아야 합니다.

배열에서 조건으로 고르는 것은 jq 만 된다

/root/ga-ignore/argocd-cm-jq.yaml 에 jqPathExpressions 하나로 이름이 sidecar 인 컨테이너의 image 만 무시하게 하세요. 출력을 /root/ga-ignore/jq.txt 에 저장합니다. app 컨테이너의 이미지는 빠지면 안 됩니다.

JSON 포인터는 배열을 자리 번호로만 가리킬 수 있어서, 순서가 바뀌면 엉뚱한 원소를 무시하게 됩니다. jq 식이면 select(.name == "sidecar") 처럼 조건으로 고를 수 있습니다. 표현식은 .spec.template.spec.containers[] 에서 시작하세요.

두 방식을 한 규칙에 함께 쓴다

/root/ga-ignore/argocd-cm-both.yaml 하나에 jsonPointers(/spec/replicas)와 jqPathExpressions(sidecar 이미지)를 함께 두고, 출력을 /root/ga-ignore/both.txt 에 저장하세요. 두 가지가 모두 빠지고 app 컨테이너의 이미지는 남아야 합니다.

한 종류에 대한 규칙 블록은 하나이고, 그 안에 두 목록이 나란히 들어갑니다. 규칙을 종류마다 여러 블록으로 쪼개려 하면 키가 겹쳐 뒤엣것만 남습니다.

너무 넓게 무시하면 드리프트가 영영 안 보인다

/root/ga-ignore/argocd-cm-wide.yaml 에 jsonPointers 로 /spec 통째로를 무시하게 하고 출력을 /root/ga-ignore/wide.txt 에 저장하세요. 이 출력에는 컨테이너 이미지 줄까지 들어 있습니다 — 즉 누가 이미지를 몰래 바꿔도 비교에 걸리지 않는다는 뜻입니다.

OutOfSync 를 없애는 가장 빠른 방법은 넓게 무시하는 것이고, 그래서 현장에서 제일 자주 저지르는 실수이기도 합니다. 4단계 출력과 이 출력에서 nginx 라는 글자가 보이는지를 견줘 보세요.

관리자 이름으로 무시하는 규칙은 미리보기가 안 된다

/root/ga-ignore/argocd-cm-mfm.yaml 에 managedFieldsManagers 로 kubectl 하나만 두고 출력을 /root/ga-ignore/mfm-only.txt 에 저장하세요. 이어서 /root/ga-ignore/argocd-cm-mfm2.yaml 에 같은 managedFieldsManagers 와 jsonPointers(/metadata/annotations)를 함께 두고 출력을 /root/ga-ignore/mfm-plus.txt 에 저장하세요. 두 출력이 어떻게 다른지 보세요.

이 규칙은 '어떤 필드' 가 아니라 '누가 쓴 필드' 로 무시할 대상을 정합니다. 그래서 리소스 YAML 만 보고는 무엇이 빠질지 계산할 수 없고, 미리보기 명령도 이 목록만으로는 아무것도 렌더하지 못합니다.

동기화 판정과 조정 루프 깨우기는 다른 손잡이다

/root/ga-ignore/argocd-cm-updates.yaml 한 장에 키 두 개를 두세요 — resource.customizations.ignoreDifferences.apps_Deployment 는 jsonPointers 로 /spec/replicas 를, resource.customizations.ignoreResourceUpdates.apps_Deployment 는 jsonPointers 로 /metadata/annotations 를 무시합니다. 같은 파일에 대해 ignore-differences 출력을 /root/ga-ignore/updates-diff.txt 에, ignore-resource-updates 출력을 /root/ga-ignore/updates-upd.txt 에 저장하세요.

두 키는 목적이 다릅니다 — 앞의 것은 '이 차이는 OutOfSync 로 치지 않는다', 뒤의 것은 '이 변경으로는 조정 루프를 깨우지 않는다' 입니다. 뒤엣것은 컨트롤러의 부하를 줄이는 손잡이라 동기화 판정을 바꾸지 않습니다. 두 출력이 어떻게 다른지 그대로 기록하세요.

앱 하나에만 걸리는 규칙과 회귀 검사

/root/ga-ignore/application.yaml 에 Application ga-ignore-web(네임스페이스 argocd, 프로젝트 default)을 만들어 kwok 클러스터에 적용하세요. spec.ignoreDifferences 에 group apps, kind Deployment 인 항목 하나를 두고 그 안에 /spec/replicas 포인터와 sidecar 이미지를 고르는 jq 식을 함께 넣습니다. 그리고 /root/ga-ignore/ignore-matrix.tsv 에 <ConfigMap파일>\t<찾을 글자>\t<yes|no> 네 줄 이상을 적고, /root/ga-ignore/check-ignore.sh 로 전부 검사해 출력을 /root/ga-ignore/ignore-result.txt 에 저장하세요. 스크립트는 표준출력에만 쓰고 한 줄이라도 틀리면 0 이 아닌 코드로 끝나야 합니다.

전역 규칙(argocd-cm)은 모든 앱에 걸리고 Application 의 규칙은 그 앱에만 걸립니다. 둘은 합쳐져서 적용되니, 전역에 넓게 걸어 두고 앱에서 좁히는 일은 불가능합니다 — 좁히는 방향은 처음부터 앱 쪽에 두어야 합니다. 표에는 argocd-cm-wide.yaml 과 nginx 처럼 '이 규칙이 이 글자를 지우는가' 를 확인하는 줄을 섞으세요.