Skip to content

OSDOCS-16934 NODES-6 CQA Part 1 #114513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cbippley wants to merge 1 commit into
base: main
Choose a base branch
from
Open

OSDOCS-16934 NODES-6 CQA Part 1 #114513

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions modules/nodes-nodes-jobs-about.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
[id="nodes-nodes-jobs-about_{context}"]
= Understanding jobs and cron jobs

[role="_abstract"]
Jobs run one-time tasks and track completion status, while cron jobs schedule recurring tasks using cron expressions, supporting non-parallel, parallel with fixed completion count, and work queue execution patterns.

A job tracks the overall progress of a task and updates its status with information
about active, succeeded, and failed pods. Deleting a job cleans up any pods it created.
Jobs are part of the Kubernetes API, which can be managed
Expand Down
128 changes: 57 additions & 71 deletions modules/nodes-nodes-jobs-creating-cron.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,24 @@
[id="nodes-nodes-jobs-creating-cron_{context}"]
= Creating cron jobs

[role="_abstract"]
Create a cron job to schedule recurring tasks using cron expressions, configuring timezone, concurrency policies, history limits, and suspension behavior.

@ocpdocs-vale-bot ocpdocs-vale-bot Jul 1, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 [error] RedHat.TermsErrors: Use 'time zone' rather than 'timezone'. For more information, see RedHat.TermsErrors.


You create a cron job in {product-title} by creating a job object.

.Procedure
[NOTE]
====
You can also create and launch a cron job from a single command using `oc create cronjob`. The following command creates and launches a cron job similar to the one specified in the following example:

To create a cron job:
[source,terminal]
----
$ oc create cronjob pi --image=perl --schedule='*/1 * * * *' -- perl -Mbignum=bpi -wle 'print bpi(2000)'
----

With `oc create cronjob`, the `--schedule` option accepts schedules in link:https://en.wikipedia.org/wiki/Cron[cron format].
====

.Procedure

. Create a YAML file similar to the following:
+
Expand All @@ -22,46 +35,40 @@ kind: CronJob
metadata:
name: pi
spec:
schedule: "*/1 * * * *" <1>
timeZone: Etc/UTC <2>
concurrencyPolicy: "Replace" <3>
startingDeadlineSeconds: 200 <4>
suspend: true <5>
successfulJobsHistoryLimit: 3 <6>
failedJobsHistoryLimit: 1 <7>
jobTemplate: <8>
schedule: "*/1 * * * *"
timeZone: Etc/UTC
concurrencyPolicy: "Replace"
startingDeadlineSeconds: 200
suspend: true
successfulJobsHistoryLimit: 3
failedJobsHistoryLimit: 1
jobTemplate:
spec:
template:
metadata:
labels: <9>
labels:
parent: "cronjobpi"
spec:
containers:
- name: pi
image: perl
command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
restartPolicy: OnFailure <10>
restartPolicy: OnFailure
#...
----
+
<1> Schedule for the job specified in link:https://en.wikipedia.org/wiki/Cron[cron format]. In this example, the job will run every minute.
<2> An optional time zone for the schedule. See link:https://en.wikipedia.org/wiki/List_of_tz_database_time_zones[List of tz database time zones] for valid options. If not specified, the Kubernetes controller manager interprets the schedule relative to its local time zone.
<3> An optional concurrency policy, specifying how to treat concurrent jobs within a cron job. Only one of the following concurrent policies may be specified. If not specified, this defaults to allowing concurrent executions.
* `Allow` allows cron jobs to run concurrently.
* `Forbid` forbids concurrent runs, skipping the next run if the previous has not
finished yet.
* `Replace` cancels the currently running job and replaces
it with a new one.
<4> An optional 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 is no deadline.
<5> An optional flag allowing the suspension of a cron job. If set to `true`,
all subsequent executions will be suspended.
<6> The number of successful finished jobs to retain (defaults to 3).
<7> The number of failed finished jobs to retain (defaults to 1).
<8> Job template. This is similar to the job example.
<9> Sets a label for jobs spawned by this cron job.
<10> The restart policy of the pod. This does not apply to the job controller.
where:

