From 595e1455cabd951a87b4601295e3c3eabf03f6fc Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Sun, 6 May 2018 15:01:50 -0400 Subject: [PATCH] #4500: Split out tasks in cron jobs docs (#8337) * first attempt * Skipping these sections * cleanup and style * style * move schedule info to schedule section * link to example --- .../workloads/controllers/cron-jobs.md | 151 +-------------- .../job/automated-tasks-with-cron-jobs.md | 174 ++++++++++++++++++ .../controllers => tasks/job}/cronjob.yaml | 0 data/tasks.yml | 1 + 4 files changed, 177 insertions(+), 149 deletions(-) create mode 100755 content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md rename content/en/docs/{concepts/workloads/controllers => tasks/job}/cronjob.yaml (100%) diff --git a/content/en/docs/concepts/workloads/controllers/cron-jobs.md b/content/en/docs/concepts/workloads/controllers/cron-jobs.md index b33c591e60..607309a7f7 100644 --- a/content/en/docs/concepts/workloads/controllers/cron-jobs.md +++ b/content/en/docs/concepts/workloads/controllers/cron-jobs.md @@ -18,103 +18,7 @@ A _Cron Job_ manages time based [Jobs](/docs/concepts/workloads/controllers/jobs 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. -**Note:** The question mark (`?`) in the schedule has the same meaning as an asterisk `*`, -that is, it stands for any of available value for a given field. - -**Note:** CronJob resource in `batch/v2alpha1` API group has been deprecated starting -from cluster version 1.8. You should switch to using `batch/v1beta1`, instead, which is -enabled by default in the API server. Further in this document, we will be using -`batch/v1beta1` in all the examples. - -A typical use case is: - -* Schedule a job execution at a given point in time. -* Create a periodic job, e.g. database backup, sending emails. - -### Prerequisites - -You need a working Kubernetes cluster at version >= 1.8 (for CronJob). For previous versions of cluster (< 1.8) -you need to explicitly enable `batch/v2alpha1` API by passing `--runtime-config=batch/v2alpha1=true` to -the API server (see [Turn on or off an API version for your cluster](/docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster) -for more), and then restart both the API server and the controller manager -component. - -## Creating a Cron Job - -Here is an example Cron Job. Every minute, it runs a simple job to print current time and then say -hello. - -{{< code file="cronjob.yaml" >}} - -Run the example cron job by downloading the example file and then running this command: - -```shell -$ kubectl create -f ./cronjob.yaml -cronjob "hello" created -``` - -Alternatively, use `kubectl run` to create a cron job without writing full config: - -```shell -$ kubectl run hello --schedule="*/1 * * * *" --restart=OnFailure --image=busybox -- /bin/sh -c "date; echo Hello from the Kubernetes cluster" -cronjob "hello" created -``` - -After creating the cron job, get its status using this command: - -```shell -$ kubectl get cronjob hello -NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE -hello */1 * * * * False 0 -``` - -As you can see above, there's no active job yet, and no job has been scheduled, either. - -Watch for the job to be created in around one minute: - -```shell -$ kubectl get jobs --watch -NAME DESIRED SUCCESSFUL AGE -hello-4111706356 1 1 2s -``` - -Now you've seen one running job scheduled by "hello". We can stop watching it and get the cron job again: - -```shell -$ kubectl get cronjob hello -NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE -hello */1 * * * * False 0 Mon, 29 Aug 2016 14:34:00 -0700 -``` - -You should see that "hello" successfully scheduled a job at the time specified in `LAST-SCHEDULE`. There are -currently 0 active jobs, meaning that the job that's scheduled is completed or failed. - -Now, find the pods created by the job last scheduled and view the standard output of one of the pods. Note that -your job name and pod name would be different. - -```shell -# Replace "hello-4111706356" with the job name in your system -$ pods=$(kubectl get pods --selector=job-name=hello-4111706356 --output=jsonpath={.items..metadata.name}) - -$ echo $pods -hello-4111706356-o9qcm - -$ kubectl logs $pods -Mon Aug 29 21:34:09 UTC 2016 -Hello from the Kubernetes cluster -``` - -## Deleting a Cron Job - -Once you don't need a cron job anymore, simply delete it with `kubectl`: - -```shell -$ kubectl delete cronjob hello -cronjob "hello" deleted -``` - -This stops new jobs from being created and removes all the jobs and pods created by this cronjob. -You can read more about it in [garbage collection section](/docs/concepts/workloads/controllers/garbage-collection/). +For instructions on creating and working with cron jobs, and for an example of a spec file for a cron job, see [Running automated tasks with cron jobs](/docs/tasks/job/automated-tasks-with-cron-jobs). ## Cron Job Limitations @@ -130,7 +34,7 @@ Jobs may fail to run if the CronJob controller is not running or broken for a span of time from before the start time of the CronJob to start time plus `startingDeadlineSeconds`, or if the span covers multiple start times and `concurrencyPolicy` does not allow concurrency. -For example, suppose a cron job is set to start at exactly `08:30:00` and its +For example, suppose a cron job is set to start at exactly `08:30:00` and its `startingDeadlineSeconds` is set to 10, if the CronJob controller happens to be down from `08:29:00` to `08:42:00`, the job will not start. Set a longer `startingDeadlineSeconds` if starting later is better than not @@ -138,54 +42,3 @@ starting at all. The Cronjob is only responsible for creating Jobs that match its schedule, and the Job in turn is responsible for the management of the Pods it represents. - -## Writing a Cron Job Spec - -As with all other Kubernetes configs, a cron job needs `apiVersion`, `kind`, and `metadata` fields. For general -information about working with config files, see [deploying applications](/docs/user-guide/deploying-applications), -and [using kubectl to manage resources](/docs/user-guide/working-with-resources) documents. - -A cron job also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status). - -**Note:** All modifications to a cron job, especially its `.spec`, will be applied only to the next run. - -### Schedule - -The `.spec.schedule` is a required field of the `.spec`. It takes a [Cron](https://en.wikipedia.org/wiki/Cron) format -string, e.g. `0 * * * *` or `@hourly`, as schedule time of its jobs to be created and executed. - -### Job Template - -The `.spec.jobTemplate` is another required field of the `.spec`. It is a job template. It has exactly the same schema -as a [Job](/docs/concepts/workloads/controllers/jobs-run-to-completion/), except it is nested and does not have an `apiVersion` or `kind`, see -[Writing a Job Spec](/docs/concepts/workloads/controllers/jobs-run-to-completion/#writing-a-job-spec). - -### Starting Deadline Seconds - -The `.spec.startingDeadlineSeconds` field is optional. It stands for the deadline (in seconds) for starting the job -if it misses its scheduled time for any reason. Missed jobs executions will be counted as failed ones. If not specified, -there's no deadline. - -### Concurrency Policy - -The `.spec.concurrencyPolicy` field is also optional. It specifies how to treat concurrent executions of a job -created by this cron job. Only one of the following concurrent policies may be specified: - -* `Allow` (default): allows concurrently running jobs -* `Forbid`: forbids concurrent runs, skipping next run if previous hasn't finished yet -* `Replace`: cancels currently running job and replaces it with a new one - -Note that concurrency policy only applies to the jobs created by the same cron job. If there are multiple -cron jobs, their respective jobs are always allowed to run concurrently. - -### Suspend - -The `.spec.suspend` field is also optional. If set to `true`, all subsequent executions will be suspended. It does not -apply to already started executions. Defaults to false. - -### Jobs History Limits - -The `.spec.successfulJobsHistoryLimit` and `.spec.failedJobsHistoryLimit` fields are optional. -These fields specify how many completed and failed jobs should be kept. By default, they are -set to 3 and 1 respectively. Setting a limit to `0` corresponds to keeping none of the corresponding -kind of jobs after they finish. diff --git a/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md new file mode 100755 index 0000000000..2fafc704fa --- /dev/null +++ b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md @@ -0,0 +1,174 @@ +--- +title: Running automated tasks with cron jobs +reviewers: +- chenopis +content_template: templates/task +--- + +{{% capture overview %}} + +You can use [CronJobs](/docs/concepts/workloads/controllers/cron-jobs) to run jobs on a time-based schedule. +These automated jobs run like [Cron](https://en.wikipedia.org/wiki/Cron) tasks on a Linux or UNIX system. + +Cron jobs are useful for creating periodic and recurring tasks, like running backups or sending emails. +Cron jobs can also schedule individual tasks for a specific time, such as if you want to schedule a job for a low activity period. + +**Note:** CronJob resource in `batch/v2alpha1` API group has been deprecated starting from cluster version 1.8. +You should switch to using `batch/v1beta1`, instead, which is enabled by default in the API server. +Examples in this document use `batch/v1beta1` in all examples. + +Cron jobs have limitations and idiosyncracies. +For example, in certain circumstances, a single cron job can create multiple jobs. +Therefore, jobs should be idempotent. +For more limitations, see [CronJobs](/docs/concepts/workloads/controllers/cron-jobs). + +{{% /capture %}} + +{{% capture prerequisites %}} + +* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} +* You need a working Kubernetes cluster at version >= 1.8 (for CronJob). For previous versions of cluster (< 1.8) +you need to explicitly enable `batch/v2alpha1` API by passing `--runtime-config=batch/v2alpha1=true` to +the API server (see [Turn on or off an API version for your cluster](/docs/admin/cluster-management/#turn-on-or-off-an-api-version-for-your-cluster) +for more), and then restart both the API server and the controller manager +component. + +{{% /capture %}} + +{{% capture steps %}} + +## Creating a Cron Job + +Cron jobs require a config file. +This example cron job config `.spec` file prints the current time and a hello message every minute: + +{{< code file="cronjob.yaml" >}} + +Run the example cron job by downloading the example file and then running this command: + +```shell +$ kubectl create -f ./cronjob.yaml +cronjob "hello" created +``` + +Alternatively, you can use `kubectl run` to create a cron job without writing a full config: + +```shell +$ kubectl run hello --schedule="*/1 * * * *" --restart=OnFailure --image=busybox -- /bin/sh -c "date; echo Hello from the Kubernetes cluster" +cronjob "hello" created +``` + +After creating the cron job, get its status using this command: + +```shell +$ kubectl get cronjob hello +NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE +hello */1 * * * * False 0 +``` + +As you can see from the results of the command, the cron job has not scheduled or run any jobs yet. +Watch for the job to be created in around one minute: + +```shell +$ kubectl get jobs --watch +NAME DESIRED SUCCESSFUL AGE +hello-4111706356 1 1 2s +``` + +Now you've seen one running job scheduled by the "hello" cron job. +You can stop watching the job and view the cron job again to see that it scheduled the job: + +```shell +$ kubectl get cronjob hello +NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE +hello */1 * * * * False 0 Mon, 29 Aug 2016 14:34:00 -0700 +``` + +You should see that the cron job "hello" successfully scheduled a job at the time specified in `LAST-SCHEDULE`. +There are currently 0 active jobs, meaning that the job has completed or failed. + +Now, find the pods that the last scheduled job created and view the standard output of one of the pods. +Note that the job name and pod name are different. + +```shell +# Replace "hello-4111706356" with the job name in your system +$ pods=$(kubectl get pods --selector=job-name=hello-4111706356 --output=jsonpath={.items..metadata.name}) + +$ echo $pods +hello-4111706356-o9qcm + +$ kubectl logs $pods +Mon Aug 29 21:34:09 UTC 2016 +Hello from the Kubernetes cluster +``` + +## Deleting a Cron Job + +When you don't need a cron job any more, delete it with `kubectl delete cronjob`: + +```shell +$ kubectl delete cronjob hello +cronjob "hello" deleted +``` + +Deleting the cron job removes all the jobs and pods it created and stops it from creating additional jobs. +You can read more about removing jobs in [garbage collection](/docs/concepts/workloads/controllers/garbage-collection/). + +## Writing a Cron Job Spec + +As with all other Kubernetes configs, a cron job needs `apiVersion`, `kind`, and `metadata` fields. For general +information about working with config files, see [deploying applications](/docs/user-guide/deploying-applications), +and [using kubectl to manage resources](/docs/user-guide/working-with-resources) documents. + +A cron job config also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status). + +**Note:** All modifications to a cron job, especially its `.spec`, are applied only to the following runs. + +### Schedule + +The `.spec.schedule` is a required field of the `.spec`. +It takes a [Cron](https://en.wikipedia.org/wiki/Cron) format string, such as `0 * * * *` or `@hourly`, as schedule time of its jobs to be created and executed. + +**Note:** The question mark (`?`) in the schedule has the same meaning as an asterisk `*`, that is, it stands for any of available value for a given field. + +### Job Template + +The `.spec.jobTemplate` is the template for the job, and it is required. +It has exactly the same schema as a [Job](/docs/concepts/workloads/controllers/jobs-run-to-completion/), except that it is nested and does not have an `apiVersion` or `kind`. +For information about writing a job `.spec`, see [Writing a Job Spec](/docs/concepts/workloads/controllers/jobs-run-to-completion/#writing-a-job-spec). + +### Starting Deadline + +The `.spec.startingDeadlineSeconds` field is optional. +It stands for the deadline in seconds for starting the job if it misses its scheduled time for any reason. +After the deadline, the cron job does not start the job. +Jobs that do not meet their deadline in this way count as failed jobs. +If this field is not specified, the jobs have no deadline. + +### Concurrency Policy + +The `.spec.concurrencyPolicy` field is also optional. +It specifies how to treat concurrent executions of a job that is created by this cron job. +the spec may specify only one of the following concurrency policies: + +* `Allow` (default): The cron job allows concurrently running jobs +* `Forbid`: The cron job does not allow concurrent runs; if it is time for a new job run and the previous job run hasn't finished yet, the cron job skips the new job run +* `Replace`: If it is time for a new job run and the previous job run hasn't finished yet, the cron job replaces the currently running job run with a new job run + +Note that concurrency policy only applies to the jobs created by the same cron job. +If there are multiple cron jobs, their respective jobs are always allowed to run concurrently. + +### Suspend + +The `.spec.suspend` field is also optional. +If it is set to `true`, all subsequent executions are suspended. +This setting does not apply to already started executions. +Defaults to false. + +### Jobs History Limits + +The `.spec.successfulJobsHistoryLimit` and `.spec.failedJobsHistoryLimit` fields are optional. +These fields specify how many completed and failed jobs should be kept. +By default, they are set to 3 and 1 respectively. Setting a limit to `0` corresponds to keeping none of the corresponding kind of jobs after they finish. + +{{% /capture %}} diff --git a/content/en/docs/concepts/workloads/controllers/cronjob.yaml b/content/en/docs/tasks/job/cronjob.yaml similarity index 100% rename from content/en/docs/concepts/workloads/controllers/cronjob.yaml rename to content/en/docs/tasks/job/cronjob.yaml diff --git a/data/tasks.yml b/data/tasks.yml index 07cc4a18f4..7046f903aa 100644 --- a/data/tasks.yml +++ b/data/tasks.yml @@ -64,6 +64,7 @@ toc: - title: Run Jobs landing_page: /docs/tasks/job/parallel-processing-expansion/ section: + - docs/tasks/job/automated-tasks-with-cron-jobs.md - docs/tasks/job/parallel-processing-expansion.md - docs/tasks/job/coarse-parallel-processing-work-queue/index.md - docs/tasks/job/fine-parallel-processing-work-queue/index.md