이 페이지는 Cloud Translation API를 통해 번역되었습니다.

CrashLoopBackOff 이벤트 문제 해결

Autopilot Standard

이 페이지는 Google Kubernetes Engine (GKE)에서 CrashLoopBackOff 이벤트가 발생하는 포드 문제를 해결하는 데 도움이 됩니다.

이 페이지는 컨테이너가 비정상 종료되는 원인이 되는 구성 오류나 코드 관련 버그와 같은 앱 수준 문제를 파악하려는 애플리케이션 개발자를 대상으로 합니다. 또한 리소스 소진, 노드 중단, 잘못 구성된 활성 프로브와 같은 컨테이너 다시 시작의 플랫폼 수준 근본 원인을 파악해야 하는 플랫폼 관리자 및 운영자를 위한 페이지입니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참고하세요.

`CrashLoopBackOff` 이벤트 이해

포드가 CrashLoopBackOff 상태로 멈추면 포드 내 컨테이너가 반복적으로 시작되고 비정상 종료되거나 종료됩니다. 이 CrashLoop은 Kubernetes가 restartPolicy를 준수하여 컨테이너를 다시 시작하도록 트리거합니다. 다시 시작할 때마다 다음 시도 전 BackOff 지연 시간이 기하급수적으로 증가 (예: 10초, 20초, 40초)하여 최대 5분까지 늘어납니다.

이 이벤트는 컨테이너 내의 문제를 나타내지만 유용한 진단 신호이기도 합니다. CrashLoopBackOff 이벤트는 노드에 할당하고 컨테이너 이미지를 가져오는 등 포드 생성의 많은 기본 단계가 이미 완료되었음을 확인합니다. 이 정보를 통해 클러스터 인프라가 아닌 컨테이너의 앱 또는 구성에 조사를 집중할 수 있습니다.

CrashLoopBackOff 상태는 Kubernetes, 특히 kubelet이 포드의 다시 시작 정책에 따라 컨테이너 종료를 처리하는 방식 때문에 발생합니다. 이 주기는 일반적으로 다음 패턴을 따릅니다.

컨테이너가 시작됩니다.
컨테이너가 종료됩니다.
kubelet은 중지된 컨테이너를 관찰하고 포드의 restartPolicy에 따라 다시 시작합니다.
이 주기는 증가하는 지수 백오프 지연 후 컨테이너가 다시 시작되면서 반복됩니다.

이 동작의 핵심은 포드의 restartPolicy입니다. 기본 정책인 Always은 성공적으로 종료된 후에도 어떤 이유로든 종료되면 컨테이너를 다시 시작하므로 이 루프가 발생하는 가장 일반적인 원인입니다. OnFailure 정책은 0이 아닌 종료 코드에서만 다시 시작되므로 루프가 발생할 가능성이 적고 Never 정책은 다시 시작을 완전히 방지합니다.

`CrashLoopBackOff` 이벤트의 증상 식별

CrashLoopBackOff 상태의 포드는 CrashLoopBackOff 이벤트의 기본 표시입니다.

하지만 CrashLoopBackOff 이벤트의 명확하지 않은 증상이 발생할 수도 있습니다.

워크로드의 정상 복제본이 0개입니다.
정상 복제본이 급격히 감소합니다.
수평형 포드 자동 확장이 사용 설정된 워크로드가 느리게 확장되거나 확장되지 않습니다.

system 워크로드 (예: 로깅 또는 측정항목 에이전트)의 상태가 CrashLoopBackOff인 경우 다음과 같은 증상이 나타날 수도 있습니다.

일부 GKE 측정항목이 보고되지 않습니다.
일부 GKE 대시보드와 그래프에 간격이 있습니다.
포드 수준 네트워킹의 연결 문제

이러한 명확하지 않은 증상이 관찰되면 다음 단계로 CrashLoopBackOff 이벤트가 발생했는지 확인해야 합니다.

`CrashLoopBackOff` 이벤트 확인

CrashLoopBackOff 이벤트를 확인하고 조사하려면 Kubernetes 이벤트와 컨테이너의 앱 로그에서 증거를 수집하세요. 이 두 소스는 문제에 대한 서로 다른 보완적인 관점을 제공합니다.

Kubernetes 이벤트는 포드가 비정상 종료되고 있음을 확인합니다.
컨테이너의 앱 로그를 통해 컨테이너 내부의 프로세스가 실패하는 이유를 확인할 수 있습니다.

