Container Timezone 설정

1. 개요

컨테이너 환경에서 타임존(Timezone)이 맞지 않으면 로그 시간이 어긋나고 스케줄러가 잘못된 시간에 동작한다. 대수롭지 않게 넘겼다가 나중에 디버깅이 복잡해지는 경우가 많으므로, 컨테이너 타임존 설정 방법을 정리해 두었다.

2. 이슈

쿠버네티스(Kubernetes) 상에 동작 중인 파드(Pod)마다 서로 다른 timezone을 가지고 있었고, 이를 GMT+9 (Asia/Seoul)로 일괄 변환하는 방법이 필요했다.

3. 해결

컨테이너의 타임존을 설정하는 주요 방법은 다음과 같다.

1. Dockerfile을 통한 설정 (Build-time)

컨테이너 이미지를 빌드하는 시점에 Dockerfile 내에서 타임존을 설정하는 방법이다. 이 방법은 컨테이너가 시작될 때마다 별도의 설정 없이 일관된 타임존을 보장하여 가장 권장되는 방식 중 하나이다.

• 원리: 대부분의 Linux 시스템은 /etc/timezone 파일에 타임존 정보를 저장하거나, /etc/localtime 파일이 실제 타임존 데이터 파일(예: /usr/share/zoneinfo/Asia/Seoul)을 가리키는 심볼릭 링크로 구성된다. tzdata 패키지는 이러한 타임존 데이터 파일을 제공한다. ENV TZ 명령어는 컨테이너 내부의 환경 변수를 설정하여 시스템이 해당 타임존을 사용하도록 지시한다.

# 예시: Ubuntu/Debian 기반 이미지
FROM ubuntu:latest
 