`spec.schedule`:: Specifies the schedule for the job in link:https://en.wikipedia.org/wiki/Cron[cron format]. In this example, the job will run every minute.
`spec.timeZone`:: Optional: Specifies a time zone for the schedule. See link:https://en.wikipedia.org/wiki/List_of_tz_database_time_zones[List of tz database time zones] for valid options. If not specified, the Kubernetes controller manager interprets the schedule relative to its local time zone.
`spec.concurrencyPolicy`:: Optional: Specifies how to treat concurrent jobs within a cron job. Only one of the following concurrent policies may be specified. If not specified, this defaults to allowing concurrent executions: `Allow` (allows cron jobs to run concurrently), `Forbid` (forbids concurrent runs, skipping the next run if the previous has not finished yet), or `Replace` (cancels the currently running job and replaces it with a new one).
`spec.startingDeadlineSeconds`:: Optional: Specifies a 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 is no deadline.
`spec.suspend`:: Optional: Specifies a flag allowing the suspension of a cron job. If set to `true`, all subsequent executions will be suspended.
`spec.successfulJobsHistoryLimit`:: Specifies the number of successful finished jobs to retain (defaults to 3).
`spec.failedJobsHistoryLimit`:: Specifies the number of failed finished jobs to retain (defaults to 1).
`spec.jobTemplate`:: Specifies the job template. This is similar to the job example.
`spec.jobTemplate.spec.template.metadata.labels`:: Specifies labels for jobs spawned by this cron job.
`spec.jobTemplate.spec.template.spec.restartPolicy`:: Specifies the restart policy of the pod. This does not apply to the job controller.
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
ifdef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
[source,yaml]
Expand All @@ -71,51 +78,42 @@ kind: CronJob
metadata:
name: pi
spec:
schedule: "*/1 * * * *" <1>
concurrencyPolicy: "Replace" <2>
startingDeadlineSeconds: 200 <3>
suspend: true <4>
successfulJobsHistoryLimit: 3 <5>
failedJobsHistoryLimit: 1 <6>
jobTemplate: <7>
schedule: "*/1 * * * *"
concurrencyPolicy: "Replace"
startingDeadlineSeconds: 200
suspend: true
successfulJobsHistoryLimit: 3
failedJobsHistoryLimit: 1
jobTemplate:
spec:
template:
metadata:
labels: <8>
labels:
parent: "cronjobpi"
spec:
containers:
- name: pi
image: perl
command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
restartPolicy: OnFailure <9>
restartPolicy: OnFailure
----
+
<1> Schedule for the job specified in link:https://en.wikipedia.org/wiki/Cron[cron format]. In this example, the job will run every minute.
<2> An optional concurrency policy, specifying how to treat concurrent jobs within a cron job. Only one of the following concurrent policies may be specified. If not specified, this defaults to allowing concurrent executions.
* `Allow` allows cron jobs to run concurrently.
* `Forbid` forbids concurrent runs, skipping the next run if the previous has not
finished yet.
* `Replace` cancels the currently running job and replaces
it with a new one.
<3> An optional 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 is no deadline.
<4> An optional flag allowing the suspension of a cron job. If set to `true`,
all subsequent executions will be suspended.
<5> The number of successful finished jobs to retain (defaults to 3).
<6> The number of failed finished jobs to retain (defaults to 1).
<7> Job template. This is similar to the job example.
<8> Sets a label for jobs spawned by this cron job.
<9> The restart policy of the pod. This does not apply to the job controller.
where:

`spec.schedule`:: Specifies the schedule for the job in link:https://en.wikipedia.org/wiki/Cron[cron format]. In this example, the job will run every minute.
`spec.concurrencyPolicy`:: Optional: Specifies how to treat concurrent jobs within a cron job. Only one of the following concurrent policies may be specified. If not specified, this defaults to allowing concurrent executions: `Allow` (allows cron jobs to run concurrently), `Forbid` (forbids concurrent runs, skipping the next run if the previous has not finished yet), or `Replace` (cancels the currently running job and replaces it with a new one).
`spec.startingDeadlineSeconds`:: Optional: Specifies a 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 is no deadline.
`spec.suspend`:: Optional: Specifies a flag allowing the suspension of a cron job. If set to `true`, all subsequent executions will be suspended.
`spec.successfulJobsHistoryLimit`:: Specifies the number of successful finished jobs to retain (defaults to 3).
`spec.failedJobsHistoryLimit`:: Specifies the number of failed finished jobs to retain (defaults to 1).
`spec.jobTemplate`:: Specifies the job template. This is similar to the job example.
`spec.jobTemplate.spec.template.metadata.labels`:: Specifies labels for jobs spawned by this cron job.
`spec.jobTemplate.spec.template.spec.restartPolicy`:: Specifies the restart policy of the pod. This does not apply to the job controller.
+
[NOTE]
====
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.
====
endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]

. Create the cron job:
Expand All @@ -124,15 +122,3 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
----
$ oc create -f <file-name>.yaml
----

