CronDrive
Guías

CronJob de Kubernetes: qué revisar si no se ejecuta y cómo iniciarlo manualmente

Actualizada el 15 de noviembre de 2026

Un CronJob crea un Job en cada momento programado. El Job crea un pod, que aloja el contenedor donde se ejecuta el comando. Cuando un CronJob “no se ejecuta”, primero identifica dónde se detuvo el proceso: ¿no se creó el job, el pod no pudo iniciar o el comando falló? Los ejemplos usan un CronJob llamado backup; reemplázalo por el nombre del tuyo. Si está en otro namespace (espacio de nombres), agrega -n <namespace> a los comandos y sustituye <namespace> por su nombre.

1. ¿Creó un job?

kubectl get cronjob backup
kubectl get jobs --sort-by=.metadata.creationTimestamp
kubectl describe cronjob backup

kubectl get cronjob muestra el horario, si está suspendido (SUSPEND), cuántos jobs están en ejecución (ACTIVE) y hace cuánto creó el último (LAST SCHEDULE). kubectl describe termina con los eventos del CronJob, donde el controlador dice qué hizo y por qué.

Los nombres de los jobs incluyen el nombre del CronJob y un sufijo numérico; por ejemplo, backup-29911860. Si no hay un job para la hora que esperabas, revisa los puntos 2 a 5. Si lo hay, pasa al punto 6.

2. ¿Está suspendido?

Con spec.suspend: true, el CronJob conserva su horario, pero deja de crear jobs. Esta opción puede haberse activado manualmente durante un incidente o mediante la configuración de un chart de Helm. Para reanudar la creación de jobs:

kubectl patch cronjob backup -p '{"spec":{"suspend":false}}'

Las ejecuciones que se saltó mientras estaba suspendido cuentan como perdidas. Si el CronJob no tiene startingDeadlineSeconds, al activarlo inicia de inmediato un job por la más reciente.

3. ¿El horario está en la zona horaria que crees?

Sin spec.timeZone, el horario usa la zona horaria del componente kube-controller-manager del clúster. Suele ser UTC; en ese caso, 0 3 * * * programa la ejecución para las 3:00 UTC. Para indicar otra zona horaria:

spec:
  schedule: "0 3 * * *"
  timeZone: "America/Santiago"

timeZone es estable desde Kubernetes 1.27. Una zona escrita en el horario, como CRON_TZ=America/Santiago 0 3 * * *, no está soportada: Kubernetes la rechaza al crear o actualizar el CronJob.

El horario tiene los cinco campos de un crontab, con pasos como */5, y acepta @hourly, @daily, @weekly, @monthly y @yearly. Pégalo en el probador de expresiones cron para ver cuándo se ejecuta en tu zona horaria. Más detalles en la zona horaria de cron.

4. ¿Se le pasó el plazo para iniciar?

spec.startingDeadlineSeconds es cuánto puede atrasarse el inicio de un job. Si el CronJob no logra crearlo dentro de esos segundos desde la hora programada, porque el controlador estaba caído o la ejecución anterior seguía en curso, se salta esa ejecución y espera la siguiente.

  • Un plazo muy corto se salta ejecuciones. Con menos de 10 segundos el job puede no crearse nunca: el controlador revisa los CronJobs cada 10 segundos.
  • Sin él, no hay plazo: un job que no pudo iniciar a tiempo inicia cuando puede.
  • Tras mucho tiempo sin ejecutarse, solo se ejecuta la última. Si el CronJob perdió más de 100 ejecuciones, registra un evento TooManyMissedTimes e inicia un solo job, por la más reciente. En versiones anteriores de Kubernetes dejaba de crear jobs, con el error too many missed start time (> 100), hasta que le ponías startingDeadlineSeconds.

5. ¿La ejecución anterior sigue en curso?

spec.concurrencyPolicy define qué hacer cuando llega la hora de una ejecución y la anterior no ha terminado:

  • Allow, el valor predeterminado, permite iniciar la nueva ejecución. Las ejecuciones que tardan más que el intervalo se acumulan.
  • Forbid omite la nueva ejecución. Un job que no termina bloquea las siguientes: ACTIVE permanece en 1 y LAST SCHEDULE deja de avanzar.
  • Replace detiene la que está en curso e inicia la nueva.

Con Forbid, puedes eliminar el job bloqueado con kubectl delete job <nombre-del-job>. Para evitar que vuelva a ocurrir, configura activeDeadlineSeconds en spec.jobTemplate.spec del CronJob. Si un job supera ese límite de tiempo, Kubernetes detiene sus pods y lo marca como fallido. Para evitar ejecuciones simultáneas en un crontab, consulta la guía de flock.

6. El job existe, pero el pod no inicia o falla

Reemplaza backup-29911860 por el nombre del job que quieres revisar y <pod> por el nombre de su pod:

kubectl get pods --selector=job-name=backup-29911860
kubectl describe pod <pod>
kubectl logs job/backup-29911860

