mcpField
K
k8s-timezone-config

k8s-timezone-config

github.com/julianobarbosa云与 DevOps1498 次安装2 天前更新
代码仓库

关于 k8s-timezone-config

为使用 Kubernetes 的基础设施团队提供将 Pod 内应用时间设为巴西圣保罗时区的配置指南。涵盖 Helm、Deployment 和 StatefulSet，并说明验证方法及常见限制。

主要功能

  1. 01通过 TZ 设置容器时区
  2. 02涵盖 Helm 与原生资源配置
  3. 03指导检查 Pod 内时间
  4. 04说明 CronJob 时区限制
  5. 05列出镜像与应用的注意事项

适用场景

  1. 01统一 Pod 内应用的本地时间戳
  2. 02为多容器 Pod 配置时区
  3. 03排查应用时间仍显示 UTC 的问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/julianobarbosa/claude-code-skills --skill k8s-timezone-config

安装后在 Claude Code 中输入/k8s-timezone-config确认已加载。

详细介绍

Kubernetes Pod 时区配置

贵组织基础设施的标准时区： America/Sao_Paulo

问题

Kubernetes Pod 默认以 UTC 运行。日志和应用程序时间戳显示的偏移量是 +0000，而不是巴西当地时间（-0300）。

解决方案

在容器规格中添加 TZ 环境变量。

实现模式

1. Helm Values（extraEnv 模式）

适用于支持 extraEnv 的 Helm Chart：

# In values.yaml
extraEnv:
  - name: TZ
    value: America/Sao_Paulo
2. 多个容器

当一个 Deployment 包含多个容器（例如，API 服务器 + 前端）时，请在所有容器中添加 TZ：

apiServer:
  extraEnv:
    - name: TZ
      value: America/Sao_Paulo

frontend:
  extraEnv:
    - name: TZ
      value: America/Sao_Paulo
3. 原生 Kubernetes Deployment
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          env:
            - name: TZ
              value: America/Sao_Paulo
4. StatefulSet
apiVersion: apps/v1
kind: StatefulSet
spec:
  template:
    spec:
      containers:
        - name: app
          env:
            - name: TZ
              value: America/Sao_Paulo

验证

部署后，验证时区是否设置正确：

# Check pod logs for timestamp offset
# Before: 2026-01-13T11:37:06 +0000
# After:  2026-01-13T08:37:06 -0300

# Or exec into pod
kubectl exec -it <pod-name> -n <namespace> -- date
# Should show: Mon Jan 13 08:37:06 -03 2026

需要配置时区的常见应用程序

应用程序配置位置说明
Dependency-TrackapiServer.extraEnv + frontend.extraEnv两个容器都需要设置 TZ
Grafanaenv 或 extraEnvVars单个容器
LokiextraEnv影响日志时间戳
Prometheusserver.env影响告警时间戳
DefectDojoextraEnvDjango 应用
PostgreSQLprimary.extraEnvVars数据库时间戳

重要说明

  1. 需要重启：Pod 必须重启，TZ 更改才会生效
  2. 所有容器：为 Pod 中的所有容器设置 TZ，包括 Sidecar
  3. Init 容器：如果 Init 容器会记录时间戳，也要为其设置 TZ
  4. Cron Job：Kubernetes CronJob 的调度始终使用 UTC——TZ 只影响容器级别的时间

贵组织的 GitOps 工作流

  1. 编辑 argo-cd-helm-values/kube-addons/<service>/<cluster>/values.yaml 中的 values.yaml
  2. 为所有容器添加 TZ 环境变量
  3. 提交并推送（ArgoCD 会自动同步）
  4. 验证 Pod 是否已在新时区下重启

参考

  • IANA 时区数据库：America/Sao_Paulo = UTC-3（自 2019 年起不实行夏令时）
  • Linux TZ 变量：使用 /usr/share/zoneinfo/America/Sao_Paulo

注意事项

  • TZ 环境变量只影响应用级别的时间戳，不影响 kubectl logs 的时间戳（这些时间戳来自容器运行时，容器运行时仍使用 UTC）。即使 Pod 内部时钟已设为圣保罗时间，kubelet 时间戳仍为 +0000。
  • CronJob 的 schedule: 始终使用 UTC，不受 Pod 的 TZ 影响。0 8 * * * 计划会在巴西利亚时间（BRT）05:00 触发，而不是 08:00。请在 CronJob 本身使用 spec.timeZone: America/Sao_Paulo（K8s 1.27+），或手动计算 UTC 偏移量。
  • Distroless 和 scratch 镜像不包含 /usr/share/zoneinfo——TZ=America/Sao_Paulo 会静默回退到 UTC。请使用包含 tzdata 的基础镜像，或通过 configMap/volume 挂载。
  • 在较旧的 Chart 中，Init 容器不会继承主容器的 TZ——请单独在 Init 容器规格中设置，否则其迁移日志仍会使用 UTC。
  • 除 TZ 外，Java 应用还需要在 JAVA_OPTS 中设置 -Duser.timezone=America/Sao_Paulo——在某些发行版中，JVM 会读取自身的属性，而不是环境变量。
  • PostgreSQL 的 TZ 环境变量设置的是操作系统时钟，而不是数据库的 timezone 设置。通过 now() 获取的服务器时间戳仍使用 postgresql.conf 中的值——请同时设置两者。

评论

支持 Markdown