Configuring the Time Zone for Containers

Scenario

In containerized applications, containers use the Coordinated Universal Time (UTC) time zone by default. CCI uses the serverless architecture, and the underlying compute nodes are transparent to users, so they cannot synchronize the time zone of the nodes by mounting the /etc/localtime file of the nodes, like what they can do on CCE cluster nodes.

If your service requires a specific local time zone (for example, Asia/Shanghai), you are advised to configure the time zone using either of the following methods based on the image type:

• Method 1: Set the TZ environment variable (recommended). This method can be used for most standard images (such as CentOS, Ubuntu, Nginx, and Java). The configuration is simple and can be completed on the console or in YAML.
• Method 2: Mount a ConfigMap. This method is suitable for lightweight images (such as Alpine and Distroless). The time zone data file may not be available in such images, and you need to mount a ConfigMap.

(Recommended) Method 1: Setting the TZ Environment Variable

Most common images (including the tzdata package) support the TZ environment variable for defining the time zone.

• Scenario 1: Creating a workload
  1. Log in to the CCI 2.0 console.
  2. In the navigation pane, choose Workloads. On the Deployments tab, click Create Deployment.
  3. Add basic configuration. For details, see Creating a Deployment.
  4. Add containers.
     1. Click Add Container.
     2. Set the basic information. Click Next.
     3. In Advanced Settings, click the Environment Variables tab.
     4. Click Add Environment Variable.
        • Type: Custom
        • Variable Name: TZ
        • Variable/Variable Reference: Asia/Shanghai (For more time zones, see Appendix: Common Time Zones.)
  5. Complete the subsequent configuration and create the workload.

• Scenario 2: Updating an existing workload

  For workloads that are running in CCI or when batch configuration is required, you are advised to edit the YAML file to quickly add or modify the configuration.

  1. Locate the target workload in the workload list and click Edit YAML in the Operation column.
  2. In the YAML editor, search for the keyword image to find the service container configuration (usually containing the image and name fields).
  3. Add or modify the env field under the target container configuration.

     The following is an example YAML file:

     ...
     spec:
       template:
         spec:
           containers:
           - name: app-container
             image: nginx:latest
             # ---Add the following env configuration---
             env:
             - name: TZ
               value: Asia/Shanghai
             # -----------------------
     ...

     

     • If the time is still UTC time after the configuration, the image is a lightweight one, such as Alpine. In this case, use method 2.
     • Modifying the environment variable will trigger a rolling upgrade of the workload. The old pods will be destroyed, and the configuration will take effect after the new pods are started.

Method 2: Mounting a ConfigMap (for Lightweight Images)

If your image is extremely simplified (for example, a pure Go binary image or an Alpine image that does not have tzdata preinstalled), the /usr/share/zoneinfo directory may not exist in the container. In this case, setting the environment variable is invalid. You must mount the external time zone file to the workload.

• ccictl has been configured in the operating environment.
• A Linux OS is used (with the /usr/share/zoneinfo directory).

1. Create a ConfigMap.

   Use ccictl to create a ConfigMap as the local time zone file.

   (The following uses the Asia/Shanghai time zone as an example.)

   # Syntax: ccictl create configmap <name> --from-file=<Key><local-file-path> -n <namespace>
   ccictl create configmap timezone-config --from-file=localtime=/usr/share/zoneinfo/Asia/Shanghai -n namespace

2. Mount the ConfigMap to the workload.

   Edit the workload YAML and mount the ConfigMap to the /etc/localtime directory in the container.

   The following is an example YAML file:

   ...
   spec:
     template:
       spec:
         containers:
         - name: app-container
           image: alpine:latest
           volumeMounts:
           - name: tz-vol
             mountPath: /etc/localtime
             subPath: localtime  # [Key] subPath must be specified. Otherwise, other files in the /etc directory will be overwritten.
             readOnly: true
         volumes:
         - name: tz-vol
           configMap:
             name: timezone-config
   ...

Verification

After the configuration is complete, take the following steps to check whether the time zone takes effect:

1. Wait until the workload status changes to Running.
2. Use ccictl to access the container terminal.

   ccictl exec -it <pod-name> -n <namespace>

3. Run the date -R command.

   date -R

4. Check the command output. The output time should contain the corresponding time zone offset (like +0800 shown in the following).

   Fri, 27 Oct 2023 10:00:00 +0800

Appendix: Common Time Zones

The value of the TZ environment variable complies with the IANA time zone standard and is in the Region/City format. Configure the time zone based on site requirements.

Common Issues

Why does the TZ environment variable not take effect immediately after it is modified in the YAML file?

Modifying the environment variable will trigger a rolling upgrade. Wait until the old pods are terminated and the new pods are in the Running state.

Why is the TZ environment variable invalid in the Alpine image?

By default, Alpine does not contain the tzdata package and cannot parse the time zone string. You are advised to add RUN apk add --no-cache tzdata during image building or mount a ConfigMap to the workload.