values 파일은 2 인데 파드는 3개였다

목표

진짜 Argo CD 에서 Helm 차트와 Kustomize 오버레이를 소스로 쓰고, 값이 어디서 정해지는지, 동기화 단계·웨이브·훅이 적용 순서를 어떻게 바꾸는지,
selfHeal 이 무엇을 되돌리지 않게 할 수 있는지를 클러스터에 생긴 결과로 확인합니다.

왜 중요한가

Argo CD 는 Helm 을 패키지 관리자로 쓰지 않고 템플릿 엔진으로만 씁니다. 그래서 helm list 에 아무것도 없고, 롤백도 Helm 이 아니라 Git 과 Argo CD 가 맡습니다.
대신 값이 네 군데(차트 기본값, 값 파일, Application 의 valuesObject, parameters)에서 올 수 있어 "Git 의 values 파일을 고쳤는데 왜 안 바뀌지" 가 흔한 장애가 됩니다.
Kustomize 덮어쓰기도 같아서 Application 에 적은 이미지는 Git 저장소에 없는 원하는 상태입니다. 동기화는 한 번에 모두 적용하는 것이 아니라
PreSync·Sync·PostSync 단계와 웨이브로 나뉘고, 앞 웨이브가 Healthy 가 될 때까지 기다리며, 훅이 실패하면 뒤 단계는 시작되지 않습니다.
마지막으로 HPA 처럼 다른 조정기가 소유한 필드는 ignoreDifferences 로 비교와 동기화에서 빼야 selfHeal 과 싸우지 않습니다.

단계