[NOTE]
====
You can also create and launch a cron job from a single command using `oc create cronjob`. The following command creates and launches a cron job similar to the one specified in the previous example:

[source,terminal]
----
$ oc create cronjob pi --image=perl --schedule='*/1 * * * *' -- perl -Mbignum=bpi -wle 'print bpi(2000)'
----

With `oc create cronjob`, the `--schedule` option accepts schedules in link:https://en.wikipedia.org/wiki/Cron[cron format].
====
64 changes: 29 additions & 35 deletions modules/nodes-nodes-jobs-creating.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,22 @@
[id="nodes-nodes-jobs-creating_{context}"]
= Creating jobs

[role="_abstract"]
Create a job to run a one-time task, configuring parallelism, completion count, time limits, retry policies, and automatic cleanup behavior.

You create a job in {product-title} by creating a job object.

.Procedure
[NOTE]
====
You can also create and launch a job from a single command using `oc create job`. The following command creates and launches a job similar to the one specified in the following example:

To create a job:
[source,terminal]
----
$ oc create job pi --image=perl -- perl -Mbignum=bpi -wle 'print bpi(2000)'
----
====

.Procedure

. Create a YAML file similar to the following:
+
Expand All @@ -21,53 +32,36 @@ kind: Job
metadata:
name: pi
spec:
parallelism: 1 <1>
completions: 1 <2>
activeDeadlineSeconds: 1800 <3>
backoffLimit: 6 <4>
ttlSecondsAfterFinished: 100 <5>
template: <6>
parallelism: 1
completions: 1
activeDeadlineSeconds: 1800
backoffLimit: 6
ttlSecondsAfterFinished: 100
template:
metadata:
name: pi
spec:
containers:
- name: pi
image: perl
command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
restartPolicy: OnFailure <7>
restartPolicy: OnFailure
#...
----
<1> Optional: Specify how many pod replicas a job should run in parallel; defaults to `1`.
* For non-parallel jobs, leave unset. When unset, defaults to `1`.
<2> Optional: Specify how many successful pod completions are needed to mark a job completed.
* For non-parallel jobs, leave unset. When unset, defaults to `1`.
* For parallel jobs with a fixed completion count, specify the number of completions.
* For parallel jobs with a work queue, leave unset. When unset defaults to the `parallelism` value.
<3> Optional: Specify the maximum duration the job can run.
<4> Optional: Specify the number of retries for a job. This field defaults to six.
<5> Optional: Specify the period of time in seconds after which the job should be automatically deleted upon completion. If set to '0', the job is immediately deleted after completion. If this field is not included, the job is not automatically deleted.
<6> Specify the template for the pod the controller creates.
<7> Specify the restart policy of the pod:
* `Never`. Do not restart the job.
* `OnFailure`. Restart the job only if it fails.
* `Always`. Always restart the job.
+
For details on how {product-title} uses restart policy with failed containers, see
the link:https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#example-states[Example States] in the Kubernetes documentation.
where:

`spec.parallelism`:: Optional: Specifies how many pod replicas a job should run in parallel; defaults to `1`. For non-parallel jobs, leave unset. When unset, defaults to `1`.
`spec.completions`:: Optional: Specifies how many successful pod completions are needed to mark a job completed. For non-parallel jobs, leave unset. When unset, defaults to `1`. For parallel jobs with a fixed completion count, specify the number of completions. For parallel jobs with a work queue, leave unset. When unset defaults to the `parallelism` value.
`spec.activeDeadlineSeconds`:: Optional: Specifies the maximum duration the job can run.
`spec.backoffLimit`:: Optional: Specifies the number of retries for a job. This field defaults to six.
`spec.ttlSecondsAfterFinished`:: Optional: Specifies the period of time in seconds after which the job should be automatically deleted upon completion. If set to '0', the job is immediately deleted after completion. If this field is not included, the job is not automatically deleted.
`spec.template`:: Specifies the template for the pod the controller creates.
`spec.template.spec.restartPolicy`:: Specifies the restart policy of the pod: `Never` (Do not restart the job), `OnFailure` (Restart the job only if it fails), or `Always` (Always restart the job). For details on how {product-title} uses restart policy with failed containers, see the link:https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#example-states[Example States] in the Kubernetes documentation.

. Create the job:
+
[source,terminal]
----
$ oc create -f <file-name>.yaml
----

[NOTE]
====
You can also create and launch a job from a single command using `oc create job`. The following command creates and launches a job similar to the one specified in the previous example:

[source,terminal]
----
$ oc create job pi --image=perl -- perl -Mbignum=bpi -wle 'print bpi(2000)'
----
====
Loading