CronJobs

Autopilot Padrão

---

Os CronJobs geralmente estão disponíveis no Google Kubernetes Engine (GKE) versão 1.21 e posteriores. Neste documento, explicamos como executar CronJobs no GKE. Os CronJobs são um recurso integrado do Kubernetes. Para mais detalhes, consulte a documentação do Kubernetes sobre CronJobs.

Visão geral

Os CronJobs criam jobs do Kubernetes em uma programação repetida. Os CronJobs permitem automatizar tarefas comuns, como fazer backups, criar relatórios, enviar e-mails ou tarefas de limpeza.

Os CronJobs são criados, gerenciados, escalonados e excluídos da mesma forma que os jobs. O número exato de objetos de job criados depende de vários fatores. Para mais informações, consulte Limitações do CronJob.

Para saber mais sobre jobs, consulte Como executar um job.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ativar a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
  Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Definindo os locais padrão, você evita erros como este na CLI gcloud: One of [--zone, --region] must be supplied: Please specify location.

Como criar um CronJob

Você pode criar um CronJob usando um arquivo de manifesto. Por exemplo, o seguinte manifesto YAML imprime o horário atual e uma string a cada minuto, mantendo os valores padrão dos parâmetros do CronJob:

# cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  concurrencyPolicy: Allow
  startingDeadlineSeconds: 100
  suspend: false
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: hello
            image: busybox
            args:
            - /bin/sh
            - -c
            - date; echo "Hello, World!"
          restartPolicy: OnFailure

Observação: se o cluster executar versões do GKE anteriores à 1.21, especifique batch/v1beta1 no campo apiVersion.

Para criar esse CronJob, salve o manifesto YAML em um arquivo e aplique-o ao cluster:

kubectl apply -f PATH_TO_FILE

Substitua PATH_TO_FILE pelo caminho para o manifesto YAML.

Como configurar um CronJob

É possível especificar os seguintes parâmetros ao criar um CronJob:

• Quando executar o CronJob
• O que o CronJob faz
• Prazo para o CronJob começar
• Permitir jobs simultâneos para o CronJob
• Novos jobs suspensos
• Execuções que o CronJob salva no histórico

Como especificar quando o CronJob é executado

O campo spec.schedule define quando e com que frequência o CronJob é executado, usando o formato crontab padrão do Unix. Todos os horários do CronJob estão em UTC: Há cinco campos, separados por espaços. Esses campos representam:

1. Minutos (entre 0 e 59)
2. Horas (entre 0 e 23)
3. Dia do mês (entre 1 e 31)
4. Mês (entre 1 e 12)
5. Dia da semana (entre 0 e 6 a partir de domingo)

É possível usar os caracteres especiais a seguir em qualquer um dos campos spec.schedule:

• ? é um valor de caractere curinga que corresponde a um único caractere.
• * é um valor curinga que corresponde a zero ou mais caracteres.
• / permite que você especifique um intervalo para um campo. Por exemplo, se o primeiro campo (o campo minutos) tiver um valor de */5, significa “a cada 5 minutos”. Se o quinto campo (o campo dia da semana) é definido como 0/5, significa “a cada cinco domingos”.

Como especificar o que o CronJob executa

O spec.jobTemplate descreve o que o CronJob faz, incluindo as imagens de contêiner, os comandos que os contêineres executam e a política de reinicialização do CronJob. Para mais detalhes sobre o que incluir em spec.jobTemplate, consulte a documentação do Kubernetes CronJob (em inglês).

Como especificar um prazo

O campo opcional startingDeadlineSeconds indica o número máximo de segundos que o CronJob pode levar para iniciar se, por qualquer motivo, não o fizer no horário programado. Os CronJobs perdidos são considerados falhas.

Para especificar um prazo, adicione o valor de startingDeadlineSeconds ao campo spec do CronJob no arquivo de manifesto. Por exemplo, o seguinte manifesto especifica que o CronJob tem 100 segundos para começar:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  startingDeadlineSeconds: 100
  jobTemplate:
    spec:
    ...

Observação: se você especificar um valor vazio para o campo startingDeadlineSeconds, o CronJob nunca expirará. Isso pode fazer com que o mesmo CronJob seja executado várias vezes simultaneamente. É possível evitar isso especificando uma política de simultaneidade.

Como especificar uma política de simultaneidade

O campo opcional spec.concurrencyPolicy especifica como tratar execuções simultâneas de um job criado pelo controlador do CronJob. Se você não definir um valor, vários jobs simultâneos serão permitidos por padrão.