이 정보를 보려면 다음 옵션 중 하나를 선택하세요.

콘솔

Kubernetes 이벤트 및 앱 로그를 보려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 워크로드 페이지로 이동합니다.

워크로드로 이동
조사할 워크로드를 선택합니다. 개요 또는 세부정보 탭에 워크로드 상태에 관한 자세한 정보가 표시됩니다.
관리형 포드 섹션에서 문제가 있는 포드의 이름을 클릭합니다.
포드 세부정보 페이지에서 다음을 조사합니다.
- Kubernetes 이벤트에 대한 세부정보를 확인하려면 이벤트 탭으로 이동하세요.
- 컨테이너의 앱 로그를 확인하려면 로그 탭으로 이동합니다. 이 페이지에서는 앱 관련 오류 메시지 또는 스택 트레이스를 확인할 수 있습니다.

kubectl

Kubernetes 이벤트 및 앱 로그를 보려면 다음 단계를 따르세요.

클러스터에서 실행 중인 모든 포드의 상태를 확인합니다.
```
kubectl get pods
```
출력은 다음과 비슷합니다.
```
NAME       READY  STATUS             RESTARTS  AGE
POD_NAME   0/1    CrashLoopBackOff   23        8d
```
출력에서 다음 열을 검토합니다.
- Ready: 준비된 컨테이너 수를 검토합니다. 이 예에서 0/1은 예상 컨테이너 중 0개가 준비 상태임을 나타냅니다. 이 값은 문제의 명확한 신호입니다.
- Status: 상태가 CrashLoopBackOff인 포드를 찾습니다.
- Restarts: 값이 높으면 Kubernetes가 컨테이너를 시작하려고 반복적으로 시도하지만 실패하고 있음을 나타냅니다.

실패한 포드를 식별한 후 포드의 상태와 관련된 클러스터 수준 이벤트를 확인하기 위해 포드를 설명합니다.

kubectl describe pod POD_NAME -n NAMESPACE_NAME

다음을 바꿉니다.

POD_NAME: kubectl get 명령어의 출력에서 식별한 포드의 이름입니다.
NAMESPACE_NAME: 포드의 네임스페이스입니다.

출력은 다음과 비슷합니다.

Containers:
container-name:
...
  State:          Waiting
    Reason:       CrashLoopBackOff
  Last State:     Terminated
    Reason:       StartError
    Message:      failed to create containerd task: failed to create shim task: context deadline exceeded: unknown
    Exit Code:    128
    Started:      Thu, 01 Jan 1970 00:00:00 +0000
    Finished:     Fri, 27 Jun 2025 16:20:03 +0000
  Ready:          False
  Restart Count:  3459
...
Conditions:
Type                        Status
PodReadyToStartContainers   True
Initialized                 True
Ready                       False
ContainersReady             False
PodScheduled                True
...
Events:
Type     Reason   Age                     From     Message
----     ------   ----                    ----     -------
Warning  Failed   12m (x216 over 25h)     kubelet  Error: context deadline exceeded
Warning  Failed   8m34s (x216 over 25h)   kubelet  Error: context deadline exceeded
Warning  BackOff  4m24s (x3134 over 25h)  kubelet  Back-off restarting failed container container-name in pod failing-pod(11111111-2222-3333-4444-555555555555)

출력에서 다음 필드를 검토하여 CrashLoopBackOff 이벤트의 징후를 확인합니다.

State: 컨테이너 상태가 CrashLoopBackOff 이유로 Waiting을 표시할 수 있습니다.
Last State: 이전에 종료된 컨테이너의 상태입니다. Terminated 상태를 확인하고 종료 코드를 검토하여 비정상 종료 (0이 아닌 종료 코드)가 있었는지 또는 예기치 않은 성공적인 종료 (0 종료 코드)가 있었는지 확인합니다.
Events: 클러스터 자체에서 수행한 작업입니다. 컨테이너가 시작된 후 활성 프로브 실패 또는 Back-off restarting failed container와 같은 백오프 경고에 관한 메시지를 찾습니다.

포드가 실패한 이유를 자세히 알아보려면 앱 로그를 확인하세요.
```
kubectl logs POD_NAME --previous
```
--previous 플래그는 종료된 이전 컨테이너에서 로그를 가져오며, 여기에서 비정상 종료의 원인을 보여주는 특정 스택 트레이스나 오류 메시지를 확인할 수 있습니다. 현재 컨테이너가 너무 새 컨테이너라 기록된 로그가 없을 수 있습니다.

