> ## 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.

# Jobs

> Manage one-time batch jobs that run to completion in Kubernetes

Jobs run pods to completion for batch processing tasks. Unlike Deployments that run continuously, Jobs ensure a specified number of pods successfully terminate. They are ideal for one-time tasks, data processing, and batch operations.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Job" icon="briefcase">
    A controller that creates pods and ensures a specified number complete successfully.
  </Card>

  <Card title="Completions" icon="check">
    The number of pods that must complete successfully before the Job is done.
  </Card>

  <Card title="Parallelism" icon="layer-group">
    The maximum number of pods that can run simultaneously.
  </Card>

  <Card title="Backoff Limit" icon="rotate-left">
    The number of retries before marking the Job as failed.
  </Card>
</CardGroup>

## Required Permissions

| Action     | Permission                                     |
| ---------- | ---------------------------------------------- |
| View jobs  | `iam:project:infrastructure:kubernetes:read`   |
| Create job | `iam:project:infrastructure:kubernetes:write`  |
| Edit job   | `iam:project:infrastructure:kubernetes:write`  |
| Delete job | `iam:project:infrastructure:kubernetes:delete` |

## Job Status Values

| Status       | Description                            |
| ------------ | -------------------------------------- |
| **Complete** | All required completions succeeded     |
| **Failed**   | Job exceeded backoff limit or deadline |
| **Running**  | Pods are actively running              |
| **Pending**  | Job created but no pods started yet    |

## Job Metrics

| Metric          | Description                                    |
| --------------- | ---------------------------------------------- |
| **Completions** | Target number of successful pods (e.g., `3/5`) |
| **Succeeded**   | Number of pods that completed successfully     |
| **Failed**      | Number of pods that failed                     |
| **Active**      | Number of pods currently running               |
| **Duration**    | Time from Job start to completion              |

## How to View Jobs

<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 Jobs across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find Jobs by name, namespace, or status. Filter by status (Complete, Failed, Running, Pending).
  </Step>
</Steps>

## How to View Job Details

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

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

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

    * Completion progress (succeeded/target)
    * Active and failed pod counts
    * Duration and age
    * Container specifications
    * Events
  </Step>
</Steps>

## How to Create a Job

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

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

    * `spec.completions` - Number of successful completions required
    * `spec.parallelism` - Max concurrent pods
    * `spec.backoffLimit` - Max retries before failure
    * `spec.template` - Pod template specification
  </Step>

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

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

<Tip>
  For recurring tasks, use CronJobs instead. Jobs are for one-time executions.
</Tip>

## How to Edit a Job

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

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

  <Step title="Modify Spec">
    Edit the Job specification. Note that most Job fields are immutable after creation.
  </Step>

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

<Warning>
  Most Job spec fields are immutable after creation. To change completions, parallelism, or the pod template, delete and recreate the Job.
</Warning>

## How to Delete a Job

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

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

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

<Info>
  Deleting a Job uses the Background propagation policy by default. Pods created by the Job are deleted asynchronously.
</Info>

## Job Completion Modes

| Mode            | Description                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| **Non-indexed** | Job completes when `completions` pods succeed (default)                                              |
| **Indexed**     | Each pod gets an index (0 to completions-1), useful for parallel processing with distinct work items |

## Parallelism and Completions

| Setting                              | Behavior                                         |
| ------------------------------------ | ------------------------------------------------ |
| `completions: 1, parallelism: 1`     | Single pod, runs once (default)                  |
| `completions: N, parallelism: 1`     | Sequential execution of N pods                   |
| `completions: N, parallelism: M`     | Up to M pods run in parallel until N complete    |
| `completions: unset, parallelism: N` | Work queue pattern - pods run until one succeeds |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Job stuck in Pending">
    * Check if namespace has resource quotas blocking pod creation
    * Verify the container image exists and is accessible
    * Check for missing ConfigMaps, Secrets, or PVCs
    * Review Job events for scheduling errors
  </Accordion>

  <Accordion title="Job keeps failing (backoff limit reached)">
    * Check pod logs for application errors
    * Verify command and arguments are correct
    * Check if required environment variables are set
    * Review resource limits - pods may be OOMKilled
    * Increase `backoffLimit` if retries are expected
  </Accordion>

  <Accordion title="Job running longer than expected">
    * Set `spec.activeDeadlineSeconds` to limit total runtime
    * Check if pods are stuck waiting for resources
    * Review pod logs for slow operations
    * Consider increasing parallelism
  </Accordion>

  <Accordion title="Completed Jobs accumulating">
    * Set `ttlSecondsAfterFinished` to auto-delete completed Jobs
    * Jobs created by CronJobs are cleaned up by history limits
    * Manually delete old Jobs if needed
  </Accordion>

  <Accordion title="Pods not being created">
    * Verify Job status and events
    * Check for selector mismatch between Job and pod template
    * Review namespace resource quotas
    * Check ServiceAccount permissions if using custom accounts
  </Accordion>

  <Accordion title="Job completed but pods still running">
    * This shouldn't happen normally
    * Check if `ttlSecondsAfterFinished` is set
    * Manually delete orphaned pods if needed
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between Jobs and Deployments?">
    **Deployments** keep pods running indefinitely and replace them if they fail. **Jobs** run pods to completion and consider success when the task finishes. Use Jobs for batch tasks, Deployments for services.
  </Accordion>

  <Accordion title="How do I run a Job on a schedule?">
    Use a CronJob, which creates Jobs on a time-based schedule. The CronJob controller automatically creates Jobs at specified intervals.
  </Accordion>

  <Accordion title="What happens if a Job pod fails?">
    The Job controller creates a new pod up to `backoffLimit` times. Each retry uses exponential backoff (10s, 20s, 40s..., capped at 6 minutes). After exceeding the limit, the Job is marked Failed.
  </Accordion>

  <Accordion title="Can I restart a failed Job?">
    No. Jobs cannot be restarted. Delete the failed Job and create a new one with the same specification.
  </Accordion>

  <Accordion title="How do I limit how long a Job can run?">
    Set `spec.activeDeadlineSeconds` to specify the maximum runtime in seconds. The Job will be terminated if it exceeds this duration, regardless of completion status.
  </Accordion>

  <Accordion title="What is ttlSecondsAfterFinished?">
    This field automatically deletes completed Jobs after the specified number of seconds. For example, `ttlSecondsAfterFinished: 3600` deletes the Job one hour after completion.
  </Accordion>

  <Accordion title="How do I process a work queue with Jobs?">
    Use a Job with `parallelism` set but `completions` unset. Each pod processes items from a shared queue until the queue is empty, then exits successfully.
  </Accordion>

  <Accordion title="What's the default backoff limit?">
    The default `backoffLimit` is 6, meaning Kubernetes will retry failed pods up to 6 times before marking the Job as failed.
  </Accordion>

  <Accordion title="Can I update a running Job?">
    Most fields are immutable. You can update some metadata (labels, annotations) but not the pod template, completions, or parallelism. For changes, delete and recreate the Job.
  </Accordion>
</AccordionGroup>