쿠버네티스 배포 중 마주한 문제와 해결방법

 Troubleshooting 

CI/CD 파이프라인을 만들다 보면 다양한 에러를 마주하게 됩니다.
아래는 제가 실제로 마주쳤던 문제들과 해결 방법을 정리한 리스트입니다.

---

1. ❌ ImagePullBackOff

현상

kubectl get pods
# STATUS: ImagePullBackOff

 

원인

• Kubernetes가 컨테이너 이미지를 GHCR (private registry) 에서 가져오지 못함

해결 방법

1. GHCR Personal Access Token을 만들 때 read:packages 권한 포함했는지 확인
2. Kubernetes Secret 생성
3. kubectl create secret docker-registry ghcr-secret \ --docker-server=ghcr.io \ --docker-username=<USERNAME> \ --docker-password=<TOKEN> \ --docker-email=none
4. values-dev.yaml 또는 Deployment에 imagePullSecrets 추가
5. imagePullSecrets: - name: ghcr-secret

---

2. ❌ failed to authorize: failed to fetch anonymous token

현상

failed to authorize: failed to fetch anonymous token: unexpected status from GET request

 

원인

• Kubernetes가 인증 없이 GHCR 접근을 시도함 (Secret 누락)

해결 방법

• 2번과 같이 ghcr-secret을 생성하고, Helm values에 반영

---

3. ❌ nil pointer evaluating interface {}.image

현상

executing "image-gallery/templates/backend-deployment.yaml" at <.Values.backend.image>: nil pointer evaluating interface {}.image

 

원인

• values.yaml에 backend.image 또는 frontend.image 값이 빠져 있음

해결 방법

• values-dev.yaml 값이 잘 정의되어 있는지, helm 에 잘 주입되었는지 확인
  • backend: image: ghcr.io/<USERNAME>/backend tag: latest
  • frontend: image: ghcr.io/<USERNAME>/frontend tag: latest

---

4. ❌ helm upgrade ... path not found

현상

Error: path "./helm/image-gallery" not found

 

원인

• Jenkins workspace와 실제 Helm Chart 경로가 다름

해결 방법

• Jenkinsfile에서 Helm 실행 시 경로 지정하거나 main 브랜치로 check out 하기
• dir('helm/image-gallery') { sh "helm upgrade --install image-gallery . -f values-dev.yaml" }

---

5. ❌ Unsplash API Key 전달 문제

현상

• Docker build 시 --build-arg로 API Key를 전달 → 배포 후 Pod에서 값이 없음

해결 방법

1. Kubernetes Secret 사용
2. kubectl create secret generic unsplash-secret \ --from-literal=ACCESS_KEY=<UNSPLASH_KEY>
3. Helm 템플릿에 환경변수 주입
   • env:
     • - name: UNSPLASH_ACCESS_KEY
       • valueFrom: secretKeyRef:
       • name: unsplash-secret
       • key: ACCESS_KEY

---

6. ❌ 포트 접근 불가

현상

• 브라우저에서 프론트엔드/백엔드 접근이 안 됨

원인

• Service 타입이 ClusterIP라 외부 접근 불가

해결 방법

• 로컬 테스트 시 포트포워딩
• kubectl port-forward svc/image-gallery-frontend 3000:80
• kubectl port-forward svc/image-gallery-backend 8000:8000
• 이후 브라우저에서 http://localhost:3000 / http://localhost:8000 확인

---

7. ❌ ADDRESS가 비어 있음 / <none> 표시 (Ingress)

• 현상

NAME                             CLASS    HOSTS         ADDRESS   PORTS   AGE 
image-gallery-backend-ingress    <none>   myapp.local             80      67s 
image-gallery-frontend-ingress   <none>   myapp.local             80      67s

• 원인
  • Ingress 리소스가 제대로 ingressClassName을 지정하지 않아서 발생하는 상황
  • ingress-nginx 컨트롤러는 특정 Ingress 리소스를 처리하기 위해 ingressClassName 필드를 사용하는데, 이 필드가 없으면 Ingress 컨트롤러는 어떤 Ingress를 처리해야 할지 모르기 때문에 IP 주소를 할당하지 않는다.
  • Minikube NGINX Ingress Controller가 이 리소스를 처리하지 않음
• 해결 방법
  • 각 Ingress YAML에 spec.ingressClassName: nginx 추가
    • spec: ingressClassName: nginx

✅ 정리

1. ImagePullBackOff → GHCR 인증 문제 → ghcr-secret 생성 & Helm values에 반영
2. failed to authorize → Secret 누락 → imagePullSecrets 확인
3. nil pointer → values.yaml에 image 값 빠짐 → values-dev.yaml 수정
4. path not found → Jenkins workspace 경로 문제 → dir('helm/image-gallery') 사용
5. API Key 전달 문제 → Docker build-time 전달 ❌, Kubernetes Secret ✅
6. 포트 접근 문제 → ClusterIP는 직접 접근 불가 → 포트포워딩 사용
7. Ingress Address 비어 있음 → 각 Ingress YAML에 spec.ingressClassName 설정