CronJob

Um CronJob cria Jobs em um cronograma recorrente.

Um objeto CronJob é como uma linha em um arquivo crontab (tabela cron). Executa uma tarefa periodicamente em um determinado cronograma, escrito no formato Cron.

Ao criar o manifesto para um objeto CronJob, verifique se o nome que você forneceu é um nome de subdomínio DNS válido. O nome não pode ter mais que 52 caracteres. Esta limitação existe porque o controlador do CronJob adicionará automaticamente 11 caracteres ao final do nome escolhido para a tarefa, e o tamanho máximo de um nome de tarefa não pode ultrapassar 63 caracteres.

CronJob

CronJobs são úteis para criar tarefas periódicas e recorrentes, como a execução de backups ou o envio de mensagens de e-mail. CronJobs também permitem o agendamento de tarefas individuais para um horário específico, como por exemplo uma tarefa que é executada em um período maior de ociosidade do cluster.

Exemplo

Este manifesto de CronJob de exemplo imprime a data e horário atuais, seguidos da mensagem "Hello from the Kubernetes cluster", uma vez por minuto:

application/job/cronjob.yaml

apiVersion: batch/v1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: hello
            image: busybox
            imagePullPolicy: IfNotPresent
            command:
            - /bin/sh
            - -c
            - date; echo Hello from the Kubernetes cluster
          restartPolicy: OnFailure

(O artigo Running Automated Tasks with a CronJob demonstra este exemplo com maiores detalhes).

Sintaxe do cronograma cron

# ┌───────────── minuto (0 - 59)
# │ ┌───────────── hora (0 - 23)
# │ │ ┌───────────── dia do mês (1 - 31)
# │ │ │ ┌───────────── mês (1 - 12)
# │ │ │ │ ┌───────────── dia da semana (0 - 6) (domingo a sábado;
# │ │ │ │ │                                 7 também representa domingo em alguns sistemas operacionais)
# │ │ │ │ │
# │ │ │ │ │
# * * * * *

Por exemplo, a linha abaixo determina que a tarefa deve iniciar toda sexta-feira à meia-noite, bem como em todo dia 13 do mês à meia-noite:

0 0 13 * 5

É também possível gerar expressões de cronograma para CronJobs utilizando ferramentas da web como o crontab.guru.

Limitações do CronJob

Um CronJob cria uma tarefa aproximadamente uma vez por tempo de execução de seu cronograma. Dizemos "aproximadamente" porque existem circunstâncias em que duas tarefas podem ser criadas, e outras circunstâncias em que nenhuma tarefa será criada. Tentamos tornar estas situações raras, mas não é possível preveni-las completamente. Portanto, as tarefas devem ser idempotentes.

Se o valor da propriedade startingDeadlineSeconds (limite de tempo de inicialização, em segundos) estiver definido como um valor grande, ou não definido (o padrão), e se a propriedade concurrencyPolicy (política de concorrência) estiver definido como Allow (permitir), as tarefas sempre serão executadas pelo menos uma vez.

Para cada CronJob, o controlador do CronJob verifica quantos agendamentos foram perdidos no tempo entre o último horário agendado e o horário atual. Se houver mais de 100 agendamentos perdidos no período, o controlador não iniciará o trabalho e gerará a seguinte mensagem de erro:

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

É importante observar que, se o campo startingDeadlineSeconds estiver definido (não nil), o controlador contará quantas tarefas perdidas ocorreram a partir do valor de startingDeadlineSeconds até agora, e não do último horário agendado até agora. Por exemplo, se startingDeadlineSeconds for 200, o controlador contará quantas tarefas perdidas ocorreram nos últimos 200 segundos.

Um CronJob é considerado perdido se não for criado no horário agendado. Por exemplo, se concurrencyPolicy estiver definido como Forbid (proibir) e uma tentativa de agendamento de um novo CronJob ocorreu quando havia um agendamento anterior ainda em execução, o novo agendamento será contabilizado como perdido.

Por exemplo, suponha que um CronJob esteja definido para agendar uma nova tarefa a cada minuto, começando às 08:30:00, e seu campo startingDeadlineSeconds não esteja definido. Se o controlador do CronJob estiver inativo das 08:29:00 até as 10:21:00, a tarefa não será iniciada, pois o número de tarefas que perderam seus horários agendados é maior que 100.

Para ilustrar melhor este conceito, suponha que um CronJob esteja definido para agendar uma nova tarefa a cada minuto, começando às 08:30:00, e seu startingDeadlineSeconds esteja definido em 200 segundos. Se o controlador do CronJob estiver inativo no mesmo período do exemplo anterior (das 08:29:00 às 10:21:00), a tarefa ainda será iniciada às 10:22:00. Isso acontece pois o controlador agora verifica quantos agendamentos perdidos ocorreram nos últimos 200 segundos (ou seja, 3 agendamentos perdidos), ao invés de verificar o período entre o último horário agendado e o horário atual.

O CronJob é responsável apenas pela criação das tarefas que correspondem à sua programação, e a tarefa, por sua vez, é responsável pelo gerenciamento dos Pods que ele representa.

Versão do controlador

A partir da versão 1.21 do Kubernetes, a segunda versão do controlador do CronJob é a implementação ativada por padrão. Para desativar o controlador do CronJob padrão e utilizar a versão original do controlador do CronJob, é necessário adicionar o flag de feature gate CronJobControllerV2 à chamada do kube-controller-manager com o valor false (falso). Por exemplo:

--feature-gates="CronJobControllerV2=false"

Próximos passos

A página Cron expression format documenta o formato dos campos de agendamento do CronJob.

Para instruções sobre criação e utilização de tarefas cron, e para um exemplo de manifesto de CronJob, veja Running automated tasks with cron jobs.