Kubernetes CronJob timeZone: DST 처리·UnknownTimeZone·검증 방법

.spec.timeZone은 CronJob 스케줄을 어느 시간대로 해석할지 정하는 필드입니다. 서버의 시간대와 원하는 실행 시간대가 다르거나 DST(서머타임)가 적용된다면, 설정값뿐 아니라 실제 예약 시각도 살펴봐야 합니다.

시간대 필드는 Kubernetes v1.27부터 안정화됐습니다. 아래 예제는 테스트 클러스터에서 설정과 예약 시각을 확인하는 용도입니다.

이 글에서 바로 찾기 9개 항목

DST 전후의 실행 시각 확인하기

DST 전환일에는 현지 시각이 건너뛰거나 반복되는 구간이 있습니다. .spec.timeZone: "Europe/Berlin"처럼 DST가 있는 시간대를 쓴다면 전환일 전후의 예약 시각과 실제 생성된 Job을 비교할 필요가 있습니다.

.spec.timeZone은 무엇을 바꾸나요?

.spec.timeZone을 설정하면 CronJob 컨트롤러는 스케줄 문자열을 그 시간대로 해석합니다. 지정하지 않으면 kube-controller-manager 프로세스의 로컬 시간대를 사용합니다.

원인과 설계 이유

중복·누락의 주요 원인:

CronJob은 예약 시각마다 정확히 한 번 실행된다고 보장하지 않습니다. 중복 생성이나 누락에 대비해 Job 자체도 반복 실행에 안전하게 설계해야 합니다.
잘못된 시간대 이름을 설정하면 컨트롤러가 이벤트 UnknownTimeZone을 발생시키고 잡을 생성하지 않을 수 있습니다.
여러 CronJob이 서로 다른 시간대지만 실제 UTC 시점이 겹치면 동시 부하가 생깁니다(운영상 부하 주의).

테스트 클러스터에 적용할 예제

v1.27 이상 클러스터와 kubectl 접근 권한이 필요합니다. 운영 환경에 적용하기 전 스테이징에서 검증하는 예제입니다.

1. 매니페스트 작성

apiVersion: batch/v1
kind: CronJob
metadata:
  name: tz-demo-cronjob
  namespace: <your-namespace>
spec:
  schedule: "30 2 * * *"   # 매일 02:30 (현지 해석)
  timeZone: "Europe/Berlin"  # DST가 적용되는 예시
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
          - name: tz-demo
            image: busybox
            args:
            - /bin/sh
            - -c
            - date; echo Scheduled from $CRON_SCHEDULE
            env:
            - name: CRON_SCHEDULE
              value: "30 2 * * *"

Europe/Berlin을 지정하면 스케줄은 CET/CEST 규칙을 따릅니다. <your-namespace>는 실제 사용할 네임스페이스 이름으로 바꿉니다.

2. 배포 후 설정 조회

kubectl apply -f cronjob-tz.yaml
kubectl get cronjob tz-demo-cronjob -n <your-namespace> -o yaml
kubectl describe cronjob tz-demo-cronjob -n <your-namespace>

출력에서는 다음 항목을 살펴봅니다.

.spec.timeZone에 지정한 값이 들어 있는지 확인합니다.
Events에 UnknownTimeZone이 있다면 시간대 이름과 관련 오류를 살펴봅니다.
v1.32 이상에서는 생성된 Job의 batch.kubernetes.io/cronjob-scheduled-timestamp 어노테이션으로 원래 예약된 시각을 볼 수 있습니다.

이벤트 메시지 예시

Events:
  Type    Reason           Age    From                Message
  ----    ------           ----   ----                -------
  Normal  SuccessfulCreate  2m     cronjob-controller  Created job tz-demo-cronjob-xxxxx
  Warning UnknownTimeZone  1m     cronjob-controller  Invalid TimeZone "Europe/BerlinX": location not found

위 메시지는 설명용 예시이며, 실제 문구는 버전에 따라 다를 수 있습니다. 시간대에는 Europe/Berlin, Asia/Seoul 같은 유효한 IANA 이름을 사용합니다.

검증 및 진단 체크리스트

Kubernetes CronJob timeZone 검증 체크리스트 요약 인포그래픽

이미지 내용 텍스트로 보기

IANA tz 이름 확인
UnknownTimeZone 이벤트 없음
어노테이션으로 예약시각 검증
cron_job_creation_skew 확인

UnknownTimeZone 이벤트: kubectl describe cronjob에서 이벤트 확인. 있으면 TZ 이름 수정 또는 CronJob 일시 중지(.spec.suspend) 권고.
스케줄 일관성: v1.32 이상에서는 Job의 batch.kubernetes.io/cronjob-scheduled-timestamp와 실제 생성 시각을 비교합니다.
컨트롤러 로그: kube-controller-manager 로그에서 “TimeZone” 관련 경고/오류를 검색. 로그 레벨을 올려 상세 원인 진단 가능.
실행 지연: 사용 중인 버전이 제공하는 컨트롤러 지표와 Job 생성 시각을 함께 봅니다. 허용 지연은 업무의 실행 주기와 요구사항에 맞춰 정합니다.

대안과 운영 권장사항

구형 클러스터(v1.26 이하 또는 타임존 기능 비활성화 환경): kube-controller-manager의 로컬 타임존을 운영팀이 명확히 관리하거나, 파드 내부에서 cron을 실행해 애플리케이션 레벨로 시간대 제어(운영 부담 증가)를 고려.
concurrencyPolicy는 같은 CronJob이 만든 Job 사이에만 적용됩니다. 여러 CronJob이 동시에 실행되는 부하는 실행 시각과 리소스 쿼터를 별도로 검토해야 합니다.
시간대 데이터(Go tz DB)가 오래된 경우, kube-controller-manager 또는 kube-apiserver 빌드를 업그레이드하거나 외부 tz 패키지 설치를 검토(KEP에 관련 제안 있음).

설정값보다 실제 예약 시각이 중요합니다

시간대 이름이 올바르더라도 기대한 시각에 실행되는지는 별도 확인이 필요합니다. 이벤트와 생성된 Job을 비교하고, DST를 사용하는 환경은 전환일 전후도 점검 대상으로 둡니다.

공식 문서: CronJob concept (v1.36) · KEP-3140 TimeZone support

자주 묻는 질문

.timeZone을 설정하면 DST 전환 시 자동으로 안전한가요?

시간대 규칙을 적용하는 설정이지 정확히 한 번 실행을 보장하는 기능은 아닙니다. DST 전후의 예약 시각을 점검하고, 작업이 중복 실행돼도 문제가 없도록 설계할 필요가 있습니다.

UnknownTimeZone 이벤트를 보면 어떻게 대처하나요?

지정한 IANA 시간대 이름과 컨트롤러 로그부터 확인합니다. 일시 중지에는 .spec.suspend: true를 쓸 수 있지만, 재개할 때 누락된 예약이 실행될 수 있어 마감 시간 설정도 함께 검토해야 합니다.

구형 쿠버네티스에서 대체할 방법은 무엇인가요?

컨트롤러의 로컬 시간대를 관리하거나, 애플리케이션 안의 cron 또는 외부 스케줄러를 사용하는 방법이 있습니다. 지원 버전과 권한, 장애 대응 부담을 비교해 선택할 수 있습니다.

Kubernetes CronJob 시간대(timeZone) 정리 — DST·UnknownTimeZone·검증 방법