> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CronJobs

> Schedule and manage time-based jobs in Kubernetes

CronJobs create Jobs on a time-based schedule. They are useful for periodic tasks like backups, report generation, sending emails, and cleanup operations.

## Key Concepts

<CardGroup cols={2}>
  <Card title="CronJob" icon="timer">
    A resource that creates Jobs on a recurring schedule defined by cron syntax.
  </Card>

  <Card title="Schedule" icon="calendar-clock">
    Cron expression defining when Jobs should be created (e.g., `0 * * * *` for hourly).
  </Card>

  <Card title="Job" icon="play">
    A single execution instance created by the CronJob at each scheduled time.
  </Card>

  <Card title="Suspend" icon="pause">
    Temporarily stop scheduling new Jobs without deleting the CronJob.
  </Card>
</CardGroup>

## Required Permissions

| Action            | Permission                                     |
| ----------------- | ---------------------------------------------- |
| View cronjobs     | `iam:project:infrastructure:kubernetes:read`   |
| Run now (trigger) | `iam:project:infrastructure:kubernetes:write`  |
| Suspend/Resume    | `iam:project:infrastructure:kubernetes:write`  |
| Create cronjob    | `iam:project:infrastructure:kubernetes:write`  |
| Edit cronjob      | `iam:project:infrastructure:kubernetes:write`  |
| Delete cronjob    | `iam:project:infrastructure:kubernetes:delete` |

## CronJob Status Values

| Status        | Description                                         |
| ------------- | --------------------------------------------------- |
| **Active**    | CronJob is enabled and will create Jobs on schedule |
| **Suspended** | CronJob is paused and will not create new Jobs      |

## Cron Schedule Format

CronJobs use standard cron syntax with five fields:

```
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday = 0)
│ │ │ │ │
* * * * *
```

**Common schedules:**

| Schedule              | Cron Expression |
| --------------------- | --------------- |
| Every minute          | `* * * * *`     |
| Every hour            | `0 * * * *`     |
| Every day at midnight | `0 0 * * *`     |
| Every Monday at 9am   | `0 9 * * 1`     |
| Every 15 minutes      | `*/15 * * * *`  |
| Weekdays at 6am       | `0 6 * * 1-5`   |

**Shorthand expressions:**

| Shorthand  | Equivalent  |
| ---------- | ----------- |
| `@hourly`  | `0 * * * *` |
| `@daily`   | `0 0 * * *` |
| `@weekly`  | `0 0 * * 0` |
| `@monthly` | `0 0 1 * *` |
| `@yearly`  | `0 0 1 1 *` |

## How to View CronJobs

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view CronJobs across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find CronJobs by name or schedule, or filter by status.
  </Step>
</Steps>

## How to View CronJob Details

<Steps>
  <Step title="Find the CronJob">
    Locate the CronJob in the list.
  </Step>

  <Step title="Click CronJob Name">
    Click on the CronJob name to open the detail drawer.
  </Step>

  <Step title="Review Details">
    View CronJob information including:

    * Schedule configuration
    * Last schedule time
    * Active Jobs count
    * Job template specification
    * Container details
    * Events
  </Step>
</Steps>

## How to Run a CronJob Immediately

Trigger a CronJob to run now without waiting for the next scheduled time.

<Steps>
  <Step title="Find the CronJob">
    Locate the CronJob in the list.
  </Step>

  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the CronJob row.
  </Step>

  <Step title="Click Run Now">
    Select **Run Now** to trigger immediate execution.
  </Step>

  <Step title="Verify">
    A new Job is created with the name format: `{cronjob-name}-manual-{timestamp}`.
  </Step>
</Steps>

<Info>
  Manually triggered Jobs have the label `triggered-by: manual` to distinguish them from scheduled Jobs.
</Info>

## How to Suspend a CronJob

Suspend a CronJob to temporarily stop scheduling new Jobs.

<Steps>
  <Step title="Find the CronJob">
    Locate the active CronJob in the list.
  </Step>

  <Step title="Open Actions Menu">
    Click the actions menu on the CronJob row.
  </Step>

  <Step title="Click Suspend">
    Select **Suspend** from the menu.
  </Step>

  <Step title="Verify">
    The status changes to Suspended. No new Jobs will be scheduled.
  </Step>
</Steps>

<Warning>
  Suspending a CronJob does not affect Jobs that are already running. They will continue to completion.
</Warning>

## How to Resume a CronJob

Resume a suspended CronJob to restart scheduling.

<Steps>
  <Step title="Find the Suspended CronJob">
    Locate the suspended CronJob in the list.
  </Step>

  <Step title="Open Actions Menu">
    Click the actions menu on the CronJob row.
  </Step>

  <Step title="Click Resume">
    Select **Resume** from the menu.
  </Step>

  <Step title="Verify">
    The status changes to Active. Jobs will be scheduled according to the cron expression.
  </Step>
