Kubernetes/Trouble Shooting

🛠️ K8S Trouble Shooting : 컨테이너 및 이미지 문제 해결하기

ygtoken 2025. 3. 2. 19:44
728x90

 

 

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 명령어 등을 활용하여 추가로 분석해보는 것이 좋습니다.

 

 

728x90