출력에서 프로세스가 종료되도록 하는 앱 관련 오류를 찾습니다. 맞춤 앱을 사용하는 경우 앱을 작성한 개발자가 이러한 오류 메시지를 가장 잘 해석할 수 있습니다. 미리 빌드된 앱을 사용하는 경우 이러한 앱은 자체 디버깅 안내를 제공하는 경우가 많습니다.

비정상 종료 루프 포드 대화형 플레이북 사용

CrashLoopBackOff 이벤트를 확인한 후 대화형 플레이북으로 문제 해결을 시작합니다.

Google Cloud 콘솔에서 GKE 대화형 플레이북 - 비정상 종료 루프 포드 페이지로 이동합니다.

비정상 종료 루프 포드로 이동
클러스터 목록에서 문제를 해결할 클러스터를 선택합니다. 클러스터를 찾을 수 없는 경우 필터 필드에 클러스터 이름을 입력합니다.
네임스페이스 목록에서 문제 해결을 원하는 네임스페이스를 선택합니다. 네임스페이스를 찾을 수 없는 경우 필터 필드에 네임스페이스를 입력합니다.
각 섹션을 살펴보면서 다음 질문에 답해 보세요.
1. 앱 오류 식별: 어떤 컨테이너가 다시 시작되나요?
2. 메모리 부족 문제 조사: 앱과 관련하여 잘못된 구성이나 오류가 있나요?
3. 노드 중단 조사: 노드 리소스에 컨테이너를 다시 시작하게 하는 중단이 있나요?
4. 활성 프로브 실패 조사: 활성 프로브가 컨테이너를 중지하나요?
5. 변경 이벤트 상관관계 파악: 컨테이너가 비정상 종료되기 시작할 무렵에 어떤 문제가 발생했나요?
선택사항: 향후 CrashLoopBackOff 이벤트에 관한 알림을 받으려면 향후 문제 완화 팁 섹션에서 알림 만들기를 선택합니다.

플레이북을 사용한 후에도 문제가 지속되면 가이드의 나머지 부분을 읽고 CrashLoopBackOff 이벤트 해결에 관해 자세히 알아보세요.

`CrashLoopBackOff` 이벤트 해결

다음 섹션에서는 CrashLoopBackOff 이벤트의 가장 일반적인 원인을 해결하는 방법을 설명합니다.

리소스 소진 (OOMKilled)
활성 프로브 실패
잘못 구성된 앱

리소스 소진 해결

CrashLoopBackOff 이벤트는 메모리 부족 (OOM) 문제로 인해 발생하는 경우가 많습니다. kubectl describe 출력에 다음이 표시되면 이 문제가 원인인지 확인할 수 있습니다.

Last State: Terminated
  Reason: OOMKilled

OOM 이벤트를 진단하고 해결하는 방법은 OOM 이벤트 문제 해결을 참고하세요.

활성 프로브 실패 해결

활성 프로브는 kubelet에서 실행하는 주기적인 상태 점검입니다. 프로브가 지정된 횟수만큼 실패하면 (기본 횟수는 3회) kubelet가 컨테이너를 다시 시작하여 프로브 실패가 계속되면 CrashLoopBackOff 이벤트가 발생할 수 있습니다.

활성 프로브가 원인인지 확인

활성 상태 프로브 실패로 인해 CrashLoopBackOff 이벤트가 트리거되는지 확인하려면 kubelet 로그를 쿼리하세요. 이러한 로그에는 프로브 실패와 후속 재시작을 나타내는 명시적 메시지가 포함되는 경우가 많습니다.

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동
쿼리 창에서 다음 쿼리를 입력하여 활성 프로브 관련 재시작을 필터링합니다.
```
resource.type="k8s_node"
log_id("kubelet")
jsonPayload.MESSAGE:"failed liveness probe, will be restarted"
resource.labels.cluster_name="CLUSTER_NAME"
```
CLUSTER_NAME을 클러스터 이름으로 바꿉니다.
출력을 검토합니다. 활성 프로브 실패가 CrashLoopBackOff 이벤트의 원인인 경우 쿼리는 다음과 유사한 로그 메시지를 반환합니다.
```
Container probe failed liveness probe, will be restarted
```

