{"id":13819880,"url":"https://github.com/k8tz/k8tz","last_synced_at":"2025-05-16T07:32:23.091Z","repository":{"id":37087116,"uuid":"405338178","full_name":"k8tz/k8tz","owner":"k8tz","description":"Kubernetes admission controller and a CLI tool to inject timezones into Pods and CronJobs","archived":false,"fork":false,"pushed_at":"2025-03-24T20:19:25.000Z","size":4764,"stargazers_count":432,"open_issues_count":11,"forks_count":37,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-24T20:28:29.212Z","etag":null,"topics":["devops","go","golang","helm-chart","helm-chart-repository","helm-charts","kubernetes","kubernetes-controller","timezone","timezones","tzdata"],"latest_commit_sha":null,"homepage":"http://k8tz.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k8tz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-11T09:32:31.000Z","updated_at":"2025-03-24T20:19:17.000Z","dependencies_parsed_at":"2023-02-17T23:15:45.044Z","dependency_job_id":"9a85ea3b-8dfb-45ad-a385-77e4a6934978","html_url":"https://github.com/k8tz/k8tz","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k8tz%2Fk8tz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k8tz%2Fk8tz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k8tz%2Fk8tz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k8tz%2Fk8tz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k8tz","download_url":"https://codeload.github.com/k8tz/k8tz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254488406,"owners_count":22079424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","go","golang","helm-chart","helm-chart-repository","helm-charts","kubernetes","kubernetes-controller","timezone","timezones","tzdata"],"created_at":"2024-08-04T08:00:54.398Z","updated_at":"2025-05-16T07:32:23.077Z","avatar_url":"https://github.com/k8tz.png","language":"Go","readme":"# Kubernetes Timezone Controller\n\n![Build Workflow Status](https://img.shields.io/github/actions/workflow/status/k8tz/k8tz/go.yaml?branch=master)\n[![Go Report Card](https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat)](https://goreportcard.com/report/github.com/k8tz/k8tz)\n[![codecov](https://codecov.io/gh/k8tz/k8tz/branch/master/graph/badge.svg?token=3HEoptX1C0)](https://codecov.io/gh/k8tz/k8tz)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/k8tz/k8tz)](go.mod)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n![k8tz Logo](assets/k8tz-logo-blue-transparent-medium.png)\n\n`k8tz` is a kubernetes admission controller and a CLI tool to inject timezones into Pods and CronJobs[^1].\n\nContainers do not inherit timezones from host machines and have only accessed to the clock from the kernel. The default timezone for most images is UTC, yet it is not guaranteed and may be different from container to container. With `k8tz` it is easy to standardize selected timezone across pods and namespaces automatically with minimal effort.\n\n## Features\n\n:zap: Coordinate timezone for all pods in clusters and/or namespaces (force UTC by default)\n\n:zap: Standardize [tzdata](https://www.iana.org/time-zones) version across all pods in cluster\n\n:zap: Does not require [tzdata](https://www.iana.org/time-zones) installed in images or nodes\n\n:zap: Easy to configure with [Helm values](charts/k8tz/README.md#values) and [Annotations](#annotations)\n\n:zap: [CLI tools](#cli) for manual timezone injection\n\n:zap: Supports Kubernetes 1.16+ and OpenShift 4.X\n\nRead more: [Timezone in Kubernetes With k8tz](https://medium.com/@yonatankahana/timezone-in-kubernetes-with-k8tz-fdefca785238)\n\n## Install Admission Controller (Helm)\n\n![Short Demo](assets/k8tz-helm-demo.gif)\n\ntl;dr:\n\n```console\nhelm repo add k8tz https://k8tz.github.io/k8tz/\nhelm install k8tz k8tz/k8tz --set timezone=Europe/London\n```\n\nRead more in the chart [README](charts/k8tz/README.md).\n\n## CLI\n\n`k8tz` can be used as a command-line tool to inject timezone into yaml files or to be integrated inside another deployment script that don't want to use the admission controller automation.\n\n### Examples\n\nYou can process the `test-pod.yaml` from file-to-file or directly to `kubectl`:\n\n```console\n# to a file\nk8tz inject --strategy=hostPath test-pod.yaml \u003e injected-test-pod.yaml\n\n# or directly to kubectl\nk8tz inject --timezone=Europe/London test-pod.yaml | kubectl apply -f -\n```\n\nOr you can inject to all existing deployments in current namespace:\n\n```console\nkubectl get deploy -oyaml | k8tz inject - | kubectl apply -f -\n```\n\nNOTE: The injection process is idempotent; you can do it multiple times and/or use the CLI injection alongside the admission controller. Subsequent injections have no effect.\n\n### Download GitHub Release\n\nYou can install k8tz binary file by downloading precompiled binary and use it\n\n```console\nwget -c https://github.com/k8tz/k8tz/releases/download/v0.18.0/k8tz_0.18.0_linux_amd64.tar.gz -O - | tar xz\nchmod +x k8tz\n./k8tz version\n```\n\nthen install it to your `$PATH` with:\n\n```console\nsudo install k8tz /usr/local/bin/k8tz\n```\n\n### Go Install\n\nIf you have `go` installed, you can install `k8tz` with:\n\n```console\ngo install github.com/k8tz/k8tz@latest\n```\n\n### Use Docker\n\nYou can use k8tz directly from Docker, here are some examples:\n\n```console\ndocker run -i quay.io/k8tz/k8tz --help\n\ncat test-pod.yaml | docker run -i quay.io/k8tz/k8tz inject -tPortugal - | kubectl create -f\n\nkubectl get deploy -oyaml | docker run -i quay.io/k8tz/k8tz inject - | kubectl apply -f\n```\n\n### From Source\n\nYou can build `k8tz` binary from source yourself by simple running:\n\n```console\nmake compile\n```\n\nThe created binary will be located at `build/k8tz`, you can then install it to your PATH using:\n\n```console\nmake TARGET=/usr/local/bin install\n```\n\nTo uninstall, use `sudo rm -v /usr/local/bin/k8tz`.\n\n## Injection Strategy\n\nTimezone information is defined using Time Zone Information Format files (`TZif`, [RFC-8536](https://datatracker.ietf.org/doc/html/rfc8536)). The Timezone Database contains `TZif` files that represent the local time for many locations around the globe. To set the container's timezone, `/etc/localtime` inside the container should point to a valid `TZif` file which represents the requested timezone. In most images these files do not exist by default, so we need to make them available from inside the container mounted at `/etc/localtime`.\n\nCurrently, there are 2 strategies how it can be done:\n\n### Using **hostPath**\n\nIf those files (which are located under `/usr/share/zoneinfo`) exist in every node on the cluster (it is the user's responsibility to ensure that), `hostPath` volume can be used to supply the required `TZif` file into the pod. If the required timezone will be missing on the host machine, the pod will be stuck in `PodInitializing` status and will not be started.\n\n### Using bootstrap **initContainer**\n\nAnother solution, which is generally safer, is to inject `initContainer` (bootstrap image) to the pod and supply the required `TZif` file using a shared `emptyDir` volume. This is the default method of k8tz.\n\n## Annotations\n\nThe behaviour of the controller can be changed using annotations on both `Pod` and/or `Namespace` objects. If the same annotation specified in both, the `Pod`'s annotation value will take place.\n\n| Annotation         | Description                                                            | Default         |\n|--------------------|------------------------------------------------------------------------|-----------------|\n| `k8tz.io/inject`   | Decide whether k8tz should inject timezone or not                      | `true`          |\n| `k8tz.io/timezone` | Decide what timezone should be used, e.g: `Africa/Addis_Ababa`         | `UTC`           |\n| `k8tz.io/strategy` | Decide what injection strategy to use, i.e: `hostPath`/`initContainer` | `initContainer` |\n\n## Roadmap\n\n- [X] Support `StatefulSet` injection\n- [X] Support `CronJob` injection\n- [ ] Better way to lookup pod owner annotations\n- [X] Test and document installation on OpenShift\n- [X] Implement `make install` for easier installation from source\n- [X] Add VERBOSE flag to helm\n- [X] Write verbose logs for webhook\n- [X] Separate README for Helm chart\n\n[^1]: Timezones for CronJobs are available only from kubernetes \u003e=1.24.0-beta.0 with [`CronJobTimeZone`](https://github.com/kubernetes/enhancements/blob/aad71056d33eccf3845b73670106f06a9e74fec6/keps/sig-apps/3140-TimeZone-support-in-CronJob/README.md) feature gate enabled.\n","funding_links":[],"categories":["kubernetes"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk8tz%2Fk8tz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk8tz%2Fk8tz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk8tz%2Fk8tz/lists"}