Merge pull request #32577 from deejross/kep3140

Document timezone support for CronJob

Author: k8s-ci-robot

content/en/docs/concepts/workloads/controllers/cron-jobs.md

@@ -91,6 +91,21 @@ For example, the line below states that the task must be started every Friday at
 
 To generate CronJob schedule expressions, you can also use web tools like [crontab.guru](https://crontab.guru/).
 
+## Time zones
+For CronJobs with no time zone specified, the kube-controller-manager interprets schedules relative to its local time zone.
+
+{{< feature-state for_k8s_version="v1.24" state="alpha" >}}
+
+If you enable the  `CronJobTimeZone` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/),
+you can specify a time zone for a CronJob (if you don't enable that feature gate, or if you are using a version of
+Kubernetes that does not have experimental time zone support, all CronJobs in your cluster have an unspecified
+timezone).
+
+When you have the feature enabled, you can set `spec.timeZone` to the name of a valid [time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) name. For example, setting
+`spec.timeZone: "Etc/UTC"` instructs Kubernetes to interpret the schedule relative to Coordinated Universal Time.
+
+A time zone database from the Go standard library is included in the binaries and used as a fallback in case an external database is not available on the system.
+
 ## CronJob limitations {#cron-job-limitations}
 
 A cron job creates a job object _about_ once per execution time of its schedule. We say "about" because there

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -275,6 +275,7 @@ different Kubernetes components.
 | `CronJobControllerV2` | `false` | Alpha | 1.20 | 1.20 |
 | `CronJobControllerV2` | `true` | Beta | 1.21 | 1.21 |
 | `CronJobControllerV2` | `true` | GA | 1.22 | - |
+| `CronJobTimeZone` | `false` | Alpha | 1.24 | |
 | `CustomPodDNS` | `false` | Alpha | 1.9 | 1.9 |
 | `CustomPodDNS` | `true` | Beta| 1.10 | 1.13 |
 | `CustomPodDNS` | `true` | GA | 1.14 | - |
@@ -761,6 +762,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `CronJobControllerV2`: Use an alternative implementation of the
   {{< glossary_tooltip text="CronJob" term_id="cronjob" >}} controller. Otherwise,
   version 1 of the same controller is selected.
+- `CronJobTimeZone`: Allow the use of the `timeZone` optional field in [CronJobs](/docs/concepts/workloads/controllers/cron-jobs/)
 - `CustomCPUCFSQuotaPeriod`: Enable nodes to change `cpuCFSQuotaPeriod` in
   [kubelet config](/docs/tasks/administer-cluster/kubelet-config-file/).
 - `CustomResourceValidationExpressions`: Enable expression language validation in CRD which will validate customer resource based on validation rules written in `x-kubernetes-validations` extension.