Improvement for k8s.io/docs/concepts/workloads/controllers/cron-jobs/

[tbrownaw]

There is a section that starts:

For every CronJob, the CronJob Controller checks how many schedules it missed in the duration from its last scheduled time until now. If there are more than 100 missed schedules, then it does not start the Job and logs the error.

Cannot determine if job needs to be started. Too many missed start time (> 100). Set or decrease .spec.startingDeadlineSeconds or check clock skew.

I'm running a 1.31 version, and this message and described behavior does not match what I observe. The first sentence "Cannot determine if job needs to be started." is missing, and the wording of the rest is slightly different. Additionally, the job does in fact start once the previous job completes.

The actual message I see is

too many missed start times. Set or decrease .spec.startingDeadlineSeconds or check clock skew

CronJob used for testing (best run overnight because of how long the sleep is):

apiVersion: batch/v1
kind: CronJob
metadata:
  name: testcronjob
spec:
  jobTemplate:
    metadata:
      name: testcronjob
    spec:
      template:
        spec:
          containers:
          - image: bash
            args:
              - "-c"
              - "sleep 12125"
            name: testcronjob
            resources: {}
          restartPolicy: OnFailure
  schedule: '* * * * *'
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 10
  failedJobsHistoryLimit: 10

Version:

$ kubectl version
Client Version: v1.32.0
Kustomize Version: v5.5.0
Server Version: v1.31.4+k3s1

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[xirehat]

@tbrownaw You’re right about the documentation. The current behavior is implemented [here]

I think this would be a good first contribution to the Kubernetes docs, fixing this would help others.

However, I don’t understand this part:

Additionally, the job does in fact start once the previous job completes.

Could you clarify what you mean?

[tbrownaw]

The docs page says that once there are too many missed schedules the Job won't be started any more, because of the missed schedules.

In experimenting with the test cronjob above, this doesn't happen. As soon as the previous run finishes and the concurrencyPolicy stops forbidding a new job to be scheduled, it is scheduled.

[xirehat]

What you’re describing sounds like a steady state, where each job finishes successfully and the next one starts. The documentation, however, refers to the case where a job fails too many times; after a certain threshold (the exact calculation is unclear, see this PR: kubernetes/kubernetes#118940), the job stops running, and the above error is shown.