Kubernetes에서 삭제되지 않은 리소스로 인한 설치 충돌 문제 해결하기

운영 중 Kubernetes 클러스터에서 애드온(addon)이나 신규 애플리케이션을 배포하다 보면,
종종 기존 리소스가 완전히 삭제되지 않은 상태에서 잔여 리소스가 충돌을 일으키는 경우가 있다.

대표적으로 MutatingWebhookConfiguration 또는 ValidatingWebhookConfiguration 과 같은 웹훅(Webhook) 리소스가 삭제되지 않고 남아있을 때 이런 문제가 발생.
이 리소스들은 API 요청 경로에 개입하여 리소스 생성/수정을 검증하기 때문에, 예상치 못한 에러를 유발할 수 있음.

증상

• Helm 차트나 매니페스트를 새로 적용하려는데 설치가 실패
• kubectl apply 시 기존 웹훅이 걸려 리소스가 생성되지 않음
• 이미 삭제한 애드온(예: Istio, ArgoCD, Gatekeeper 등)의 웹훅 설정이 남아 있음

1. 잔여 웹훅 리소스 확인

우선 현재 클러스터에 남아있는 웹훅 관련 리소스를 확인.

# 변환(Mutating) 웹훅 확인
kubectl get mutatingwebhookconfiguration

# 검증(Validating) 웹훅 확인
kubectl get validatingwebhookconfiguration

출력 예시:

NAME                        WEBHOOKS   AGE
istio-sidecar-injector      2          5d
argo-validate-config        1          10d

2. 불필요한 리소스 삭제

이미 삭제한 애드온에서 남긴 리소스라면 안전하게 제거할 수 있음.

# MutatingWebhookConfiguration 삭제
kubectl delete mutatingwebhookconfiguration <resource-name>

# ValidatingWebhookConfiguration 삭제
kubectl delete validatingwebhookconfiguration <resource-name>

예시:

kubectl delete mutatingwebhookconfiguration istio-sidecar-injector
kubectl delete validatingwebhookconfiguration argo-validate-config

3. 추가 확인 포인트

웹훅 외에도 설치가 꼬일 수 있는 “잔여 리소스”는 다음과 같다 :

• CustomResourceDefinition (CRD)
• ValidatingAdmissionPolicy
• APIService
• Namespace (삭제 중 Terminating 상태에 멈춰 있는 경우)

이런 리소스들도 설치 충돌의 원인이 될 수 있으므로, 필요하다면 다음처럼 정리

kubectl get crd | grep <addon-name>
kubectl delete crd <crd-name>

kubectl get apiservice
kubectl delete apiservice <apiservice-name>

마무리

• Kubernetes에서 삭제가 덜 된 리소스는 신규 설치 시 충돌을 일으킬 수 있다.
• 특히 MutatingWebhookConfiguration / ValidatingWebhookConfiguration 은 설치 실패의 주요 원인.
• 불필요한 리소스를 정리한 뒤 다시 설치하면 정상적으로 배포가 가능하다.

🛠 마지막 수정일: 2025.09.22