concurrencyPolicy aceita os seguintes valores:

Valor	Significado
Allow	Jobs simultâneos são permitidos. Esse é o padrão.
Forbid	Jobs simultâneos são proibidos e não é possível iniciar jobs novos até que os anteriores tenham concluído ou expirado.
Replace	Jobs simultâneos são proibidos e jobs antigos são cancelados em favor de jobs novos.

Como suspender execuções subsequentes

O campo opcional spec.suspend, quando definido como true, impede que novos jobs sejam executados, mas permite que as execuções atuais sejam concluídas.

Como especificar limites de histórico

Um CronJob cria um pod sempre que é executado. A visualização do status de encerramento das execuções recentes de um CronJob, bem como os registros de um pod individual, são abordados em Como visualizar o histórico de CronJobs.

Configure o número de execuções bem-sucedidas e com falha de CronJobs que são salvas especificando valores para spec.successfulJobsHistoryLimit e spec.failedJobsHistoryLimit. Por padrão, successfulJobsHistoryLimit é definido como 3 e failedJobsHistoryLimit é definido como 1.

Por exemplo, o manifesto a seguir instrui o GKE a salvar no máximo cinco execuções bem-sucedidas do CronJob e no máximo 10 execuções com falha do CronJob:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  startingDeadlineSeconds: 100
  successfulJobsHistoryLimit: 5
  failedJobsHistoryLimit: 10
  jobTemplate:
    spec:
    ...

É possível desativar a retenção do histórico de execuções bem-sucedidas ou com falha do CronJob definindo o respectivo valor como 0. Desativar a retenção do histórico pode tornar as falhas de depuração mais difíceis. Por exemplo, o manifesto a seguir instrui o GKE a salvar apenas execuções com falha do CronJob:

kind: CronJob
metadata:
  name: hello
spec:
  schedule: "*/1 * * * *"
  startingDeadlineSeconds: 100
  successfulJobsHistoryLimit: 0
  failedJobsHistoryLimit: 10
  jobTemplate:
    spec:
    ...

Como inspecionar um CronJob

Para verificar a configuração de um CronJob, use kubectl describe:

kubectl describe cronjob CRONJOB_NAME

Substitua CRONJOB_NAME pelo nome do CronJob a ser inspecionado.

Como visualizar o histórico de CronJobs

Um CronJob é executado dentro de um pod. Por padrão, o Kubernetes preserva os registros de pods encerrados que representam as três últimas execuções bem-sucedidas de um CronJob e o último trabalho com falha. É possível alterar ou desativar esses padrões alterando os limites do histórico do CronJob.

Para visualizar o histórico de um CronJob, primeiro liste todos os pods. Os CronJobs concluídos são mostrados com status Completed, e os jobs que falharam têm um status RunContainerError, CrashLoopBackOff ou outro que indique uma falha.

Observação: talvez você veja mais entradas do que o esperado. O histórico do CronJob está sujeito à coleta de lixo periódica. Por exemplo, na saída abaixo, quatro instâncias do CronJob hello são mostradas.

NAME                                READY   STATUS              RESTARTS   AGE
hello-1556555640-9bc5r              0/1     Completed           0          3m6s
hello-1556555700-cm6wk              0/1     Completed           0          2m6s
hello-1556555760-62wf5              0/1     Completed           0          66s
hello-1556555820-rl8kl              0/1     Completed           0          5s
hello-failed-1556555820-wrvt2       0/1     RunContainerError   1          5s

Para fazer com que um job falhe de propósito, modifique o manifesto de exemplo em Como criar um CronJob. Altere o campo args em spec.containers para um comando inválido ou um caminho que não existe e altere o valor metadata.name para um que indique que você está testando falhas.

Para visualizar os registros de um CronJob específico, execute o seguinte comando:

kubectl logs POD_NAME

Substitua POD_NAME pelo nome do pod que você quer inspecionar.

A resposta será semelhante a:

container_linux.go:247: starting container process caused
"exec: \"/in/sh\": stat /in/sh: no such file or directory"

Como excluir um CronJob

Para excluir um CronJob, execute o comando a seguir:

kubectl delete cronjob CRONJOB_NAME

Ao excluir um CronJob, o coletor de lixo do Kubernetes excluir os jobs associados e impede o início de novos jobs.

A seguir

• Leia a documentação do Kubernetes para CronJobs.
• Saiba como executar um job único.