1. 베어 저장소 /srv/bare/src.git 을 만들고 /root/capa-src/repo 로 복제해 charts/web 에 Helm 차트를 커밋·push 하세요. Chart.yaml(name web, version 0.1.0), values.yaml(replicaCount: 1, greeting: chart-default), values-prod.yaml(replicaCount: 2, greeting: from-values-file), 템플릿 두 개({{ .Release.Name }}-greeting ConfigMap 의 data.greeting, {{ .Release.Name }}-web Deployment 의 replicas·이미지 nginx:1.27-alpine)를 둡니다. /root/capa-src/app-src-helm.yaml 의 Application src-helm(저장소 git://gitd.gitsrv.svc.cluster.local:9418/src.git main·charts/web, 대상 네임스페이스 src-helm, 자동 동기화·CreateNamespace)에 helm.valueFiles: [values-prod.yaml] 를 주고 적용해 Synced·Healthy 를 확인하세요.
2. src-helm 의 source.helm 에 valuesObject(replicaCount: 3, greeting: from-values-object)와 parameters(greeting = from-parameter)를 더해 다시 적용하세요. 동기화가 끝나면 /root/capa-src/precedence.json 에 replicas(src-helm 네임스페이스 Deployment src-helm-web 의 spec.replicas, 숫자)와 greeting(ConfigMap src-helm-greeting 의 값)을 적습니다.
3. Argo CD 는 차트를 렌더링해 적용할 뿐 Helm 릴리스를 만들지 않습니다. src-helm 네임스페이스의 Secret 중 타입이 helm.sh/release.v1 인 것의 개수와, ConfigMap src-helm-greeting 에 Argo CD 가 남긴 추적 표식을 확인해 /root/capa-src/tracking.json 에 helm_release_secrets(숫자), tracking_annotation(그 ConfigMap 의 argocd.argoproj.io/tracking-id 값), instance_label(라벨 app.kubernetes.io/instance 가 있으면 그 값, 없으면 null)을 적으세요.
4. /root/capa-src/repo/kust 에 Kustomize 구조를 커밋·push 하세요. base 에 Deployment api(replicas 1, 라벨 app: api, 이미지 nginx:1.27-alpine)와 kustomization, overlays/prod 에 base 를 가리키고 namePrefix: prod-, replicas 로 api 를 2 로 바꾸는 kustomization 을 둡니다. Application src-kust(경로 kust/overlays/prod, 대상 네임스페이스 src-kust, 자동 동기화·CreateNamespace)를 /root/capa-src/app-src-kust.yaml 에 쓰고, source.kustomize.images 로 nginx=nginx:1.28-alpine 을 지정해 적용하세요. Deployment prod-api 가 2개 파드·이미지 1.28 로 Healthy 여야 합니다.
5. /root/capa-src/repo/waves 에 네 파일을 커밋·push 하세요. ConfigMap settings(sync-wave -1), readinessProbe 가 있는 Deployment app(sync-wave 0, 이미지 nginx:1.27-alpine), Job smoke(sync-wave 1, busybox:1.36 이 echo smoke ok), PreSync 훅 Job(generateName migrate-, hook-delete-policy BeforeHookCreation, busybox:1.36 이 echo migrate ok)입니다. Application src-waves(경로 waves, 대상 네임스페이스 src-waves, 자동 동기화·CreateNamespace)를 /root/capa-src/app-src-waves.yaml 로 적용하고 Synced·Healthy·작업 Succeeded 를 확인하세요. 그 시점의 관찰을 /root/capa-src/waves.json 에 hook_job(성공한 PreSync 훅 Job 이름), hook_created(그 Job 의 creationTimestamp), settings_created(ConfigMap settings 의 creationTimestamp)로 남깁니다.
6. 한 커밋에서 waves/config.yaml 의 mode 를 green 으로, waves/migrate.yaml 의 명령을 echo migrate failed; exit 1 로 바꿔 push 하고 src-waves 를 hard refresh 하세요. 작업이 실패한 것을 보고 /root/capa-src/failed-hook.json 에 commit(그 커밋 SHA), phase(status.operationState.phase), live_mode(src-waves 의 ConfigMap settings 의 mode)를 적습니다. 그다음 migrate 명령만 원래대로 되돌린 새 커밋을 push 하고(mode 는 green 유지), 필요하면 실패한 작업을 끝낸 뒤 src-waves 가 새 커밋에 Synced·Healthy·Succeeded 가 되어 mode 가 green 으로 바뀌게 하세요.
7. src-kust 에 ignoreDifferences(group apps, kind Deployment, jsonPointers /spec/replicas)와 syncOptions RespectIgnoreDifferences=true 를 더해 다시 적용하세요(자동 동기화·selfHeal 은 유지). 그다음 kubectl scale 로 prod-api 를 4 로 늘리고 40초 이상 기다린 뒤에도 replicas 가 4 이고 src-kust 가 Synced 인 것을 확인해 /root/capa-src/ignore.json 에 scaled_at(scale 직후 유닉스 초), checked_at, replicas(확인 시점 값, 숫자), sync_status 를 적으세요.
8. /root/capa-src/report.json 에 helm_winner(greeting 을 정한 곳: chart·valueFiles·valuesObject·parameters 중 하나), replicas_winner(replicaCount 를 정한 곳, 같은 선택지), helm_installed(Helm 릴리스가 만들어졌는지, 불리언), image_source(prod-api 이미지 1.28 이 정의된 곳: git 또는 application), hook_blocked_sync(6단계 실패 때 mode 가 바뀌지 않았는지, 불리언), replicas_owner(prod-api 의 spec.replicas 필드를 지금 소유한 managedFields 관리자 이름)를 적으세요.

참고

• VM 안에 k3s, Argo CD v3.5.2, git 데몬(gitd.gitsrv)이 있습니다. /srv/bare/<이름>.git 은 git://gitd.gitsrv.svc.cluster.local:9418/<이름>.git 으로 보입니다.
• 렌더링 결과 미리 보기: kubectl -n argocd get app <이름> -o jsonpath='{.status.resources}', 작업 결과: .status.operationState.syncResult.resources.
• 즉시 다시 읽게 하기: kubectl -n argocd annotate app <이름> argocd.argoproj.io/refresh=hard --overwrite.
• 흔한 실수: valueFiles 경로를 저장소 루트 기준으로 쓰는 것. 차트 디렉터리 기준입니다.
• 흔한 실수: 6단계에서 훅을 고친 뒤 Synced 만 보고 넘어가는 것. 실패한 revision 을 재시도하는 작업이 남아 있으면 새 커밋이 적용되지 않습니다.
• [Helm](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/) · [Kustomize](https://argo-cd.readthedocs.io/en/stable/user-guide/kustomize/) · [Sync Phases and Waves](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/) · [Diffing](https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/) · [Resource Tracking](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_tracking/)

단계 8개

1. 차트를 Git 에 두고 Application 으로 가리킨다
2. values 파일은 2 인데 파드는 3개였다
3. helm list 에는 아무것도 없다
4. Git 에는 1.27 인데 클러스터에는 1.28
5. 스모크 Job 은 앱이 준비된 뒤에야 생겼다
6. 훅이 실패하자 바꾼 설정은 적용되지 않았다
7. 손으로 늘린 레플리카를 selfHeal 이 두고 본다
8. Git·Application·클러스터 중 누가 값을 정했나