home / skills / julianobarbosa / claude-code-skills / k8s-timezone-config

k8s-timezone-config skill

safe

This skill helps configure Kubernetes pod timezone to America/Sao_Paulo by injecting TZ env vars across containers and pods for accurate local timestamps.

npx playbooks add skill julianobarbosa/claude-code-skills --skill k8s-timezone-config

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: k8s-timezone-config
description: Configure timezone for Kubernetes pods using TZ environment variable. Use when deploying workloads that need Brazil/São Paulo timezone or when logs show UTC (+0000) instead of local time.
---

# Kubernetes Pod Timezone Configuration

**Standard timezone for Hypera infrastructure:** `America/Sao_Paulo`

## Problem

Kubernetes pods run in UTC by default. Logs and application timestamps show `+0000` offset instead of local Brazil time (`-0300`).

## Solution

Add the `TZ` environment variable to container specifications.

## Implementation Patterns

### 1. Helm Values (extraEnv pattern)

For Helm charts that support `extraEnv`:

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

### 2. Multiple Containers

When a deployment has multiple containers (e.g., API server + frontend), add `TZ` to **ALL** containers:

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

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

### 3. Raw Kubernetes Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          env:
            - name: TZ
              value: America/Sao_Paulo
```

### 4. StatefulSet

```yaml
apiVersion: apps/v1
kind: StatefulSet
spec:
  template:
    spec:
      containers:
        - name: app
          env:
            - name: TZ
              value: America/Sao_Paulo
```

## Verification

After deployment, verify timezone is set correctly:

```bash
# 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
```

## Common Applications Requiring Timezone

| Application | Config Location | Notes |
|-------------|-----------------|-------|
| Dependency-Track | `apiServer.extraEnv` + `frontend.extraEnv` | Both containers need TZ |
| Grafana | `env` or `extraEnvVars` | Single container |
| Loki | `extraEnv` | Affects log timestamps |
| Prometheus | `server.env` | Affects alert timestamps |
| DefectDojo | `extraEnv` | Django app |
| PostgreSQL | `primary.extraEnvVars` | Database timestamps |

## Important Notes

1. **Restart required**: Pods must restart for TZ changes to take effect
2. **All containers**: Set TZ on ALL containers in a pod, including sidecars
3. **Init containers**: Also set TZ on init containers if they log timestamps
4. **Cron jobs**: Kubernetes CronJob schedules are always UTC - TZ only affects container-level time

## Hypera GitOps Workflow

1. Edit values.yaml in `argo-cd-helm-values/kube-addons/<service>/<cluster>/values.yaml`
2. Add TZ environment variable to all containers
3. Commit and push (ArgoCD auto-syncs)
4. Verify pods restart with new timezone

## Reference

- IANA Timezone Database: `America/Sao_Paulo` = UTC-3 (no DST since 2019)
- Linux TZ variable: Uses `/usr/share/zoneinfo/America/Sao_Paulo`

Overview

This skill configures the timezone for Kubernetes pods by injecting the TZ environment variable set to America/Sao_Paulo. It provides patterns for Helm values, raw manifests, StatefulSets, CronJobs, and multi-container pods so logs and application timestamps reflect Brazil time instead of UTC. The guidance covers verification and common pitfalls to ensure consistent application behavior.

How this skill works

The skill adds an env entry named TZ with value America/Sao_Paulo to container specs so the process inside the container uses the correct timezone file. It shows where to add TZ for Helm charts (extraEnv/extraEnvVars), raw Deployment/StatefulSet manifests, init containers, sidecars, and CronJob containers. It also explains verification commands and restart requirements.

When to use it

Deploying workloads that must show Brazil/Sao_Paulo local time instead of UTC
When application or log timestamps display +0000 and need to be -0300
Installing or updating Helm charts that support extraEnv or extraEnvVars
Deployments with multiple containers, sidecars, or init containers that emit timestamps
Before committing helm-values for GitOps workflows so ArgoCD can sync updated envs

Best practices

Set TZ=America/Sao_Paulo on every container in the pod, including sidecars and init containers
Use existing chart hooks like extraEnv, extraEnvVars or server.env rather than editing container images
Remember pods must restart for TZ changes to take effect; trigger a rollout or rely on GitOps sync
Do not rely on TZ to change Kubernetes CronJob schedule; CronJobs are scheduled by cluster UTC
Verify with kubectl exec <pod> -- date and by checking log timestamp offsets after rollout

Example use cases

Add TZ to values.yaml using extraEnv for Helm charts to enforce Brazil timezone across a service
Update a Deployment manifest to include env: - name: TZ value: America/Sao_Paulo for app and sidecar containers
Apply TZ to StatefulSet pods so database and application timestamps align with local time
Configure TZ for Grafana/Loki/Prometheus containers to normalize dashboard and log times
Include TZ in init containers when their logs need to reflect local timestamps during startup

FAQ

Will setting TZ change Kubernetes CronJob schedule?

No. Kubernetes CronJob schedules are evaluated in UTC. TZ only affects time inside the container, not the CronJob controller schedule.

Do pods need to be restarted after adding TZ?

Yes. Updating environment variables requires pod restart or pod recreation for the new TZ to take effect.