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 주소 등은 모두 샘플 데이터이며, 실제 시스템 정보는 포함되어 있지 않습니다.