オプションを入れたのに効かない — 設定をデプロイ前に読み返す

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

목표

argocd-cm 을 한 항목씩 늘려 가며 argocd admin settings validate 로 Argo CD 가 읽어 낸 값을 확인하고, 오타 난 키가 어떻게 조용히 사라지는지 본다. 저장소 Secret 과 소유 표시 방식은 kwok 클러스터에 직접 올린다.

왜 중요한가

Argo CD 를 선언으로 관리하면 argocd-cm 한 장이 플랫폼 전체의 동작을 정한다. 그런데 이 파일은 평범한 ConfigMap 이라 스키마가 없다 — 키 이름을 틀려도 거절되지 않고, 그냥 그 설정이 없는 것이 된다. 이 조용함이 문제를 오래 살아남게 한다. argocd admin settings validate 는 파일을 검사하는 도구가 아니라 도구가 그 파일에서 무엇을 읽어 냈는지 절별로 돌려주는 도구다. 그래서 쓰는 법이 중요하다 — '✅ 가 떴으니 괜찮다' 가 아니라 내가 넣은 값이 되돌아 나오는가를 본다. 설정 변경에 이 출력의 전후 diff 를 붙이는 습관 하나가 '왜 이 옵션이 안 먹지' 라는 질문을 없앤다.

단계

