EKS CronJob에서 BackoffLimitExceeded 오류가 발생하는 원인과 해결 방법

EKS에서 CronJob 실행 시 다음과 같은 오류 메시지를 본 적 있으신가요?

[BackoffLimitExceeded] Job has reached the specified backoff limit

이 오류는 Kubernetes Batch Job이 실패했고, 설정된 최대 재시도 횟수를 초과했을 때 발생합니다. 이 글에서는 해당 에러가 발생하는 이유와, 실전에서 이를 어떻게 해결할 수 있는지 자세히 살펴봅니다.

🔍 오류 원인: backoffLimit 초과

BackoffLimitExceeded는 CronJob이 생성한 Job이 실패했으며, backoffLimit 설정에 도달했음을 의미합니다.

예를 들어 아래와 같은 CronJob YAML 설정이 있었다고 가정해봅니다:

spec:
  backoffLimit: 0

이 설정은 Job이 단 한 번이라도 실패하면 바로 중단되도록 합니다. 따라서 컨테이너가 실행 직후 오류를 내고 종료되면, Kubernetes는 더 이상 재시도하지 않고 바로 BackoffLimitExceeded 상태로 종료시킵니다.

⚠️ CronJob 예시와 주의할 점

containers:
  - command:
      - /bin/sh
      - -c
      - java -jar -Dspring.profiles.active=dev ...
    env:
      - name: SPRING_PROFILES_ACTIVE
        value: sample
    image: 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/sample-batch:latest

이처럼 복잡한 명령어와 많은 환경 변수에 의존하는 경우, 다음과 같은 문제가 발생할 수 있습니다:

환경 변수 누락
잘못된 이미지 태그
Volume 마운트 오류
Java 실행 시 예외 발생

🛠 해결 방법

1. backoffLimit 설정 수정

테스트 또는 운영 안정성을 위해, 다음과 같이 backoffLimit 값을 늘릴 수 있습니다:

spec:
  backoffLimit: 2

이 설정은 Job이 최대 2번까지 재시도되도록 합니다.

2. Job 로그 확인

실제 실패 원인을 파악하려면 로그 확인이 필수입니다.

kubectl logs job/<job-name> -n <namespace>

로그에서 Java 예외, 환경 변수 미설정, volume 마운트 실패 등의 원인을 찾을 수 있습니다.

3. 환경 변수 및 자원 확인

$SPRING_PROFILES_ACTIVE, $JAR_NAME 등 모든 환경 변수가 정상 주입되었는지 확인
Volume 마운트 경로 존재 여부 확인
컨테이너 리소스 제한에 의해 OOMKilled 되는지 확인

💡 추가 팁

테스트용 CronJob의 schedule을 "*/5 * * * *" 등으로 짧게 설정하여 반복 확인
ttlSecondsAfterFinished 값을 설정하면 실패 Job이 자동으로 정리되어 클러스터 자원 관리에 도움됨
concurrencyPolicy: Forbid 설정은 중복 실행 방지에 유용

📌 결론

EKS 환경에서 CronJob 실행 시 BackoffLimitExceeded 오류가 발생했다면, 단순히 재시도 횟수 초과 문제가 아니라, 실제 Job 실패 원인을 파악하는 것이 우선입니다. 로그 확인과 환경 변수 검토, 그리고 적절한 backoffLimit 설정을 통해 안정적인 운영이 가능합니다.

✅ 보안 주의사항

본 문서에 사용된 이미지 URL, 환경 변수, Volume 이름, Endpoint 주소 등은 모두 샘플 데이터이며, 실제 시스템 정보는 포함되어 있지 않습니다.