Tick-tock. Does your container know what time it is?

Traditionally, Linux computer systems are installed on a physical or virtual machine, and one of the questions asked during the install is: What time zone is the machine is running in? The installer sets up a link between /etc/localtime and a time zone file. On my Fedora machine, I see the following link:

$ ls -l /etc/localtime
lrwxrwxrwx. 1 root root 38 Feb 29 13:11 /etc/localtime -> ../usr/share/zoneinfo/America/New_York

When you ask the system what time it is, the glibc library reads this link to display the time based on the time zone.

$ date
Tue 11 Aug 2020 03:57:43 PM EDT

If I force a change to this file to point at Japan, the way the date is reported changes:

$ ln -fs ../usr/share/zoneinfo/Japan /etc/localtime
$ date
Wed 12 Aug 2020 04:58:59 AM JST

Problem: Container images have an embedded time zone

When container engines like Podman, Docker, or CRI-O run containers, they pull down the specified OCI image from a container registry. This image is built with a hardcoded link from /etc/localtime to one time zone. Usually, the time zone is set to the location where the image or base image was built, or to UTC±00:00. There is no installation process to modify the time zone. Once the image is pulled, the container engine just launches the container based on the hardcoded time zone. This means that your container running in Tokyo could be reporting that it is running in New York City, depending on where the image was built.

Users have attempted to fix this by mounting the time zone file from the host into the container or by adding an environment variable like TZ=jst. These attempts have caused problems since the /etc/localtime file is often a symbolic link and may not do what the user expects. The TZ environment variable is also a problem since not all services pay attention to the variable, causing users to become confused due to different outcomes to the same setting. For example, Fedora images accept the environment variable, while Alpine images ignore it entirely.

Additionally, some time zones even share the same abbreviation, such as CST standing both for Central Standard time (in the US) and China Standard time. Given all that, there was no easy way to change the system to cause ALL containers to use the desired time zone.

Podman (2.1) adds the --tz flag

The --tz flag takes IANA time zones as well as local. The reserved word local sets the time zone to match your host machine's time zone.

Taking a look at the podman-run man page, we can see the new --tz option:

$ man podman-run
…
--tz=time zone

Set a time zone in the container. This flag takes area-based time zones, GMT, as well as local, which sets the time zone in the container to match the host machine. See /usr/share/zoneinfo/ for valid time zones.

And here are some examples of it in action:

$ date
Tue Aug 11 16:48:10 EDT 2020

$ podman run --tz=local alpine date
Tue Aug 11 16:48:27 EDT 2020

$ podman run --tz=Asia/Shanghai alpine date
Wed Aug 12 04:48:42 CST 2020

$ podman run --tz=US/Eastern alpine date
Tue Aug 11 16:48:47 EDT 2020

This flag is also available in the podman create command.

How does it work?

Setting a time zone works the same on rootful and rootless containers. Functionally, the time zone flag mounts a copy of your specified time zone file found in /usr/share/zoneinfo as /etc/localtime, thus setting the time zone in the container. If the specified time zone is local (or happens to be a symlink, as some time zone files are simply a symlink to another file), the flag follows the symlink and mounts the pointed-to file. This solves the symlink and environment variable problems that users may have previously encountered. The time zone setting is permanent for the life of the container.

I don't want to specify this flag for every container I run?

Administrators and users can set a system-wide default time zone for all of their containers using containers.conf. This ensures that every container created on your system has the specified time zone set unless overridden by the command line. Setting the time zone within containers.conf is helpful if you want to consistently make containers with the same time zone, alleviating the need to use the flag every time a container is created or run.

$ cat $HOME/.config/containers/containers.conf
[containers]
# Set time zone in container. Takes IANA time zones as well as "local",
# which sets the time zone in the container to match the host machine.
#
tz = "Europe/London"

$ podman run alpine date
Tue Aug 11 21:54:21 BST 2020

Note: containers.conf is located at /usr/share/containers/containers.conf and /etc/containers/containers.conf for rootful mode and at $HOME/.config/containers/containers.conf for rootless mode.

Conclusion

The time zone flag makes it easy and foolproof to set the time in a container to your personal needs, without fussing with mounts, symlinks, and environment variables. Setting a time zone in containers.conf allows you to "set it and forget it" for all of your containers.

Now go on your merry way and travel the world: all within your container.

[ Getting started with containers? Check out this free course. Deploying containerized applications: A technical overview. ]