활성 상태 프로브가 CrashLoopBackOff 이벤트의 원인임을 확인한 후 일반적인 원인을 해결합니다.

활성 프로브 구성 검토
CPU 및 디스크 I/O 사용률을 검사합니다.
대규모 배포 해결
일시적인 오류 해결
프로브 리소스 소비 해결

활성 프로브 구성 검토

잘못 구성된 프로브는 CrashLoopBackOff 이벤트의 빈번한 원인입니다. 프로브의 매니페스트에서 다음 설정을 확인합니다.

프로브 유형 확인: 프로브의 구성은 앱에서 상태를 보고하는 방식과 일치해야 합니다. 예를 들어 앱에 상태 확인 URL (예: /healthz)이 있는 경우 httpGet 프로브 유형을 사용합니다. 명령어를 실행하여 상태를 확인하는 경우 exec 프로브 유형을 사용합니다. 예를 들어 네트워크 포트가 열려 있고 수신 대기 중인지 확인하려면 tcpSocket 프로브 유형을 사용합니다.
프로브 매개변수 확인:
- 경로 (httpGet 프로브 유형의 경우): HTTP 경로가 올바르고 앱이 상태 확인을 제공하는지 확인합니다.
- 포트: 프로브에 구성된 포트가 실제로 앱에서 사용되고 노출되는지 확인합니다.
- 명령어 (exec 프로브 유형의 경우): 명령어가 컨테이너 내에 있고, 성공 시 종료 코드 0을 반환하며, 구성된 timeoutSeconds 기간 내에 완료되는지 확인합니다.
- 제한 시간: 특히 시작 중이나 로드 시 앱이 응답하기에 timeoutSeconds 값이 충분한지 확인합니다.
- 초기 지연 (initialDelaySeconds): 프로브가 시작되기 전에 앱이 시작되기에 초기 지연이 충분한지 확인합니다.

자세한 내용은 Kubernetes 문서의 활성, 준비, 시작 프로브 구성을 참고하세요.

CPU 및 디스크 I/O 사용률 검사

리소스 경합으로 인해 프로브 시간 초과가 발생하며 이는 활성 프로브 실패의 주요 원인입니다. 리소스 사용량이 활성 프로브 실패의 원인인지 확인하려면 다음 해결 방법을 시도해 보세요.

CPU 사용량 분석: 프로브 간격 동안 영향을 받는 컨테이너와 컨테이너가 실행되는 노드의 CPU 사용률을 모니터링합니다. 추적해야 할 주요 측정항목은 kubernetes.io/container/cpu/core_usage_time입니다. 컨테이너나 노드의 CPU 사용량이 높으면 앱이 제때 프로브에 응답하지 못할 수 있습니다.
디스크 I/O 모니터링: 노드의 디스크 I/O 측정항목을 확인합니다. compute.googleapis.com/guest/disk/operation_time 측정항목을 사용하여 읽기 및 쓰기로 분류된 디스크 작업에 소요된 시간을 평가할 수 있습니다. 디스크 I/O가 높으면 컨테이너 시작, 앱 초기화 또는 전반적인 앱 성능이 크게 느려져 프로브 제한 시간이 초과될 수 있습니다.

대규모 배포 처리

많은 수의 포드가 동시에 배포되는 시나리오 (예: ArgoCD와 같은 CI/CD 도구)에서는 새 포드의 갑작스러운 급증으로 인해 클러스터 리소스가 과부하되어 제어 영역 리소스가 소진될 수 있습니다. 이러한 리소스 부족으로 인해 앱 시작이 지연되고 앱이 준비되기 전에 활성 프로브가 반복적으로 실패할 수 있습니다.

이 문제를 해결하려면 다음 솔루션을 시도해 보세요.

단계적 배포 구현: 노드 리소스가 과부하되지 않도록 포드를 일괄적으로 또는 더 긴 기간에 걸쳐 배포하는 전략을 구현합니다.
노드 재구성 또는 확장: 단계적 배포가 불가능한 경우 더 빠른 디스크나 더 큰 디스크 또는 Persistent Volume Claims로 노드를 업그레이드하여 증가한 I/O 수요를 더 잘 처리하는 것이 좋습니다. 클러스터 자동 확장이 적절하게 구성되어 있는지 확인합니다.
기다리며 관찰: 클러스터의 리소스가 심각하게 부족하지 않은 경우 워크로드가 상당한 지연(때로는 30분 이상) 후에 결국 배포될 수 있습니다.

