k8s-timezone-config

Kubernetes Pod のタイムゾーン設定

組織のインフラストラクチャで標準とするタイムゾーン： America/Sao_Paulo

問題

Kubernetes の Pod は、デフォルトで UTC で動作します。ログやアプリケーションのタイムスタンプには、ブラジルの現地時間（-0300）ではなく、+0000 のオフセットが表示されます。

解決方法

コンテナーの仕様に TZ 環境変数を追加します。

実装パターン

1. Helm の値（extraEnv パターン）

extraEnv をサポートする Helm チャートの場合：

# In values.yaml
extraEnv:
  - name: TZ
    value: America/Sao_Paulo

2. 複数のコンテナー

デプロイメントに複数のコンテナー（例：API サーバー＋フロントエンド）がある場合は、すべてのコンテナーに TZ を追加します。

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

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

3. Kubernetes の生のデプロイメント

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-Track	apiServer.extraEnv + frontend.extraEnv	両方のコンテナーに TZ が必要です
Grafana	env または extraEnvVars	単一コンテナー
Loki	extraEnv	ログのタイムスタンプに影響します
Prometheus	server.env	アラートのタイムスタンプに影響します
DefectDojo	extraEnv	Django アプリ
PostgreSQL	primary.extraEnvVars	データベースのタイムスタンプ

重要な注意事項

1. 再起動が必要です：TZ の変更を反映するには、Pod を再起動する必要があります
2. すべてのコンテナーが対象です：サイドカーも含め、Pod 内のすべてのコンテナーに TZ を設定します
3. Init コンテナー：タイムスタンプをログに記録する場合は、Init コンテナーにも TZ を設定します
4. Cron ジョブ：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 のままです。
• Pod の TZ に関係なく、CronJob の schedule: は常に UTC です。0 8 * * * のスケジュールは、ブラジリア時間（BRT）の 08:00 ではなく、05:00 に実行されます。CronJob 自体に spec.timeZone: America/Sao_Paulo を指定する（K8s 1.27 以降）か、UTC オフセットを手動で計算してください。
• Distroless イメージと scratch イメージには /usr/share/zoneinfo がありません。そのため、TZ=America/Sao_Paulo を指定しても、警告なしに UTC にフォールバックします。tzdata を同梱するベースイメージを使用するか、configMap/volume を介してマウントしてください。
• 古いチャートでは、Init コンテナーはメインコンテナーの TZ を継承しません。Init コンテナーの仕様にも個別に設定しないと、マイグレーションのログは UTC のままです。
• Java アプリでは、TZ に加えて JAVA_OPTS に -Duser.timezone=America/Sao_Paulo が必要です。ディストリビューションによっては、JVM は環境変数ではなく、独自のプロパティを参照します。
• PostgreSQL の TZ 環境変数が設定するのは OS の時刻であり、データベースの timezone 設定ではありません。now() によるサーバーのタイムスタンプには、引き続き postgresql.conf の値が使われます。両方を設定してください。