# 配置容器时区
#### 应用场景
在容器化应用中，容器默认使用UTC(协调世界时)时区。由于CCI采用Serverless架构，底层计算节点对用户透明，用户无法像使用传统CCE节点那样，通过挂载宿主机(Node)的/etc/localtime文件来同步宿主机时区。
如果您的业务需要使用特定的本地时区(如中国标准时间Asia/Shanghai)，建议根据镜像类型选择以下两种方式之一进行配置：
- **方式一：设置TZ环境变量(推荐)**：适用于大多数标准镜像(如CentOS、Ubuntu、Nginx、Java等)，配置简单，支持控制台图形化或YAML操作。
- **方式二：挂载ConfigMap**：适用于精简镜像(如Alpine、Distroless等)，此类镜像内部可能缺少时区数据文件，需手动挂载。
 
#### 方式一：设置TZ环境变量 (推荐)
绝大多数通用镜像(包含tzdata包)都支持通过环境变量TZ来定义时区。
- **场景一：新建工作负载**
  1. 登录[云容器实例 CCI2.0](https://console.huaweicloud.com/cci2.0/?#/cci/cluster/list)控制台。
  
  2. 左侧导航栏中选择"负载管理 \> 无状态负载"，在页面单击"创建工作负载"。
  
  3. 添加基础配置。具体操作请参见[通过控制台创建无状态负载](https://support.huaweicloud.com/usermanual-cci2/cci_01_0011.html#section0)。
  
  4. 添加容器配置。
     1. 单击"添加容器"。
     
     2. 填写基本信息。单击"下一步"。
     
     3. 在"高级设置"的"环境变量"页签。
     
     4. 单击"添加环境变量"。
        - **类型：**自定义
        
        - **变量名称**：TZ
        
        - **变量/变量引用** ：Asia/Shanghai(其他更多目标时区，请参见[附录：常用时区参数参考])。
         
      
  
  5. 完成后续配置并创建。
   

- **场景二：已有工作负载**
  对于CCI环境中已运行的工作负载，或者需要进行批量配置时，推荐通过"编辑YAML"方式快速追加配置。
  1. 在工作负载列表中，单击操作列的"编辑YAML"。
  
  2. 在YAML编辑器中，搜索关键字"image"，找到您的业务容器配置部分(通常包含image和name字段)。
  
  3. 在目标容器的配置下，添加或修改env字段。 **YAML示例：**
     ```
     ...
     spec:
       template:
         spec:
           containers:
           - name: app-container
             image: nginx:latest
             # --- 添加以下env配置 ---
             env:
             - name: TZ
               value: Asia/Shanghai
             # -----------------------
     ...
     ```
     ![](https://support.huaweicloud.com/bestpractice-cci2/public_sys-resources/note_3.0-zh-cn.png)
     - 如果配置后时间仍为UTC，说明您的镜像是Alpine等精简版，请使用方式二。
     
     - 修改环境变量会触发工作负载的滚动升级，旧实例将被销毁，新实例启动后配置即生效。
       
   
 
#### 方式二：挂载ConfigMap(适用于精简镜像)
如果您的镜像极度精简(例如纯Go二进制镜像或某些未预装tzdata的Alpine镜像)，容器内可能不存在/usr/share/zoneinfo目录，此时设置环境变量无效，必须将外部的时区文件挂载进去。
- 操作环境已配置ccictl命令行工具。
- 操作环境为Linux系统(具备/usr/share/zoneinfo目录)。
1. 创建ConfigMap。 使用 ccictl 命令行，直接将本地的时区文件创建为 ConfigMap。
   *(以创建上海时区配置为例)*
   ```
   # 语法：ccictl create configmap <名称> --from-file=<Key>=<本地文件路径> -n <命名空间>
   ccictl create configmap timezone-config --from-file=localtime=/usr/share/zoneinfo/Asia/Shanghai -n namespace
   ```
   

2. 挂载到工作负载 通过YAML编辑工作负载，将该ConfigMap挂载到容器的/etc/localtime。
   YAML示例
   ```
   ...
   spec:
     template:
       spec:
         containers:
         - name: app-container
           image: alpine:latest
           volumeMounts:
           - name: tz-vol
             mountPath: /etc/localtime
             subPath: localtime  # [关键]必须使用subPath，否则会覆盖/etc目录下的其他文件
             readOnly: true
         volumes:
         - name: tz-vol
           configMap:
             name: timezone-config
   ...
   ```
   
 
#### 验证方法
配置完成后，请按照以下步骤验证时区是否生效：
1. 等待工作负载状态变为"运行中"。
2. 使用 ccictl 进入容器终端。
   ```
   ccictl exec -it <Pod名称> -n <命名空间>
   ```
   
3. 执行date -R命令。
   ```
   date -R
   ```
   
4. **预期结果** ：输出时间应包含对应的时区偏移量(类似如下所示+0800)
   ```
   Fri, 27 Oct 2023 10:00:00 +0800
   ```
   
 
 #### 附录：常用时区参数参考
TZ环境变量的值遵循IANA时区标准，格式为区域/城市。请根据实际情况进行选择。
| **区域**                                       | **常用城市**/标准 | **TZ变量值**           | **说明**                                |
|:---|:---|:---|:---|
| **通用**                                       | UTC         | UTC                 | 默认值。                                  |
| **中国**                                       | 上海          | Asia/Shanghai       | 中国标准时间(CST)。不建议使用Asia/Beijing(非标准路径)。 |
| **北美**  | 纽约          | America/New_York    | 美国东部时间。注意大小写。                         |
| **北美**  | 洛杉矶         | America/Los_Angeles | 美国西部时间。                               |
| **欧洲**  | 伦敦          | Europe/London       | 英国时间。                                 |
| **欧洲**  | 柏林          | Europe/Berlin       | 欧洲中部时间。                               |
| **亚太**    | 东京          | Asia/Tokyo          | 日本标准时间。                               |
| **亚太**    | 新加坡         | Asia/Singapore      | 新加坡时间。                                |
   
#### 常见问题
**为什么我设置了Asia/Beijing时区不生效？**
Linux标准的时区数据库中，中国标准时间的规范标识符是Asia/Shanghai。虽然部分发行版兼容Asia/Beijing，但在大多数容器镜像中仅存在Asia/Shanghai。请始终使用Asia/Shanghai。
**为什么修改了YAML中的TZ变量后，业务没有立即生效？**
修改环境变量会触发**滚动升级**。请等待旧Pod终止、新Pod状态变为"运行中"后再进行验证。
**为什么在Alpine镜像中设置TZ环境变量无效？**
Alpine默认不包含tzdata包，无法解析时区字符串。建议在构建镜像时添加RUN apk add --no-cache tzdata，或使用ConfigMap挂载方式。