일시적 오류 해결

앱이 시작 또는 초기화 중에 일시적인 오류나 속도 저하를 겪어 프로브가 처음에는 실패할 수 있습니다. 앱이 결국 복구되는 경우 활성 상태 프로브의 매니페스트에서 initialDelaySeconds 또는 failureThreshold 필드에 정의된 값을 늘리는 것이 좋습니다.

주소 프로브 리소스 소비

드문 경우지만 활성 프로브의 실행 자체가 상당한 리소스를 소비하여 리소스 제약이 트리거될 수 있으며, 이로 인해 OOM kill로 인해 컨테이너가 종료될 수 있습니다. 프로브 명령이 경량인지 확인하세요. 경량 프로브는 빠르고 안정적으로 실행될 가능성이 높으므로 앱의 실제 상태를 정확하게 보고하는 충실도가 높습니다.

앱 잘못된 구성 해결

앱 구성 오류로 인해 많은 CrashLoopBackOff 이벤트가 발생합니다. 앱이 중지되는 이유를 파악하려면 먼저 종료 코드를 검사해야 합니다. 이 코드는 문제 해결 경로를 결정합니다.

종료 코드 0는 성공적인 종료를 나타내며, 이는 장기 실행 서비스에서는 예상치 못한 결과이므로 컨테이너의 진입점이나 앱 설계에 문제가 있음을 나타냅니다.
0이 아닌 종료 코드는 앱 비정상 종료를 나타내므로 구성 오류, 종속 항목 문제 또는 코드의 버그에 집중해야 합니다.

종료 코드 찾기

앱의 종료 코드를 찾으려면 다음 단계를 따르세요.

포드를 설명합니다.
```
kubectl describe pod POD_NAME -n NAMESPACE_NAME
```
다음을 바꿉니다.
- POD_NAME: 문제가 있는 포드의 이름입니다.
- NAMESPACE_NAME: 포드의 네임스페이스입니다.
출력에서 Last State 섹션 아래에 있는 Exit Code 필드를 검토하여 관련 컨테이너를 확인합니다. 종료 코드가 0인 경우 성공적인 종료 문제 해결 (종료 코드 0)을 참고하세요. 종료 코드가 0이 아닌 다른 숫자이면 앱 비정상 종료 문제 해결 (0이 아닌 종료 코드)을 참고하세요.

성공적인 종료 문제 해결 (종료 코드 `0`)

종료 코드 0은 일반적으로 컨테이너의 프로세스가 성공적으로 완료되었음을 의미합니다. 이는 작업 기반 작업에 원하는 결과이지만 배포, StatefulSet 또는 ReplicaSet와 같은 장기 실행 컨트롤러의 문제일 수 있습니다.

이러한 컨트롤러는 포드가 항상 실행되도록 작동하므로 종료를 수정해야 하는 실패로 취급합니다. kubelet는 포드의 restartPolicy (기본값은 Always)를 준수하여 이 동작을 적용하고, 성공적으로 종료된 후에도 컨테이너를 다시 시작합니다. 이 작업은 루프를 생성하며, 이 루프는 궁극적으로 CrashLoopBackOff 상태를 트리거합니다.

예상치 못한 종료가 발생하는 가장 일반적인 이유는 다음과 같습니다.

컨테이너 명령어가 지속적인 프로세스를 시작하지 않음: 컨테이너는 초기 프로세스 (command 또는 entrypoint)가 실행되는 동안만 실행 상태로 유지됩니다. 이 프로세스가 장기 실행 서비스가 아닌 경우 명령어 완료 즉시 컨테이너가 종료됩니다. 예를 들어 ["/bin/bash"]와 같은 명령어는 실행할 스크립트가 없으므로 즉시 종료됩니다. 이 문제를 해결하려면 컨테이너의 초기 프로세스가 지속적으로 실행되는 프로세스를 시작해야 합니다.
작업 큐가 비어 있으면 작업자 앱이 종료됨: 많은 작업자 앱은 작업 큐를 확인하고 큐가 비어 있으면 깔끔하게 종료되도록 설계되어 있습니다. 이 문제를 해결하려면 완료될 때까지 실행되는 작업용으로 설계된 작업 컨트롤러를 사용하거나 앱의 로직을 수정하여 지속적인 서비스로 실행하면 됩니다.
누락되거나 잘못된 구성으로 인해 앱이 종료됨: 명령줄 인수, 환경 변수 또는 중요한 구성 파일과 같은 필수 시작 명령어가 누락되면 앱이 즉시 종료될 수 있습니다.

