Handling Timezone and System Time Issues in Linux Containers and Kubernetes

1. Background Overview

In a Linux environment, the operating system must be installed with the correct time zone for the current location. Official or third‑party container images often have an incorrect default time zone, which can cause time drift, wrong time zone, or the need for temporary time adjustments for special business scenarios such as e‑commerce flash sales.

2. Hardware Clock and System Time

Operating systems and containers obtain time from two sources: the hardware clock (RTC – Real Time Clock) and the OS system clock. The hardware clock runs independently of the CPU and continues ticking even when the server is powered off. It is known by many names such as hardware clock, real time clock, BIOS clock, CMOS clock, and is typically implemented with an RTC chip.

The system clock, which applications use, is represented as UTC seconds since 1970‑01‑01 00:00:00 UTC.

Relationship between hardware clock and system time

The hardware clock preserves time across reboots; during OS initialization the system reads the hardware clock value (RTC) and then runs independently.

The clock operation mechanism is illustrated below:

3. Modifying Time in Linux

Time can be represented by two standards: localtime (depends on the current time zone) and UTC (global standard, equivalent to GMT). Windows defaults to localtime , macOS to UTC , while UNIX‑like systems support both. For Linux it is recommended to set the hardware clock to UTC and use UTC everywhere, which allows automatic daylight‑saving adjustments.

Check the current configuration:

timedatectl status | grep local

Set the hardware clock to local time:

timedatectl set-local-rtc 1

Set the hardware clock to UTC:

timedatectl set-local-rtc 0

These commands generate /etc/adjtime automatically.

In everyday use, the date command changes the system date/time, and hwclock synchronizes the hardware clock.

4. Trying to Modify Time Inside a Container

Attempting to change the date or hardware clock from within a container fails because containers run with limited Linux capabilities. Adding --privileged or --cap-add SYS_TIME can bypass this, but it also changes the host’s time, which is not recommended.

The Linux kernel stores the timekeeper as a global variable; therefore, modifying time inside a container would affect the entire host system, which Docker deliberately prevents.

5. Various Ways to Handle Time in Containers

Before applying any solution, ensure the host node’s time and time zone are correctly synchronized.

5.1 Add Time Zone in Dockerfile

# Set timezone
RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
    && echo "Asia/Shanghai" > /etc/timezone

This is convenient for custom images.

5.2 Mount Time‑Zone File into a Pod

... 
  containers:
  - name: xxx
    ...
    volumeMounts:
    - name: timezone
      mountPath: /etc/localtime
  volumes:
  - name: timezone
    hostPath:
      path: /usr/share/zoneinfo/Asia/Shanghai

5.3 Define Time Zone via Environment Variable

Set the TZ variable in the pod spec:

... 
  containers:
  - name: xxx
    ...
    env:
    - name: TZ
      value: Asia/Shanghai

5.4 Use PodPreset to Inject TZ Globally (pre‑1.20 Kubernetes)

Enable the PodPreset feature via kube‑apiserver flags and admission controllers, then create a PodPreset object that sets TZ=Asia/Shanghai for all pods in a namespace.

apiVersion: settings.k8s.io/v1alpha1
kind: PodPreset
metadata:
  name: tz-env
spec:
  selector:
    matchLabels: {}
  env:
  - name: TZ
    values: Asia/Shanghai

5.5 Adjust Time to a Preset Value

When calibration is not enough, use a library such as libfaketime to intercept system calls via LD_PRELOAD and present an arbitrary time to applications.

Steps:

Clone and build the library: git clone https://github.com/wolfcw/libfaketime.git cd libfaketime && make install

Copy the compiled .so into the container: docker cp /usr/lib/x86_64-linux-gnu/faketime/libfaketime.so.1 :/usr/local/lib/

Set environment variables when running the container: export LD_PRELOAD=/usr/local/lib/libfaketime.so.1 FAKETIME="-5d"

To make this persistent in Kubernetes, add the library to the image and inject LD_PRELOAD and FAKETIME via the pod’s env section, or store the FAKETIME value in a ConfigMap and mount it as a volume.

apiVersion: v1
kind: ConfigMap
metadata:
  name: faketimerc
  namespace: default
data:
  faketimerc: |
    +10d

Then mount the ConfigMap as a volume and set the corresponding environment variables in the container.

See you ~

References

libfaketime: https://github.com/wolfcw/libfaketime

How to use the real‑time clock in Linux: https://developer.toradex.com/knowledge-base/how-to-use-the-real-time-clock-in-linux

Time and time zone article (Chinese): https://wiki.deepin.org/wiki/%E6%97%B6%E9%97%B4%E5%92%8C%E6%97%B6%E5%8C%BA

Kubernetes 1.20 deprecation notes: https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.20.md#deprecation