/root/ga-settings/argocd-cm.yaml 을 data: {} 인 argocd-cm ConfigMap 으로 만들고, argocd admin settings validate --argocd-cm-path /root/ga-settings/argocd-cm.yaml 의 출력을 /root/ga-settings/baseline.txt 에 저장하세요. 다섯 개 절(accounts·general·kustomize·repositories·resource-overrides)이 모두 보여야 합니다.
/root/ga-settings/argocd-cm-accounts.yaml 에 계정 두 개를 선언하세요 — accounts.ci 는 apiKey, login, accounts.readonly 는 apiKey 입니다. --group accounts 만 검사한 출력을 /root/ga-settings/accounts.txt 에 저장하세요. 계정 수가 몇으로 나오는지 보세요.
/root/ga-settings/argocd-cm-kustomize.yaml 은 2단계 계정에 더해 kustomize.buildOptions 를 --enable-helm 으로 둡니다. --group kustomize 출력을 /root/ga-settings/kustomize.txt 에 저장하세요.
/root/ga-settings/argocd-cm-typo.yaml 을 3단계 파일과 똑같이 만들되 키 이름만 kustomize.buildOption (끝의 s 를 뺀 단수)으로 쓰세요. --group kustomize 출력을 /root/ga-settings/typo.txt 에 저장하고, 3단계 출력과 견줘 보세요.
/root/ga-settings/argocd-cm-scope.yaml 은 3단계 내용에 resource.exclusions 를 더합니다. 항목 두 개를 두세요 — 하나는 apiGroups cilium.io 의 CiliumIdentity, 다른 하나는 코어 그룹(빈 문자열)의 Event 이고, 둘 다 clusters 는 "*" 입니다. /root/ga-settings/scope.txt 에 --group kustomize 와 --group resource-overrides 를 함께 검사한 출력을 저장하세요.
/root/ga-settings/argocd-cm-track.yaml 은 5단계 내용에 application.resourceTrackingMethod: annotation 과 application.instanceLabelKey: labhub.io/instance 를 더합니다. 그다음 kwok 클러스터에 네임스페이스 ga-settings 와 /root/ga-settings/deploy.yaml(Deployment web, 이미지 nginx:1.25)을 올리고, gitops-argocd-platform-team-a-production-cluster-seoul-web-frontend-app 라는 긴 이름을 라벨 값으로 붙여 보세요 — 실패한 명령의 출력을 표준오류까지 합쳐 /root/ga-settings/label-limit.txt 에 저장합니다. 같은 값을 주석 argocd.argoproj.io/tracking-id 로는 붙일 수 있습니다. 그렇게 하세요.
/root/ga-settings/argocd-cm-repo.yaml 은 6단계 내용에 repositories 목록(url https://example.com/ga-manifests.git, name ga-manifests, type git)을 더합니다. --group repositories 출력을 /root/ga-settings/repo.txt 에 저장하세요. 그다음 지금 권장되는 방식으로 같은 저장소를 /root/ga-settings/repo-secret.yaml 에 Secret ga-settings-repo(네임스페이스 argocd)로 쓰고 kwok 클러스터에 적용하세요 — 라벨 argocd.argoproj.io/secret-type: repository 가 반드시 있어야 하고, stringData 에 type·name·url 을 둡니다.
/root/ga-settings/argocd-cm-final.yaml 은 7단계 내용에 url(https://argocd.example.com)과 dex.config(github 커넥터 하나)를 더합니다. 전체 절을 검사한 출력을 /root/ga-settings/final.txt 에 저장하고, diff /root/ga-settings/baseline.txt /root/ga-settings/final.txt 의 출력을 /root/ga-settings/settings-diff.txt 에 저장하세요. diff 는 종료 코드가 0 이 아니므로 정답지에서 멈추지 않게 조심하세요.

참고

--group 으로 절을 고를 수 있습니다: accounts, general, kustomize, repositories, resource-overrides.
이 명령은 kubeconfig 가 필요합니다. 실습 파드에는 이미 걸려 있습니다.
resource.exclusions 처럼 어느 절에도 나타나지 않는 설정이 있습니다 — 그런 것은 파일로 확인해야 합니다.
흔한 실수: kustomize.buildOption 처럼 키 이름을 틀린다. 오류 없이 기본값이 됩니다.
흔한 실수: 저장소 Secret 에 argocd.argoproj.io/secret-type 라벨을 빠뜨린다. 역시 오류가 없습니다.
참고: https://argo-cd.readthedocs.io/en/stable/operator-manual/argocd-cm-yaml/

빈 설정이 무엇을 돌려주는지부터 본다

/root/ga-settings/argocd-cm.yaml 을 data: {} 인 argocd-cm ConfigMap 으로 만들고, argocd admin settings validate --argocd-cm-path /root/ga-settings/argocd-cm.yaml 의 출력을 /root/ga-settings/baseline.txt 에 저장하세요. 다섯 개 절(accounts·general·kustomize·repositories·resource-overrides)이 모두 보여야 합니다.

이 명령은 '파일에 문제가 없는가' 가 아니라 '이 파일에서 무엇을 읽어 냈는가' 를 절별로 돌려줍니다. 비어 있는데도 계정이 하나 보이는 이유를 생각해 보세요 — 관리자 계정은 설정 없이도 있습니다.

계정을 선언으로 늘린다

/root/ga-settings/argocd-cm-accounts.yaml 에 계정 두 개를 선언하세요 — accounts.ci 는 apiKey, login, accounts.readonly 는 apiKey 입니다. --group accounts 만 검사한 출력을 /root/ga-settings/accounts.txt 에 저장하세요. 계정 수가 몇으로 나오는지 보세요.

계정 키의 값은 그 계정이 할 수 있는 일의 목록입니다 — apiKey 는 토큰 발급, login 은 화면 로그인입니다. CI 처럼 사람이 아닌 주체에는 login 을 주지 않는 편이 낫습니다. 기본 admin 계정이 이미 하나 있다는 것도 세어 보세요.

읽어 낸 값을 그대로 돌려주는 절

/root/ga-settings/argocd-cm-kustomize.yaml 은 2단계 계정에 더해 kustomize.buildOptions 를 --enable-helm 으로 둡니다. --group kustomize 출력을 /root/ga-settings/kustomize.txt 에 저장하세요.

이 절은 숫자가 아니라 읽어 낸 값 자체를 돌려줍니다. 그래서 '내가 적은 것' 과 '도구가 읽은 것' 을 눈으로 견줄 수 있는 몇 안 되는 자리입니다 — 다음 단계에서 이 성질을 쓸 겁니다.

키 이름을 틀리면 아무도 알려 주지 않는다

/root/ga-settings/argocd-cm-typo.yaml 을 3단계 파일과 똑같이 만들되 키 이름만 kustomize.buildOption (끝의 s 를 뺀 단수)으로 쓰세요. --group kustomize 출력을 /root/ga-settings/typo.txt 에 저장하고, 3단계 출력과 견줘 보세요.

ConfigMap 은 어떤 키든 받아 줍니다 — 스키마가 없으니까요. 그래서 오타는 오류가 아니라 '설정하지 않음' 이 됩니다. 이 명령이 되돌려 주는 값을 보는 습관이 이런 실수를 잡는 유일한 방법입니다.

아예 보지 않을 것을 정한다

/root/ga-settings/argocd-cm-scope.yaml 은 3단계 내용에 resource.exclusions 를 더합니다. 항목 두 개를 두세요 — 하나는 apiGroups cilium.io 의 CiliumIdentity, 다른 하나는 코어 그룹(빈 문자열)의 Event 이고, 둘 다 clusters 는 "*" 입니다. /root/ga-settings/scope.txt 에 --group kustomize 와 --group resource-overrides 를 함께 검사한 출력을 저장하세요.

제외 목록은 Argo CD 가 클러스터에서 아예 감시하지 않을 종류를 정합니다. 초당 수천 개가 생기는 Event 나 CNI 가 만드는 신원 객체를 빼면 컨트롤러 부하가 크게 줄어듭니다. 그런데 이 설정은 validate 출력의 어느 절에도 나타나지 않습니다 — 그것도 확인해 두세요.

소유 표시를 라벨에서 주석으로 옮기는 이유

/root/ga-settings/argocd-cm-track.yaml 은 5단계 내용에 application.resourceTrackingMethod: annotation 과 application.instanceLabelKey: labhub.io/instance 를 더합니다. 그다음 kwok 클러스터에 네임스페이스 ga-settings 와 /root/ga-settings/deploy.yaml(Deployment web, 이미지 nginx:1.25)을 올리고, gitops-argocd-platform-team-a-production-cluster-seoul-web-frontend-app 라는 긴 이름을 라벨 값으로 붙여 보세요 — 실패한 명령의 출력을 표준오류까지 합쳐 /root/ga-settings/label-limit.txt 에 저장합니다. 같은 값을 주석 argocd.argoproj.io/tracking-id 로는 붙일 수 있습니다. 그렇게 하세요.

라벨 값은 63자를 넘을 수 없습니다. 앱 이름이 길어지는 큰 조직에서 라벨 방식은 이 한도에 부딪히고, 잘린 이름 때문에 서로 다른 앱이 같은 소유 표시를 갖게 됩니다. 주석에는 이 한도가 없습니다.

저장소는 ConfigMap 이 아니라 Secret 으로 선언한다

/root/ga-settings/argocd-cm-repo.yaml 은 6단계 내용에 repositories 목록(url https://example.com/ga-manifests.git, name ga-manifests, type git)을 더합니다. --group repositories 출력을 /root/ga-settings/repo.txt 에 저장하세요. 그다음 지금 권장되는 방식으로 같은 저장소를 /root/ga-settings/repo-secret.yaml 에 Secret ga-settings-repo(네임스페이스 argocd)로 쓰고 kwok 클러스터에 적용하세요 — 라벨 argocd.argoproj.io/secret-type: repository 가 반드시 있어야 하고, stringData 에 type·name·url 을 둡니다.

ConfigMap 의 repositories 목록은 예전 방식이라 비밀번호나 키를 함께 둘 수 없습니다. 지금은 Secret 하나가 저장소 하나이고, Argo CD 는 그 라벨로 저장소용 Secret 을 찾습니다. 라벨이 없으면 아무 일도 일어나지 않습니다 — 오류도 나지 않습니다.

바꾸기 전과 후를 나란히 놓는다

/root/ga-settings/argocd-cm-final.yaml 은 7단계 내용에 url(https://argocd.example.com)과 dex.config(github 커넥터 하나)를 더합니다. 전체 절을 검사한 출력을 /root/ga-settings/final.txt 에 저장하고, diff /root/ga-settings/baseline.txt /root/ga-settings/final.txt 의 출력을 /root/ga-settings/settings-diff.txt 에 저장하세요. diff 는 종료 코드가 0 이 아니므로 정답지에서 멈추지 않게 조심하세요.

설정을 바꾸는 변경에는 '무엇이 달라지는가' 를 파일로 남기는 습관이 필요합니다. 그래야 리뷰어가 ConfigMap 의 줄이 아니라 도구가 읽어 낸 값을 볼 수 있습니다. general 절이 어떻게 바뀌는지 확인하세요.