</Steps>

## How to Create a CronJob

<Steps>
  <Step title="Click Create CronJob">
    Click the **Create CronJob** button in the page header.
  </Step>

  <Step title="Write YAML">
    Enter the CronJob manifest in YAML format. Key fields:

    * `spec.schedule` - Cron expression
    * `spec.jobTemplate` - Job template specification
    * `spec.concurrencyPolicy` - How to handle concurrent Jobs
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the CronJob.
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

## How to Edit a CronJob

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the CronJob row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the editor.
  </Step>

  <Step title="Modify Spec">
    Edit the CronJob specification. Common changes:

    * Schedule expression
    * Container image or command
    * Concurrency policy
    * History limits
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

## How to Delete a CronJob

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the CronJob row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion.
  </Step>
</Steps>

<Warning>
  Deleting a CronJob does not delete Jobs that have already been created. Running Jobs will continue to completion.
</Warning>

## Concurrency Policies

Control what happens when a new Job is scheduled while a previous Job is still running:

| Policy      | Description                               |
| ----------- | ----------------------------------------- |
| **Allow**   | Allow concurrent Jobs (default)           |
| **Forbid**  | Skip new Job if previous is still running |
| **Replace** | Cancel running Job and start new one      |

## History Limits

CronJobs track completed and failed Jobs for review:

| Setting                      | Description                       | Default |
| ---------------------------- | --------------------------------- | ------- |
| `successfulJobsHistoryLimit` | Number of successful Jobs to keep | 3       |
| `failedJobsHistoryLimit`     | Number of failed Jobs to keep     | 1       |

<Tip>
  Set higher history limits for debugging or lower limits to reduce resource usage.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CronJob not creating Jobs">
    * Check if CronJob is suspended
    * Verify schedule syntax is correct
    * Check concurrency policy - previous Job may still be running
    * Review CronJob events for errors
    * Verify time zone considerations
  </Accordion>

  <Accordion title="Jobs failing immediately">
    * Check container image exists and is accessible
    * Verify command and arguments are correct
    * Check required ConfigMaps/Secrets exist
    * Review Job pod logs for error messages
  </Accordion>

  <Accordion title="Missed schedules">
    * If more than 100 schedules are missed, CronJob stops
    * Check `startingDeadlineSeconds` setting
    * Verify cluster has available resources
    * Review CronJob events
  </Accordion>

  <Accordion title="Jobs running longer than expected">
    * Set `activeDeadlineSeconds` on Job template to limit runtime
    * Consider using Forbid concurrency policy
    * Check for resource constraints slowing execution
  </Accordion>

  <Accordion title="Too many Jobs accumulating">
    * Reduce `successfulJobsHistoryLimit` and `failedJobsHistoryLimit`
    * Jobs beyond limits are automatically cleaned up
    * Manually delete old Jobs if needed
  </Accordion>

  <Accordion title="Manual trigger not working">
    * Verify you have write permission
    * Check cluster connectivity
    * Review Job creation errors in events
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What time zone does the schedule use?">
    CronJobs use the kube-controller-manager's time zone by default, which is typically UTC. Kubernetes 1.27+ supports the `timeZone` field to specify a different zone.
  </Accordion>

  <Accordion title="Can I run a CronJob manually for testing?">
    Yes. Use the **Run Now** action to trigger immediate execution. The created Job will have `triggered-by: manual` label.
  </Accordion>

  <Accordion title="What happens to running Jobs when I delete a CronJob?">
    Running Jobs continue to completion. Only future scheduled Jobs are prevented. Delete Jobs separately if needed.
  </Accordion>

  <Accordion title="How do I see output from a CronJob?">
    View the logs of pods created by the Job. Navigate to Jobs page, find the Job, and view pod logs.
  </Accordion>

  <Accordion title="Can I change the schedule without recreating?">
    Yes. Edit the CronJob YAML and update the `spec.schedule` field. Changes apply to future schedules.
  </Accordion>

  <Accordion title="What's the difference between Forbid and Replace concurrency?">
    **Forbid** skips the new Job entirely if one is running. **Replace** cancels the running Job and starts a new one. Use Forbid for jobs that must complete; use Replace for jobs where only the latest run matters.
  </Accordion>

  <Accordion title="How do I prevent Jobs from running too long?">
    Set `spec.jobTemplate.spec.activeDeadlineSeconds` to limit Job runtime. The Job will be terminated if it exceeds this duration.
  </Accordion>

  <Accordion title="Can CronJobs restart failed Jobs?">
    CronJobs don't retry failed Jobs. Use Job's `backoffLimit` to retry within a single Job, or let the next scheduled run attempt the task.
  </Accordion>
</AccordionGroup>