Merge pull request #1123 from janetkuo/sj-docs-1.4

Create a ref doc for scheduled jobs

_data/reference.yml

@@ -220,6 +220,8 @@ toc:
     path: /docs/user-guide/horizontal-pod-autoscaling/
   - title: Jobs
     path: /docs/user-guide/jobs/
+  - title: Scheduled Jobs
+    path: /docs/user-guide/scheduled-jobs/
   - title: Resource Quotas
     path: /docs/admin/resource-quota/
   - title: Replica Sets

docs/user-guide/scheduled-jobs.md

@@ -0,0 +1,180 @@
+---
+assignees:
+- erictune
+- soltysh
+- janetkuo
+
+---
+
+* TOC
+{:toc}
+
+## What is a _Scheduled Job_?
+
+A _Scheduled Job_ manages time based [Jobs](/docs/user-guide/jobs/), namely:
+
+* Once at a specified point in time
+* Repeatedly at a specified point in time
+
+One ScheduledJob 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.
+
+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.4, with batch/v2alpha1 API turned on by passing
+`--runtime-config=batch/v2alpha1` while bringing up 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). You cannot use Scheduled Jobs on a hosted Kubernetes provider that has disabled alpha resources.
+
+## Creating a Scheduled Job
+
+Here is an example Scheduled Job. Every minute, it runs a simple job to print current time and then say
+hello.
+
+{% include code.html language="yaml" file="sj.yaml" ghlink="/docs/user-guide/sj.yaml" %}
+
+Run the example scheduled job by downloading the example file and then running this command:
+
+```shell
+$ kubectl create -f ./sj.yaml
+scheduledjob "hello" created
+```
+
+Alternatively, use `kubectl run` to create a scheduled job without writing full config:
+
+```shell
+$ kubectl run hello --schedule="0/1 * * * ?" --restart=OnFailure --image=busybox -- /bin/sh -c "date; echo Hello from the Kubernetes cluster"
+scheduledjob "hello" created
+```
+
+After creating the scheduled job, get its status using this command:
+
+```shell
+$ kubectl get scheduledjob hello
+NAME      SCHEDULE      SUSPEND   ACTIVE    LAST-SCHEDULE
+hello     0/1 * * * ?   False     0         <none>
+```
+
+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 scheduled job again:
+
+```shell
+$ kubectl get scheduledjob hello
+NAME      SCHEDULE      SUSPEND   ACTIVE    LAST-SCHEDULE
+hello     0/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 Scheduled Job 
+
+Once you don't need a scheduled job anymore, simply delete it with `kubectl`:
+
+```shell
+$ kubectl delete scheduledjob hello
+scheduledjob "hello" deleted
+```
+
+This stops new jobs from being created. However, running jobs won't be stopped, and no jobs or their pods will
+be deleted. To clean up those jobs and pods, you need to list all jobs created by the scheduled job, and delete them all:
+
+```shell
+$ kubectl get jobs
+NAME               DESIRED   SUCCESSFUL   AGE
+hello-1201907962   1         1            11m
+hello-1202039034   1         1            8m
+...
+
+$ kubectl delete jobs hello-1201907962 hello-1202039034 ...
+job "hello-1201907962" deleted
+job "hello-1202039034" deleted
+...
+```
+
+Once the jobs are deleted, the pods created by them are deleted as well. Note that all jobs created by scheduled
+job "hello" will be prefixed "hello-". You can delete them at once with `kubectl delete jobs --all`, if you want to 
+delete all jobs in the current namespace (not just the ones created by "hello".)
+
+## Scheduled Job Limitations
+
+A scheduled job creates a job object _about_ once per execution time of its schedule. We say "about" because there
+are certain circumstances where two jobs might be created, or no job might be created. We attempt to make these rare,
+but do not completely prevent them. Therefore, jobs should be _idempotent_.
+
+The job is responsible for retrying pods, parallelism among pods it creates, and determining the success or failure
+of the set of pods. A scheduled job does not examine pods at all.
+
+## Writing a Scheduled Job Spec
+
+As with all other Kubernetes configs, a scheduled job needs `apiVersion`, `kind`, and `metadata` fields. For general
+information about working with config files, see [deploying applications](/docs/user-guide/deploying-applications), 
+[configuring containers](/docs/user-guide/configuring-containers), and
+[using kubectl to manage resources](/docs/user-guide/working-with-resources) documents.
+
+A scheduled job also needs a [`.spec` section](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status).
+
+**Note:** All modifications to a scheduled 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/user-guide/jobs), except it is nested and does not have an `apiVersion` or `kind`, see
+[Writing a Job Spec](/docs/user-guide/jobs/#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 scheduled 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 scheduled job. If there are multiple
+scheduled 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. 

docs/user-guide/sj.yaml

@@ -0,0 +1,18 @@
+apiVersion: batch/v2alpha1
+kind: ScheduledJob
+metadata:
+  name: hello
+spec:
+  schedule: 0/1 * * * ?
+  jobTemplate:
+    spec:
+      template:
+        spec:
+          containers:
+          - name: hello
+            image: busybox
+            args:
+            - /bin/sh
+            - -c
+            - date; echo Hello from the Kubernetes cluster
+          restartPolicy: OnFailure