이 문제를 해결하려면 먼저 앱의 로그에서 구성 로드 또는 누락된 매개변수와 관련된 특정 오류 메시지를 검사하세요. 그런 다음 다음 사항을 확인합니다.
- 앱 인수 또는 환경: 필요한 모든 명령줄 인수와 환경 변수가 앱에서 예상한 대로 컨테이너에 올바르게 전달되는지 확인합니다.
- 구성 파일 존재: 필수 구성 파일이 컨테이너 내의 예상 경로에 있는지 확인합니다.
- 구성 파일 콘텐츠: 구성 파일의 콘텐츠와 형식을 검증하여 구문 오류, 필수 필드 누락, 잘못된 값이 있는지 확인합니다.
이 문제의 일반적인 예는 ConfigMap 볼륨으로 마운트된 파일에서 읽도록 앱이 구성된 경우입니다. ConfigMap가 연결되지 않았거나 비어 있거나 키 이름이 잘못 지정된 경우 구성이 누락될 때 종료되도록 설계된 앱이 종료 코드 0로 중지될 수 있습니다. 이 경우 다음 설정을 확인하세요. - 포드의 볼륨 정의에 있는 ConfigMap 이름이 실제 이름과 일치합니다. - ConfigMap 내의 키는 앱이 마운트된 볼륨에서 파일 이름으로 찾을 것으로 예상하는 항목과 일치합니다.

참고: 잘 설계된 앱은 필수 구성이 누락된 경우 0이 아닌 오류 코드로 종료되어야 하지만, 일부 앱은 이 상황에서 성공적으로 종료되도록 (코드 0) 작성됩니다.

앱 비정상 종료 문제 해결 (0이 아닌 종료 코드)

컨테이너가 0이 아닌 코드로 종료되면 Kubernetes가 컨테이너를 다시 시작합니다. 오류를 일으킨 기본 문제가 지속되면 앱이 다시 비정상 종료되고 주기가 반복되어 CrashLoopBackOff 상태가 됩니다.

0이 아닌 종료 코드는 앱 자체 내에서 오류가 발생했음을 명확하게 나타내므로 디버깅 노력을 내부 작동 및 환경으로 향하게 합니다. 다음과 같은 문제로 인해 종료되는 경우가 많습니다.

구성 오류: 0이 아닌 종료 코드는 앱의 구성 또는 실행 환경에 문제가 있음을 나타내는 경우가 많습니다. 앱에서 다음과 같은 일반적인 문제를 확인하세요.
- 구성 파일 누락: 앱이 필수 구성 파일을 찾거나 액세스하지 못할 수 있습니다.
- 잘못된 구성: 구성 파일에 구문 오류, 잘못된 값 또는 호환되지 않는 설정이 포함되어 앱이 비정상 종료될 수 있습니다.
- 권한 문제: 앱에 구성 파일을 읽거나 쓰는 데 필요한 권한이 없을 수 있습니다.
- 환경 변수: 환경 변수가 잘못되었거나 누락되면 앱이 오작동하거나 시작되지 않을 수 있습니다.
- 잘못된 entrypoint 또는 command: 컨테이너의 entrypoint 또는 command 필드에 지정된 명령어가 잘못되었을 수 있습니다. 이 문제는 실행 파일의 경로가 잘못되었거나 파일 자체가 컨테이너 이미지에 없는 새로 배포된 이미지에서 발생할 수 있습니다. 이 잘못된 구성으로 인해 128 종료 코드가 발생하는 경우가 많습니다.
- 제어되지 않는 이미지 업데이트 (:latest 태그): 워크로드 이미지가 :latest 태그를 사용하는 경우 새 포드가 호환성이 깨지는 변경사항이 도입된 업데이트된 이미지 버전을 가져올 수 있습니다.
  
  일관성과 재현성을 보장하려면 프로덕션 환경에서 항상 변경할 수 없는 특정 이미지 태그 (예: v1.2.3) 또는 SHA 다이제스트 (예: sha256:45b23dee08...)를 사용하세요. 이렇게 하면 매번 정확히 동일한 이미지 콘텐츠가 가져와집니다.
