Kubernetes에서 컨테이너 및 이미지 관련 오류는 애플리케이션 배포 시 가장 자주 발생하는 문제 중 하나입니다.
이 글에서는 Kubernetes 환경에서 발생할 수 있는 대표적인 컨테이너 및 이미지 문제 5가지를 정리하고, 각각의 원인과 해결 방법을 설명합니다. 🚀
1️⃣ “Failed to pull image…”
🔎 오류 설명
이 오류는 Kubernetes가 컨테이너 이미지를 가져오지 못할 때 발생합니다.
주요 원인은 잘못된 이미지 이름, 태그 오류, 인증 문제 또는 네트워크 연결 문제일 수 있습니다.
🔧 해결 방법
1) 올바른 이미지 이름 및 태그 확인
먼저, 사용하려는 이미지가 올바르게 입력되었는지 확인합니다.
kubectl describe pod <pod-name> -n <namespace>출력된 이벤트 로그에서 Failed to pull image가 발생한 이유를 확인합니다.
이미지가 존재하는지 Docker Hub 또는 프라이빗 레지스트리에서 직접 확인할 수도 있습니다.
docker pull <image-name>:<tag>
2) 네트워크 연결 확인
이미지를 가져오려면 네트워크 연결이 원활해야 합니다.
ping registry-1.docker.io
3) 프라이빗 레지스트리 인증
프라이빗 이미지 레지스트리를 사용할 경우 로그인해야 합니다.
docker login <your-registry>
kubectl create secret docker-registry myregistrykey \
--docker-server=<your-registry> \
--docker-username=<your-username> \
--docker-password=<your-password> \
--namespace=<namespace>
이후 imagePullSecrets를 Pod 설정에 추가합니다.
spec:
imagePullSecrets:
- name: myregistrykey
2️⃣ “failed to start container…”
🔎 오류 설명
이 오류는 컨테이너가 정상적으로 시작되지 않았을 때 발생합니다.
일반적으로 리소스 부족, 잘못된 명령어, 환경 변수 문제 또는 이미지 실행 실패가 원인입니다.
🔧 해결 방법
1) 컨테이너 로그 확인
컨테이너 실행 실패 원인을 찾으려면 로그를 확인합니다.
kubectl logs <pod-name> -c <container-name> -n <namespace>
2) Pod 이벤트 확인
Pod에서 어떤 이벤트가 발생했는지 확인합니다.
kubectl describe pod <pod-name> -n <namespace>
3) 리소스 부족 문제 해결
컨테이너가 필요한 메모리 또는 CPU를 요청하지 못하는 경우, 리소스를 증가시키세요.
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "500m"
4) initContainer 오류 여부 확인
만약 initContainer를 사용하는 경우, 이 단계에서 오류가 발생할 수 있습니다.
kubectl get pods -n <namespace>
kubectl logs <pod-name> -c <init-container-name> -n <namespace>
3️⃣ “Error: image operating system…”
🔎 오류 설명
이 오류는 컨테이너 이미지의 운영체제(OS)와 Kubernetes 노드의 OS가 호환되지 않을 때 발생합니다.
주로 ARM 아키텍처(M1 Mac)에서 AMD64용 이미지를 실행할 때 나타납니다.
🔧 해결 방법
1) 이미지 아키텍처 확인
이미지가 올바른 아키텍처인지 확인합니다.
docker inspect <image-name> | grep Architecture
2) M1 Mac 또는 ARM 지원 이미지 사용
Apple M1 환경에서는 ARM64 기반 이미지를 사용해야 합니다.
docker pull <image-name>:arm64
또는 manifest를 지원하는 다중 아키텍처 이미지를 사용합니다.
docker buildx build --platform linux/arm64 -t <your-image> .
3) QEMU를 활용한 에뮬레이션
QEMU를 사용하여 다른 아키텍처의 컨테이너를 실행할 수도 있습니다.
docker run --platform linux/amd64 <image-name>
4️⃣ “Back-off restarting failed container”
🔎 오류 설명
이 오류는 컨테이너가 지속적으로 충돌(CrashLoopBackOff)하면서 재시작되는 경우 발생합니다.
애플리케이션 내부 문제, 환경 변수 설정 오류, 권한 문제 등이 원인일 수 있습니다.
🔧 해결 방법
1) 컨테이너 로그 확인
애플리케이션 내부 오류를 확인하려면 로그를 조회합니다.
kubectl logs <pod-name> -c <container-name> -n <namespace>
2) livenessProbe 및 readinessProbe 설정 확인
liveness 또는 readiness 프로브가 잘못 설정되면 컨테이너가 계속 재시작될 수 있습니다.
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 5
periodSeconds: 10
3) 재시작 정책 확인
Pod이 계속 충돌할 경우 restartPolicy를 변경하여 문제를 확인할 수 있습니다.
restartPolicy: Never
5️⃣ “invalid character ‘<’ looking for beginning of value”
🔎 오류 설명
이 오류는 잘못된 JSON 또는 YAML 형식이 사용될 때 발생합니다.
일반적으로 잘못된 ConfigMap, Secret 또는 환경 변수 값이 설정되었을 때 나타납니다.
🔧 해결 방법
1) 리소스 정의 확인
문제가 발생한 리소스를 확인합니다.
kubectl get configmap -n <namespace>
kubectl get secret -n <namespace>
2) YAML/JSON 파일 문법 검사
리소스 파일이 올바른 문법인지 확인합니다.
kubectl apply --dry-run=client -f <file.yaml>
또는 YAML 검증 도구를 사용할 수도 있습니다.
yamllint <file.yaml>
3) 환경 변수 값 검증
특정 환경 변수가 잘못된 형식으로 정의되었을 수 있습니다.
kubectl describe pod <pod-name> -n <namespace>
환경 변수가 <html> 같은 문자열을 포함하는지 확인합니다.
env:
- name: API_KEY
value: "<your-api-key>" # 잘못된 값 (따옴표 없이 입력해야 함)
🎯 마무리
이 글에서는 Kubernetes에서 자주 발생하는 컨테이너 및 이미지 관련 오류 5가지와 그 해결 방법을 다뤘습니다.
✔️ 이미지 다운로드 실패 (Failed to pull image)
✔️ 컨테이너 실행 실패 (Failed to start container)
✔️ 운영체제 아키텍처 불일치 (Error: image operating system)
✔️ CrashLoopBackOff 문제 (Back-off restarting failed container)
✔️ JSON/YAML 형식 오류 (invalid character ‘<’ looking for beginning of value)
만약 위 해결 방법으로도 문제가 해결되지 않는다면,
kubectl describe, kubectl logs, docker inspect 명령어 등을 활용하여 추가로 분석해보는 것이 좋습니다.
'Kubernetes > Trouble Shooting' 카테고리의 다른 글
| 🛠️ K8S Trouble Shooting : Persistent Volume(스토리지) 관련 오류 해결하기 (0) | 2025.03.02 |
|---|---|
| 🛠️ K8S Trouble Shooting : RBAC 및 인증 관련 오류 해결하기 (0) | 2025.03.02 |
| 🛠️ K8S Trouble Shooting : Helm 및 업그레이드 문제 해결하기 (0) | 2025.03.02 |
| 🛠️ K8S Trouble Shooting : 리소스 조회 및 존재 여부 오류 해결하기 (0) | 2025.03.02 |
| 🛠️ K8S Trouble Shooting : API 서버 및 네트워크 연결 문제 해결하기 (0) | 2025.03.02 |