El estado del pod dice dónde se detuvo:

  • ImagePullBackOff o ErrImagePull: la imagen no existe con ese nombre y esa etiqueta, o falta el secreto para descargarla del registro.
  • Pending: ningún nodo tiene espacio para él, o ninguno coincide con su selector de nodos o sus tolerancias. Los eventos de kubectl describe pod dicen cuál.
  • CreateContainerConfigError: usa un Secret o un ConfigMap que no existe en el namespace.
  • Error: el comando se ejecutó y falló. kubectl logs muestra su salida, y kubectl describe pod su código de salida: qué significa cada uno está en los códigos de salida de un cron job. Con 137 y el motivo OOMKilled, superó su límite de memoria.

Un job reintenta un pod que falla: 6 veces, salvo que pongas otro backoffLimit, esperando más cada vez, y después queda marcado como fallido. El restartPolicy del pod tiene que ser Never u OnFailure.

Al eliminar un job antiguo, también se eliminan sus pods y los logs disponibles mediante kubectl logs. Por defecto, un CronJob conserva los últimos 3 jobs que terminaron bien y el último que falló. Para conservar un historial más amplio, aumenta successfulJobsHistoryLimit y failedJobsHistoryLimit.

Ejecútalo ahora

kubectl create job crea un job con la plantilla del CronJob, sin esperar su horario. También funciona con un CronJob suspendido:

kubectl create job --from=cronjob/backup backup-manual
kubectl wait --for=condition=complete job/backup-manual --timeout=10m
kubectl logs job/backup-manual
kubectl delete job backup-manual

kubectl wait termina cuando el job se completa correctamente. Si el job falla, el comando sigue esperando hasta agotar el tiempo límite; puedes revisar el estado con kubectl get job backup-manual desde otra terminal. El nombre debe ser único en el namespace: elimina el job cuando termines de revisarlo o usa otro nombre la próxima vez.

Un cambio en el CronJob se aplica a los jobs que crea desde entonces, no a los que ya están en ejecución.

Entérate cuando no se ejecute

Kubernetes no le avisa a nadie cuando un job falla, y un CronJob que queda suspendido o pierde sus ejecuciones no deja ningún job fallido que mirar. Para enterarte, el job tiene que avisar de cada ejecución a un monitor que la espera: cuándo empieza y cómo termina. Con CronDrive, rodea el comando con dos llamadas:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: backup
spec:
  schedule: "0 3 * * *"
  timeZone: "America/Santiago"
  concurrencyPolicy: Forbid
  startingDeadlineSeconds: 600
  jobTemplate:
    spec:
      activeDeadlineSeconds: 3600
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: backup
              image: registry.example.com/backup:1.4
              command:
                - /bin/sh
                - -c
                - |
                  url=https://job.crondrive.com/<token>
                  curl -fsS -m 10 "$url/start/$HOSTNAME"
                  /app/backup.sh
                  code=$?
                  curl -fsS -m 10 "$url/end/$code/$HOSTNAME"
                  exit $code

$HOSTNAME identifica el pod y permite asociar el aviso de inicio con el de finalización. exit $code devuelve a Kubernetes el código de salida del comando. La imagen debe incluir curl. Cuando el job reintenta, cada pod informa su propia ejecución.

Crea el job en CronDrive con el mismo horario y la misma zona horaria del CronJob. CronDrive te avisa si una ejecución falla, si no empieza dentro del margen de espera o si supera el tiempo máximo que configuraste para terminar. Así puedes detectar un CronJob suspendido, un pod que no puede descargar su imagen o un job que no termina.

CronDrive te avisa por email, o en Slack, cuando un job con este horario falla, o no se inicia o no termina a tiempo. Gratis hasta 15 jobs.

Lo que verías con este horario

Un ejemplo con las últimas ejecuciones de este horario y resultados inventados: una falló y otra no se ejecutó.

Horas en UTC.

Hora
sáb 14 nov, 03:00 A tiempo Inició 03:00, terminó 03:13, duró 13 min.
vie 13 nov, 03:00 No se ejecutó Alertas enviadas a las 03:05 y 03:30.
jue 12 nov, 03:00 A tiempo Inició 03:00, terminó 03:14, duró 14 min.
mié 11 nov, 03:00 Falló con código 1 Alerta enviada a las 03:04. Inició 03:00, terminó 03:04, duró 4 min.
mar 10 nov, 03:00 A tiempo Inició 03:00, terminó 03:13, duró 13 min.
lun 9 nov, 03:00 A tiempo Inició 03:00, terminó 03:14, duró 14 min.

La alerta de la ejecución que falló

Email de CronDrive, mié 11 nov, 03:04

Falló (código 1): "Tu job"

El job "Tu job" falló con el código de salida 1.

Si conectas Slack, el mismo mensaje llega a tu canal.

El cambio en tu crontab

0 3 * * * curl -fsS -m 10 https://job.crondrive.com/uG2Exw/start/$$; /path/to/job.sh; curl -fsS -m 10 https://job.crondrive.com/uG2Exw/end/$?/$$

Dos llamadas alrededor de tu comando, en la misma línea. La línea de tu job trae su propio token.

Monitorear este horario

O deja que tu agente de IA configure todos los cron jobs de tu servidor:

Pega esto en Claude Code, Cursor, Codex o tu agente de IA:

Configura CronDrive para vigilar los cron jobs de este servidor. Sigue las instrucciones de https://crondrive.com/es/docs/agents