종속 항목 문제: 앱이 종속된 다른 서비스에 연결할 수 없거나, 인증에 실패하거나, 해당 서비스에 액세스할 권한이 부족한 경우 앱이 비정상 종료될 수 있습니다.
- 외부 서비스를 사용할 수 없음: 앱이 네트워크 연결 문제나 서비스 중단으로 인해 연결할 수 없는 외부 서비스 (예: 데이터베이스 또는 API)에 의존할 수 있습니다. 이 문제를 해결하려면 포드에 연결하세요. 자세한 내용은 Kubernetes 문서의 실행 중인 포드 디버그를 참고하세요.
  
  포드에 연결한 후 명령어를 실행하여 파일, 데이터베이스에 대한 액세스를 확인하거나 네트워크를 테스트할 수 있습니다. 예를 들어 curl과 같은 도구를 사용하여 서비스의 URL에 연결할 수 있습니다. 이 작업을 통해 문제가 네트워크 정책, DNS 또는 서비스 자체로 인해 발생하는지 확인할 수 있습니다.
- 인증 실패: 잘못된 사용자 인증 정보로 인해 앱이 외부 서비스로 인증하지 못할 수 있습니다. 컨테이너의 로그에서 401 Unauthorized(잘못된 사용자 인증 정보) 또는 403 Forbidden (권한 부족)과 같은 메시지를 검사합니다. 이러한 메시지는 포드의 서비스 계정에 외부 Google Cloud서비스 호출에 필요한 IAM 역할이 없음을 나타내는 경우가 많습니다.
  
  GKE 워크로드 아이덴티티 제휴를 사용하는 경우 주 구성원 식별자에 작업에 필요한 권한이 있는지 확인합니다. GKE 워크로드 아이덴티티 제휴를 사용하여 주 구성원에게 IAM 역할을 부여하는 방법에 대한 자세한 내용은 승인 및 주 구성원 구성을 참고하세요. 또한 GKE 메타데이터 서버의 리소스 사용량이 한도를 초과하지 않았는지 확인해야 합니다.
- 시간 초과: 앱이 외부 서비스의 응답을 기다리는 동안 시간 초과가 발생하여 비정상 종료될 수 있습니다.
앱 관련 오류: 구성 및 외부 종속 항목이 올바른 것 같으면 앱 코드에 오류가 있을 수 있습니다. 앱 로그에서 다음과 같은 일반적인 내부 오류를 검사합니다.
- 처리되지 않은 예외: 앱 로그에 처리되지 않은 예외 또는 기타 코드 관련 버그를 나타내는 스택 트레이스나 오류 메시지가 포함될 수 있습니다.
- 교착 상태 또는 라이브락: 여러 프로세스가 서로 완료되기를 기다리는 교착 상태에 앱이 멈춰 있을 수 있습니다. 이 시나리오에서는 앱이 종료되지 않지만 무기한 응답을 중지합니다.
- 포트 충돌: 앱이 다른 프로세스에서 이미 사용 중인 포트에 바인딩하려고 하면 시작되지 않을 수 있습니다.
- 호환되지 않는 라이브러리: 앱이 런타임 환경과 호환되지 않거나 누락된 라이브러리 또는 종속 항목에 의존할 수 있습니다.
근본 원인을 찾으려면 컨테이너의 로그에서 특정 오류 메시지 또는 스택 트레이스를 검사하세요. 이 정보는 앱 코드를 수정할지, 리소스 한도를 조정할지, 환경의 구성을 수정할지 결정하는 데 도움이 됩니다. 로그에 대한 자세한 내용은 GKE 로그 정보를 참고하세요.

다음 단계

문서에서 문제 해결 방법을 찾을 수 없으면 지원 받기를 참조하여 다음 주제에 대한 조언을 포함한 추가 도움을 요청하세요.
- Cloud Customer Care에 문의하여 지원 케이스를 엽니다.
- StackOverflow에서 질문하고 google-kubernetes-engine 태그를 사용하여 유사한 문제를 검색해 커뮤니티의 지원을 받습니다. #kubernetes-engine Slack 채널에 조인하여 더 많은 커뮤니티 지원을 받을 수도 있습니다.
- 공개 Issue Tracker를 사용하여 버그나 기능 요청을 엽니다.