# tzdata 패키지 설치 (타임존 데이터 제공)
# noninteractive 모드로 설치하여 사용자 입력 없이 진행
RUN apt-get update && apt-get install -y tzdata && rm -rf /var/lib/apt/lists/*
 
# 환경 변수 TZ를 Asia/Seoul로 설정
ENV TZ=Asia/Seoul
 
# 애플리케이션 실행 명령어 (예시)
CMD ["/bin/bash"]

이식성은 가장 좋지만, 타임존을 바꿀 때마다 이미지를 다시 빌드해야 한다. 납품 환경마다 타임존이 다를 수 있으니 필자는 잘 쓰지 않는다.

2. Volume Mount를 통한 설정 (Run-time)

호스트 시스템의 타임존 정보를 컨테이너 내부로 마운트하여 사용하는 방법이다. 이 방법은 컨테이너 이미지를 수정하지 않고 런타임에 타임존을 유연하게 설정할 수 있다.

• 원리: 호스트 시스템의 /etc/localtime 파일 또는 /usr/share/zoneinfo 디렉토리를 컨테이너 내부의 /etc/localtime 경로로 마운트한다. 컨테이너는 마운트된 호스트의 타임존 정보를 사용하게 된다.

Docker CLI

$ docker run -d \
  -v /etc/localtime:/etc/localtime:ro \
  -v /usr/share/zoneinfo/Asia/Seoul:/etc/localtime:ro # 특정 타임존 파일 마운트 (더 명시적)
  your-image-name

• /etc/localtime:/etc/localtime:ro: 호스트의 현재 타임존 설정을 컨테이너로 읽기 전용(read-only)으로 마운트한다.
• /usr/share/zoneinfo/Asia/Seoul:/etc/localtime:ro: 호스트의 특정 타임존 데이터 파일(Asia/Seoul)을 컨테이너의 /etc/localtime로 마운트한다. 이 방법은 호스트의 현재 타임존 설정과 무관하게 컨테이너에 특정 타임존을 강제할 때 유용하다.

Kubernetes 환경

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
      - name: my-container
        image: your-image-name
        volumeMounts:
        - name: tz-config
          mountPath: /etc/localtime # /etc/localtime 파일을 마운트
          readOnly: true
      volumes:
      - name: tz-config
        hostPath:
          path: /usr/share/zoneinfo/Asia/Seoul # 호스트의 Asia/Seoul 타임존 파일을 사용
          type: File # 파일임을 명시

• 장점:
  • 이미지 재빌드 없이 런타임에 타임존을 변경할 수 있다.
  • 호스트의 타임존과 동기화하거나, 호스트에 존재하는 특정 타임존 파일을 선택하여 사용할 수 있다.
• 단점:
  • 컨테이너가 호스트 시스템에 의존하게 된다. 호스트의 타임존 설정이 변경되면 컨테이너에도 영향을 미친다.
  • hostPath 사용 시 노드 간 이식성이 저하될 수 있다 (모든 노드에 동일한 타임존 파일이 존재해야 한다).
  • 보안상의 이유로 hostPath 사용을 제한하는 환경도 있다.

3. 환경 변수 TZ만 설정 (Run-time)

컨테이너 이미지에 이미 tzdata 패키지가 설치되어 있는 경우, TZ 환경 변수만 설정하여 타임존을 변경할 수 있다.

• 원리: TZ 환경 변수는 C 라이브러리(glibc)에서 시간을 처리할 때 참조하는 타임존을 지정한다. tzdata 패키지가 설치되어 있다면, /usr/share/zoneinfo 경로에 다양한 타임존 데이터 파일이 존재하며, TZ 변수는 이 중 어떤 파일을 사용할지 알려주는 역할을 한다.

Docker CLI

$ docker run -d \
  -e TZ=Asia/Seoul \
  your-image-name

Kubernetes 환경

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
      - name: my-container
        image: your-image-name
        env:
        - name: TZ
          value: Asia/Seoul

가장 간단하고 유연해서 필자가 주로 쓰는 방법이다. tzdata만 이미지에 들어있으면 환경변수 하나로 끝난다. 다만 tzdata가 없으면 TZ가 무시되고 UTC로 떨어지니, 베이스 이미지에 포함되어 있는지 확인이 필요하다.

4. timedatectl 명령어 사용 (컨테이너 내부)

일부 컨테이너 이미지에는 systemd가 포함되어 있지 않아 timedatectl 명령어를 직접 사용할 수 없는 경우가 많다. 하지만 디버깅 목적이나 특정 베이스 이미지에서는 유용할 수 있다.

# 컨테이너 내부에서 실행 (예시)
$ docker exec -it <container_id> /bin/bash
# 컨테이너 쉘 내부에서
$ timedatectl set-timezone Asia/Seoul

대부분의 경량 컨테이너에는 systemd가 없어서 이 명령어를 사용할 수 없다. 재시작하면 설정도 유지되지 않으므로 디버깅 용도 외에는 의미가 없다.

4. 확인

컨테이너 내부에서 타임존이 올바르게 설정되었는지 확인하는 방법이다.

# date 명령어 사용
$ date
Tue Nov 22 07:44:20 KST 2022 # 예시 출력: KST (한국 표준시)로 표시되었다.
 
# timedatectl 명령어 사용 (timedatectl이 설치된 경우)
$ timedatectl
               Local time: 화 2022-11-22 07:44:20 KST
           Universal time: 월 2022-11-21 22:44:20 UTC
                 RTC time: 월 2022-11-21 22:44:20
                Time zone: Asia/Seoul (KST, +0900)
System clock synchronized: yes
              NTP service: active
          RTC in local TZ: no

요약

방법	장점	단점	권장 시나리오
Dockerfile	이미지에 타임존 내장, 이식성 높음, 일관된 설정 보장	이미지 재빌드 필요, 이미지 크기 약간 증가	대부분의 프로덕션 환경, 일관된 타임존이 필요한 경우
Volume Mount	이미지 재빌드 불필요, 런타임 유연성, 호스트와 동기화 가능	호스트 의존성, 노드 간 이식성 저하, hostPath 보안 문제	런타임에 타임존 변경이 잦거나 호스트와 동기화가 필요한 경우
환경 변수 TZ	가장 간단, 이미지 재빌드 불필요, 런타임 유연성	tzdata 설치 필수, 설치되지 않은 경우 기본 UTC	tzdata가 포함된 경량 이미지 사용 시, 간단한 설정
timedatectl	컨테이너 내부에서 직접 설정 가능	대부분의 경량 이미지에서 사용 불가, 컨테이너 재시작 시 설정 유지 안됨, 디버깅 목적 외 비권장	디버깅 목적, 특정 베이스 이미지 사용 시

참고

• https://dev.to/0xbf/set-timezone-in-your-docker-image-d22
• Docker 공식 문서: Configure timezone (ENV 명령어 관련)
• Kubernetes 공식 문서: Volumes - hostPath (hostPath 관련)
• Linux man page: tzset(3) (TZ 환경 변수 관련)