From b5e83e89448bcb69c095b7a056aa3f5fa4dcd4ed Mon Sep 17 00:00:00 2001
From: Maciej Szulik <maszulik@redhat.com>
Date: Tue, 16 Nov 2021 17:01:48 +0100
Subject: [PATCH] Add warning about using unsupported CRON_TZ

---
 .../workloads/controllers/cron-jobs.md        | 35 +++++++++++--------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/content/en/docs/concepts/workloads/controllers/cron-jobs.md b/content/en/docs/concepts/workloads/controllers/cron-jobs.md
index 083de9133404e..433ab201c6a42 100644
--- a/content/en/docs/concepts/workloads/controllers/cron-jobs.md
+++ b/content/en/docs/concepts/workloads/controllers/cron-jobs.md
@@ -17,8 +17,6 @@ A _CronJob_ creates {{< glossary_tooltip term_id="job" text="Jobs" >}} on a repe
 One CronJob object is like one line of a _crontab_ (cron table) file. It runs a job periodically
 on a given schedule, written in [Cron](https://en.wikipedia.org/wiki/Cron) format.
 
-In addition, the CronJob schedule supports timezone handling, you can specify the timezone by adding "CRON_TZ=<time zone>" at the beginning of the CronJob schedule, and it is recommended to always set `CRON_TZ`.
-
 {{< caution >}}
 All **CronJob** `schedule:` times are based on the timezone of the
 {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}}.
@@ -28,6 +26,16 @@ containers, the timezone set for the kube-controller-manager container determine
 that the cron job controller uses.
 {{< /caution >}}
 
+{{< caution >}}
+The [v1 CronJob API](/docs/reference/kubernetes-api/workload-resources/cron-job-v1/)
+does not officially support setting timezone as explained above.
+
+Setting variables such as `CRON_TZ` or `TZ` is not officially supported by the Kubernetes project.
+`CRON_TZ` or `TZ` is an implementation detail of the internal library being used
+for parsing and calculating the next Job creation time. Any usage of it is not
+recommended in a production cluster.
+{{< /caution >}}
+
 When creating the manifest for a CronJob resource, make sure the name you provide
 is a valid [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
 The name must be no longer than 52 characters. This is because the CronJob controller will automatically
@@ -55,16 +63,15 @@ takes you through this example in more detail).
 ### Cron schedule syntax
 
 ```
-#      ┌────────────────── timezone (optional)
-#      |      ┌───────────── minute (0 - 59)
-#      |      │ ┌───────────── hour (0 - 23)
-#      |      │ │ ┌───────────── day of the month (1 - 31)
-#      |      │ │ │ ┌───────────── month (1 - 12)
-#      |      │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday;
-#      |      │ │ │ │ │                                   7 is also Sunday on some systems)
-#      |      │ │ │ │ │
-#      |      │ │ │ │ │
-# CRON_TZ=UTC * * * * *
+# ┌───────────── minute (0 - 59)
+# │ ┌───────────── hour (0 - 23)
+# │ │ ┌───────────── day of the month (1 - 31)
+# │ │ │ ┌───────────── month (1 - 12)
+# │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday;
+# │ │ │ │ │                                   7 is also Sunday on some systems)
+# │ │ │ │ │
+# │ │ │ │ │
+# * * * * *
 ```
 
 
@@ -78,9 +85,9 @@ takes you through this example in more detail).
 
 
 
-For example, the line below states that the task must be started every Friday at midnight, as well as on the 13th of each month at midnight (in UTC):
+For example, the line below states that the task must be started every Friday at midnight, as well as on the 13th of each month at midnight:
 
-`CRON_TZ=UTC 0 0 13 * 5`
+`0 0 13 * 5`
 
 To generate CronJob schedule expressions, you can also use web tools like [crontab.guru](https://crontab.guru/).