Merge pull request openshift#7220 from gaurav-nelson/enterprise-3.7-stage

[enterprise-3.7] Cron jobs suggestions for pruning and quota

Author: Gaurav Nelson

admin_guide/pruning_resources.adoc

@@ -614,3 +614,30 @@ finished, the registry can be switched back to read-write mode by executing:
 $ oc env -n default dc/docker-registry REGISTRY_STORAGE_MAINTENANCE_READONLY-
 ----
 endif::[]
+
+[[pruning-cronjobs]]
+== Pruning Cron Jobs
+
+[IMPORTANT]
+====
+Cron Jobs is a Technology Preview feature only.
+ifdef::openshift-enterprise[]
+Technology Preview features are not
+supported with Red Hat production service level agreements (SLAs), might not be
+functionally complete, and Red Hat does not recommend to use them for
+production. These features provide early access to upcoming product features,
+enabling customers to test functionality and provide feedback during the
+development process.
+
+For more information on Red Hat Technology Preview features support scope, see
+https://access.redhat.com/support/offerings/techpreview/.
+endif::[]
+====
+
+At this time, the results of cron jobs are not automatically pruned, unless a
+application developer explicitly configures that feature. Therefore, cluster
+administrator should manually perform a regular
+xref:../../dev_guide/cron_jobs.adoc#cleaning-up-after-a-cron-job[Cron job cleanup].
+Red Hat recommends to xref:manage_authorization_policy.adoc[restrict the access] to cron jobs
+to a small group of trusted users and set appropriate xref:quota.adoc[quota] to
+prevent the cron job from creating too many jobs and pods.

dev_guide/cron_jobs.adoc

@@ -45,8 +45,10 @@ endif::[]
 [WARNING]
 ====
 A cron job creates a job object approximately once per execution time of its
-schedule, but there are circumstances in which it will fail to create a job or
-two jobs might be created. As a result, jobs should be idempotent.
+schedule, but there are circumstances in which it fails to create a job or
+two jobs might be created.  Therefore, jobs should be idempotent and you
+should monitor and xref:cleaning-up-after-a-cron-job[clean cron jobs]
+frequently.
 ====
 
 [[creating-a-cronjob]]
@@ -127,14 +129,29 @@ Doing this prevents them from generating unnecessary artifacts.
 [[cleaning-up-after-a-cron-job]]
 == Cleaning Up After a Cron Job
 
-Cron jobs can leave behind artifact resources such as jobs or pods. Check if any remain:
+Cron jobs can leave behind artifact resources such as jobs or pods.  Configuring history limits is important, so that old jobs and their pods are properly cleaned.  There are
+two optional fields within cron job's spec responsible for that:
 
+[source,yaml]
 ----
-$ oc get jobs
-$ oc get pods
+apiVersion: batch/v2alpha1
+kind: CronJob
+metadata:
+  name: pi
+spec:
+  successfulJobsHistoryLimit: 3 <1>
+  failedJobsHistoryLimit: 1     <2>
+  schedule: "*/1 * * * *"
+  jobTemplate:
+    spec:
+  ...
 ----
 
-All artifacts left over from a job execution use the job name as their prefix. For example, given the cron job example:
+<1> The number of successful finished jobs to retain.
+<2> The number of failed finished jobs to retain.
+
+At any point in time, you can manually verify all artifacts left over from a job execution by using
+the job name as their prefix. For example, given the cron job example:
 
 ----
 $ oc get jobs