From ab09b11359713289283a7699eaa5a1fe07221eea Mon Sep 17 00:00:00 2001 From: Maciej Szulik Date: Wed, 9 Nov 2016 11:32:57 +0100 Subject: [PATCH] Rename ScheduledJobs to CronJobs --- _data/guides.yml | 6 +- _data/reference.yml | 36 ++++----- .../{scheduled-jobs.md => cron-jobs.md} | 75 ++++++++++--------- docs/user-guide/{sj.yaml => cronjob.yaml} | 2 +- docs/user-guide/jobs.md | 4 +- docs/user-guide/kubectl-cheatsheet.md | 4 +- docs/user-guide/kubectl-conventions.md | 4 +- docs/user-guide/kubectl/kubectl_run.md | 2 +- test/examples_test.go | 2 +- 9 files changed, 69 insertions(+), 66 deletions(-) rename docs/user-guide/{scheduled-jobs.md => cron-jobs.md} (64%) rename docs/user-guide/{sj.yaml => cronjob.yaml} (95%) diff --git a/_data/guides.yml b/_data/guides.yml index 76773e874e..0c1a785720 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -72,7 +72,7 @@ toc: path: /docs/getting-started-guides/network-policy/walkthrough/ - title: Using Calico for NetworkPolicy path: /docs/getting-started-guides/network-policy/calico/ - - title: Using Romana for NetworkPolicy + - title: Using Romana for NetworkPolicy path: /docs/getting-started-guides/network-policy/romana/ - title: Batch Jobs @@ -85,8 +85,8 @@ toc: path: /docs/user-guide/jobs/work-queue-1/ - title: Fine Parallel Processing using a Work Queue path: /docs/user-guide/jobs/work-queue-2/ - - title: Scheduled Jobs - path: /docs/user-guide/scheduled-jobs/ + - title: Cron Jobs + path: /docs/user-guide/cron-jobs/ - title: Service Discovery and Load Balancing section: diff --git a/_data/reference.yml b/_data/reference.yml index 62fdb0ca92..6f71d1677c 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -40,13 +40,13 @@ toc: path: /docs/api-reference/batch/v1/operations/ - title: Batch API Definitions path: /docs/api-reference/batch/v1/definitions/ - + - title: Extensions API section: - title: Extensions API Operations path: /docs/api-reference/extensions/v1beta1/operations/ - title: Extensions API Definitions - path: /docs/api-reference/extensions/v1beta1/definitions/ + path: /docs/api-reference/extensions/v1beta1/definitions/ - title: kubectl CLI section: @@ -172,7 +172,7 @@ toc: - title: kube-apiserver path: /docs/admin/kube-apiserver/ - title: kube-controller-manager - path: /docs/admin/kube-controller-manager/ + path: /docs/admin/kube-controller-manager/ - title: kube-proxy path: /docs/admin/kube-proxy/ - title: kube-scheduler @@ -183,33 +183,33 @@ toc: - title: Glossary section: - title: Annotations - path: /docs/user-guide/annotations/ + path: /docs/user-guide/annotations/ - title: Daemon Sets path: /docs/admin/daemons/ - - title: Deployments + - title: Deployments path: /docs/user-guide/deployments/ - title: Horizontal Pod Autoscaling - path: /docs/user-guide/horizontal-pod-autoscaling/ + path: /docs/user-guide/horizontal-pod-autoscaling/ - title: Images path: /docs/user-guide/images/ - title: Ingress Resources - path: /docs/user-guide/ingress/ + path: /docs/user-guide/ingress/ - title: Jobs - path: /docs/user-guide/jobs/ + path: /docs/user-guide/jobs/ - title: Labels and Selectors path: /docs/user-guide/labels/ - title: Names path: /docs/user-guide/identifiers/ - title: Namespaces path: /docs/user-guide/namespaces/ - - title: Network Policies - path: /docs/user-guide/networkpolicies/ + - title: Network Policies + path: /docs/user-guide/networkpolicies/ - title: Nodes - path: /docs/admin/node/ + path: /docs/admin/node/ - title: Persistent Volumes - path: /docs/user-guide/persistent-volumes/ + path: /docs/user-guide/persistent-volumes/ - title: Pet Sets - path: /docs/user-guide/petset/ + path: /docs/user-guide/petset/ - title: Pods path: /docs/user-guide/pods/ - title: Pod Security Policies @@ -217,11 +217,11 @@ toc: - title: Replica Sets path: /docs/user-guide/replicasets/ - title: Replication Controller - path: /docs/user-guide/replication-controller/ + path: /docs/user-guide/replication-controller/ - title: Resource Quotas path: /docs/admin/resourcequota/ - - title: Scheduled Jobs - path: /docs/user-guide/scheduled-jobs/ + - title: Cron Jobs + path: /docs/user-guide/cron-jobs/ - title: Secrets path: /docs/user-guide/secrets/ - title: Security Context @@ -244,11 +244,11 @@ toc: - title: Kubernetes Identity and Access Management path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/access.md - title: Kubernetes OpenVSwitch GRE/VxLAN networking - path: /docs/admin/ovs-networking/ + path: /docs/admin/ovs-networking/ - title: Security Contexts path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security_context.md - title: Security in Kubernetes - path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security.md + path: https://github.com/kubernetes/kubernetes/blob/release-1.3/docs/design/security.md - title: Federation section: diff --git a/docs/user-guide/scheduled-jobs.md b/docs/user-guide/cron-jobs.md similarity index 64% rename from docs/user-guide/scheduled-jobs.md rename to docs/user-guide/cron-jobs.md index 0f1a16e2be..6d88997cb3 100644 --- a/docs/user-guide/scheduled-jobs.md +++ b/docs/user-guide/cron-jobs.md @@ -9,19 +9,22 @@ assignees: * TOC {:toc} -## What is a _Scheduled Job_? +## What is a _Cron Job_? -A _Scheduled Job_ manages time based [Jobs](/docs/user-guide/jobs/), namely: +A _Cron 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 +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 `*`, +**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:**: ScheduledJob resource was introduced in Kubernetes version 1.4, but starting +from version 1.5 its current name is CronJob. + A typical use case is: * Schedule a job execution at a given point in time. @@ -29,36 +32,36 @@ A typical use case is: ### 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. +You need a working Kubernetes cluster at version >= 1.4 (for ScheduledJob), >= 1.5 (for CronJobs), +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 Cron Jobs on a hosted Kubernetes provider that has disabled alpha resources. -## Creating a Scheduled Job +## Creating a Cron Job -Here is an example Scheduled Job. Every minute, it runs a simple job to print current time and then say +Here is an example Cron 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" %} +{% include code.html language="yaml" file="cronjob.yaml" ghlink="/docs/user-guide/cronjob.yaml" %} -Run the example scheduled job by downloading the example file and then running this command: +Run the example cron job by downloading the example file and then running this command: ```shell -$ kubectl create -f ./sj.yaml -scheduledjob "hello" created +$ kubectl create -f ./cronjob.yaml +cronjob "hello" created ``` -Alternatively, use `kubectl run` to create a scheduled job without writing full config: +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" -scheduledjob "hello" created +cronjob "hello" created ``` -After creating the scheduled job, get its status using this command: +After creating the cron job, get its status using this command: ```shell -$ kubectl get scheduledjob hello +$ kubectl get cronjob hello NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE hello */1 * * * * False 0 ``` @@ -73,10 +76,10 @@ 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: +Now you've seen one running job scheduled by "hello". We can stop watching it and get the cron job again: ```shell -$ kubectl get scheduledjob hello +$ kubectl get cronjob hello NAME SCHEDULE SUSPEND ACTIVE LAST-SCHEDULE hello */1 * * * * False 0 Mon, 29 Aug 2016 14:34:00 -0700 ``` @@ -99,17 +102,17 @@ Mon Aug 29 21:34:09 UTC 2016 Hello from the Kubernetes cluster ``` -## Deleting a Scheduled Job +## Deleting a Cron Job -Once you don't need a scheduled job anymore, simply delete it with `kubectl`: +Once you don't need a cron job anymore, simply delete it with `kubectl`: ```shell -$ kubectl delete scheduledjob hello -scheduledjob "hello" deleted +$ kubectl delete cronjob hello +cronjob "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: +be deleted. To clean up those jobs and pods, you need to list all jobs created by the cron job, and delete them all: ```shell $ kubectl get jobs @@ -124,29 +127,29 @@ 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 +Once the jobs are deleted, the pods created by them are deleted as well. Note that all jobs created by cron 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 +## Cron Job Limitations -A scheduled job creates a job object _about_ once per execution time of its schedule. We say "about" because there +A cron 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. +of the set of pods. A cron job does not examine pods at all. -## Writing a Scheduled Job Spec +## Writing a Cron Job Spec -As with all other Kubernetes configs, a scheduled job needs `apiVersion`, `kind`, and `metadata` fields. For general +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), [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). +A cron 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. +**Note:** All modifications to a cron job, especially its `.spec`, will be applied only to the next run. ### Schedule @@ -168,14 +171,14 @@ 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: +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 scheduled job. If there are multiple -scheduled jobs, their respective jobs are always allowed to run concurrently. +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 diff --git a/docs/user-guide/sj.yaml b/docs/user-guide/cronjob.yaml similarity index 95% rename from docs/user-guide/sj.yaml rename to docs/user-guide/cronjob.yaml index 8f247282d1..cdb1c469a1 100644 --- a/docs/user-guide/sj.yaml +++ b/docs/user-guide/cronjob.yaml @@ -1,5 +1,5 @@ apiVersion: batch/v2alpha1 -kind: ScheduledJob +kind: CronJob metadata: name: hello spec: diff --git a/docs/user-guide/jobs.md b/docs/user-guide/jobs.md index 4e42b8fcef..89ce8c708c 100644 --- a/docs/user-guide/jobs.md +++ b/docs/user-guide/jobs.md @@ -374,6 +374,6 @@ driver, and then cleans up. An advantage of this approach is that the overall process gets the completion guarantee of a Job object, but complete control over what pods are created and how work is assigned to them. -## Scheduled Jobs +## Cron Jobs -Support for creating Jobs at specified times/dates (i.e. cron) is available in Kubernetes [1.4](https://github.com/kubernetes/kubernetes/pull/11980). More information is available in the [scheduled job documents](http://kubernetes.io/docs/user-guide/scheduled-jobs/) +Support for creating Jobs at specified times/dates (i.e. cron) is available in Kubernetes [1.4](https://github.com/kubernetes/kubernetes/pull/11980). More information is available in the [cron job documents](http://kubernetes.io/docs/user-guide/cron-jobs/) diff --git a/docs/user-guide/kubectl-cheatsheet.md b/docs/user-guide/kubectl-cheatsheet.md index 14e6850f37..b207542e85 100644 --- a/docs/user-guide/kubectl-cheatsheet.md +++ b/docs/user-guide/kubectl-cheatsheet.md @@ -141,7 +141,7 @@ $ kubectl rolling-update frontend-v1 frontend-v2 --rollback # Abort exist $ cat pod.json | kubectl replace -f - # Replace a pod based on the JSON passed into stdin # Force replace, delete and then re-create the resource. Will cause a service outage. -$ kubectl replace --force -f ./pod.json +$ kubectl replace --force -f ./pod.json # Create a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000 $ kubectl expose rc nginx --port=80 --target-port=8000 @@ -251,7 +251,7 @@ Resource type | Abbreviated alias `replicasets` |`rs` `replicationcontrollers` |`rc` `resourcequotas` |`quota` -`scheduledjob` | +`cronjob` | `secrets` | `serviceaccount` |`sa` `services` |`svc` diff --git a/docs/user-guide/kubectl-conventions.md b/docs/user-guide/kubectl-conventions.md index a22973f16f..291eb712fa 100644 --- a/docs/user-guide/kubectl-conventions.md +++ b/docs/user-guide/kubectl-conventions.md @@ -38,7 +38,7 @@ In order for `kubectl run` to satisfy infrastructure as code: * Deployment - use `deployment/v1beta1`. * Job (using `extension/v1beta1` endpoint) - use `job/v1beta1`. * Job - use `job/v1`. -* ScheduledJob - use `scheduledjob/v2alpha1`. +* CronJob - use `cronjob/v2alpha1`. Additionally, if you didn't specify a generator flag, other flags will suggest using a specific generator. Below table shows which flags force using specific generators, @@ -50,7 +50,7 @@ depending on your cluster version: | Replication Controller | `--generator=run/v1` | `--generator=run/v1` | `--generator=run/v1` | `--restart=Always` | | Deployment | `--restart=Always` | `--restart=Always` | `--restart=Always` | N/A | | Job | `--restart=OnFailure` | `--restart=OnFailure` | `--restart=OnFailure` OR `--restart=Never` | N/A | -| Scheduled Job | `--schedule=` | N/A | N/A | N/A | +| Cron Job | `--schedule=` | N/A | N/A | N/A | Note that these flags will use a default generator only when you have not specified any flag. This also means that combining `--generator` with other flags won't diff --git a/docs/user-guide/kubectl/kubectl_run.md b/docs/user-guide/kubectl/kubectl_run.md index c0a7d9cc6d..9b3dfb409e 100644 --- a/docs/user-guide/kubectl/kubectl_run.md +++ b/docs/user-guide/kubectl/kubectl_run.md @@ -50,7 +50,7 @@ kubectl run nginx --image=nginx --command -- ... # Start the perl container to compute π to 2000 places and print it out. kubectl run pi --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)' -# Start the scheduled job to compute π to 2000 places and print it out every 5 minutes. +# Start the cron job to compute π to 2000 places and print it out every 5 minutes. kubectl run pi --schedule="0/5 * * * ?" --image=perl --restart=OnFailure -- perl -Mbignum=bpi -wle 'print bpi(2000)' ``` diff --git a/test/examples_test.go b/test/examples_test.go index 7e5660c4f9..63fea3c5bc 100644 --- a/test/examples_test.go +++ b/test/examples_test.go @@ -242,7 +242,7 @@ func TestExampleObjectSchemas(t *testing.T) { "redis-resource-deployment": &extensions.Deployment{}, "redis-secret-deployment": &extensions.Deployment{}, "run-my-nginx": &extensions.Deployment{}, - "sj": &batch.CronJob{}, + "cronjob": &batch.CronJob{}, }, "../docs/admin": { "daemon": &extensions.DaemonSet{},