ArgoCD 사용시 K8s 리소스가 의도치 않은 네임스페이스에 생기는 경우 트러블슈팅
🧵 ReferenceGrant 네임스페이스 오버라이딩 문제 분석과 해결기
🐳ArgoCD 에서 Helm + Kustomize 를 함께 사용하여 관리하는 경우에 발생한 문제를 다룹니다.
쿠버네티스 Gateway API와 cert-manager를 함께 사용하는 경우, ReferenceGrant 리소스 설정은 TLS 인증서 발급 및 사용을 위해 꼭 필요하다. 복잡한 상황을 해소하고자 ReferenceGrant를 istio-system 어플리케이션에 몰아넣었는데, 문제가 발생했다. 여기에 문제 상황과 해결방법을 정리하고 공유하려 한다.
클러스터 상태 및 Gitops
이전 내 gitops 상황을 요약하면 아래와 같다.
.
├── argocd
│ ├── argocd
│ │ └── application.yaml
│ ├── cert-manager
│ │ └── application.yaml
│ ├── istio-system
│ │ └── application.yaml
│ └── jenkins
│ └── application.yaml
├── cert-manager
│ ├── base
│ │ ├── namespace.yaml
│ │ └── values.yaml
│ ├── certificate
│ │ └── wildcard-certificate.yaml
│ ├── issuer
│ │ └── clusterissuer-letsencrypt.yaml
│ ├── secret
│ │ └── cloudflare-api-token-secret.yaml
│ └── kustomization.yaml
├── istio-system
│ └── istio
│ ├── argocd-route.yaml
│ ├── gateway-api-crds.yaml
│ ├── jenkins-route.yaml
│ ├── minseoky-gateway.yaml
│ ├── namespace.yaml
│ ├── values.yaml
│ ├── kustomization.yaml
│ ├── argocd-reference-grant.yaml # ❗잘못 배치됨
│ ├── jenkins-reference-grant.yaml # ❗잘못 배치됨
│ ├── secret-reference-grant.yaml # ❗잘못 배치됨
│ └── referencegrant-kustomization.yaml # ❗잘못 배치됨
├── jenkins
│ ├── base
│ │ ├── namespace.yaml
│ │ └── values.yaml
│ └── kustomization.yaml
├── kustomization.yaml
└── README.md
크게 argocd, istio-system, jenkins, cert-manager 네 개의 어플리케이션을 관리하고 있다.
Argocd + Helm + Kustomize 방식을 사용해서 관리를 하고 있었고, 그에 따라 ArgoCD에는 enable helm 옵션이 추가된 상태였다.
그리고 상술된 tree 커맨드 결과를 보면 알 수 있듯, 각 reference-grant를 모두 istio에서 관리하고 있었다. 리소스 중 하나인 jenkins를 직접 까보면, 아래와 같다.
jenkins
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
name: allow-istio-to-access-jenkins
namespace: jenkins # ✅ namespace가 istio-system이 아닌, jenkins로 명시되어있다.
spec:
from:
- group: gateway.networking.k8s.io
kind: HTTPRoute
namespace: istio-system
to:
- group: ""
kind: Service
name: jenkins
위처럼 분명히 namespace를 jenkins로 명시했음에도 불구하고, 실제 ReferenceGrant 리소스가 istio-system에 생성되는 영문을 알 수 없는 상황이 발생했다.
🐳 minseoky@proxmox:~/PLAYGROUND/gitops/referencegrant$ kubectl get referencegrant -A
NAMESPACE NAME AGE
istio-system allow-istio-to-access-argocd 40h
istio-system allow-istio-cert-access 40h
istio-system allow-istio-to-access-jenkins 40h
문제 원인 분석: Kustomize의 namespace 오버라이드
이는 Kustomize에 대한 잘못된 이해에서 비롯된 실수였다. 공식문서를 보면, 분명히 아래와 같이 명시되어 있다.
namespace
Will override the existing namespace if it is set on a resource, or add it if it is not set on a resource.
분명 Kustomize에 대해 처음 배울때 배웠던 기억이 나는데 그새 까먹었던 것 같다. 문제 해결은 간단했다. 각 reference grant를 관리 주체의 디렉토리에 재배치하면 됐다.
근데 개인적으로 마음에 안드는 부분이 있었다. 바로 argocd의 webui에 접근하기 위해 생성한 allow-istio-to-access-argocd 리소스를 argocd 디렉토리에 넣기가 싫었다.
상술한 tree 커맨드 결과를 보면 알 수 있듯, argocd는 다른 리소스와 동일하게 application으로 self-managing을 하고 있지만, 따로 Kustomize를 적극적으로 쓰지는 않는 친구였기 때문에 리소스를 정의할 공간을 지정하는 것이 어색하게 느껴졌다.
그래서 내 절충안은 따로 referencegrant 디렉토리를 만들어, 서로 다른 네임스페이스의 reference grant 들을 관리했다.
.
├── referencegrant
│ ├── argocd-reference-grant.yaml
│ ├── jenkins-reference-grant.yaml
│ ├── secret-reference-grant.yaml
│ └── kustomization.yaml
이 방식은 다음과 같은 장점이 있었다:
- 의도치 않은 namespace 오버라이딩 방지
- referencegrant/kustomization.yaml 파일에는 namespace 필드를 명시하지 않음으로써, 각 리소스에 정의된 네임스페이스가 그대로 유지된다.
- 리소스 분리 명확화
- ArgoCD, Jenkins 등 개별 서비스 디렉토리에 ReferenceGrant를 끼워 넣지 않아도 되므로, 각 서비스 디렉토리는 자신에게 직접적으로 관련된 리소스만을 포함하게 된다.
- 공통된 목적의 리소스를 모아 관리
- ReferenceGrant는 서비스 간 권한 위임이라는 공통된 목적을 가지므로, 이를 논리적으로 묶어 관리할 수 있는 구조가 생긴 셈이다.
사실상 ReferenceGrant는 서로 다른 네임스페이스 간 브릿지(bridge) 역할을 수행하는 리소스다. 단일 서비스의 내부 리소스라기보다는, 네임스페이스 간 경계를 넘는 참조를 허용하기 위한 인프라 레벨의 설정에 가깝다.
따라서 특정 서비스 디렉토리 하위에서 ReferenceGrant를 관리하는 것보다는, 별도의 referencegrant 디렉토리에서 공통적으로 관리하는 것이 더 자연스럽다고 판단했다. 이는 단지 폴더 구조의 문제를 넘어서, ReferenceGrant의 본질적인 역할을 반영한 설계 철학이라고 생각한다. 이는 베스트 프렉티스가 아니며, 단지 내 개인적인 생각이다...
정리
Kustomize를 Helm과 함께 쓸 때, namespace 필드 하나가 얼마나 큰 영향을 미칠 수 있는지를 직접 체험하게 된 사건이었다. ArgoCD처럼 선언형 GitOps 방식을 사용하는 경우, 리소스 배포의 추적성과 예측 가능성이 매우 중요한데, 이런 작은 실수가 전체 시스템의 TLS 연동에 영향을 줄 수 있음을 깨달았다.
앞으로는 네임스페이스 관련 설정을 적용할 때 더더욱 주의하려고 한다. 이 글이 나와 같은 실수를 겪는 사람들에게 도움이 되기를 바란다.