Information in this document may be out of date

This document has an older update date than the original, so the information it contains may be out of date. If you're able to read English, see the English version for the most up-to-date information: CronJob

CronJob

ESTADO DA FUNCIONALIDADE: Kubernetes v1.21 [stable]

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:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "* * * * *"
  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)
# │ │ │ │ │
# │ │ │ │ │
# * * * * *
Expressão Descrição Equivalente a
@yearly (ou @annually) Executa uma vez por ano, à meia-noite de 1º de janeiro 0 0 1 1 *
@monthly Executa uma vez por mês, à meia-noite do primeiro dia do mês 0 0 1 * *
@weekly Executa uma vez por semana, à meia-noite de domingo 0 0 * * 0
@daily (ou @midnight) Executa uma vez por dia, à meia-noite 0 0 * * *
@hourly Executa uma vez por hora, no minuto zero 0 * * * *

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.