Controle de tempo de execução de comandos no Docker usando scripts personalizados

Executar comandos dentro de containers Docker com limite de tempo é uma necessidade comum, especialmente em ambientes de CI/CD ou testes automatizados. No entanto, confiar apenas na opção --stop-timeout do docker run muitas vezes não resolve o problema, pois ela atua apenas na fase de parada do container, não na duração total de execução do comando. A solução mais eficaz envolve criar um script de gerenciamento dentro do próprio container, que monitora e controla o ciclo de vida da tarefa desejada.

O problema concreto

Imagine que você precisa garantir que um comando, por exemplo, uma execução de script ou processo, não ultrapasse um limite de tempo definido, como 5 segundos. Você inicia o container com um comando que pode durar mais do que isso, mas quer que ele seja automaticamente encerrado se passar do limite. A opção --stop-timeout do docker serve para definir quanto tempo o Docker aguarda após enviar o sinal de parada, mas ela não força o encerramento do processo em si, apenas define o período de espera. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

Diagnóstico comum

Muitos tentam usar o --stop-timeout, achando que isso limita a duração do comando, mas na prática, ele apenas controla o tempo de espera na parada do container, não o seu ciclo de vida. Além disso, comandos longos ou que não respondem ao sinal de término podem fazer o container ficar ativo por mais tempo, gerando problemas de consumo de recursos ou falhas em pipelines.

Abordagem prática com scripts internos

A melhor estratégia é incorporar um monitor de timeout dentro do container. Para isso, é comum criar um entrypoint personalizado que inicia o comando principal, enquanto monitora seu tempo de execução. Um exemplo clássico é usar o comando timeout do Linux, que interrompe automaticamente o processo após o limite desejado. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Por exemplo, podemos criar um Dockerfile que copia um script de controle e o configura como entrypoint. Este script inicia o comando principal (como um sleep ou uma execução de tarefa complexa) e, simultaneamente, monitora o tempo. Se o limite for atingido, ele força o encerramento do processo. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

FROM ubuntu:20.04
COPY controle.sh /controle.sh
RUN chmod +x /controle.sh
ENTRYPOINT ["/controle.sh"]

E o script controle.sh:

#!/bin/bash
limite=5
comando="$1"

# Inicia o comando em background
$comando &
pid_comando=$!

# Monitora o tempo de execução
tempo=0
while kill -0 $pid_comando 2>/dev/null. do
  sleep 1
  ((tempo++))
  if [ $tempo -ge $limite ]. then
    echo "Timeout atingido, encerrando o processo..."
    kill -9 $pid_comando
    exit 1
  fi
done
exit 0

Esse método garante que, independentemente do comando, ele será interrompido após o limite de tempo, evitando processos travados ou execuções indefinidas.

Tradeoffs e cuidados

Usar scripts internos para controle de timeout traz flexibilidade, mas também aumenta a complexidade do container. É preciso garantir que o script gerencie corretamente sinais e que o comando seja iniciado de forma que possa ser monitorado. Além disso, o uso do kill -9 pode gerar efeitos colaterais, como não liberar recursos ou deixar processos zumbis, portanto, sempre avalie se há uma maneira mais suave de encerrar o comando. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar.

Outro ponto é garantir que o comando seja iniciado de forma que o script possa capturar seu PID, o que nem sempre é trivial dependendo do comando ou da shell usada. Para comandos mais complexos, usar o comando timeout do próprio Linux pode ser mais simples e robusto.

Conclusão

Limitar o tempo de execução de comandos em containers Docker não é trivial usando apenas opções nativas. A prática recomendada é incorporar um mecanismo de controle interno, que pode usar comandos como timeout ou scripts de monitoração. Assim, você garante maior controle, evita travamentos e mantém a automação mais confiável. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

Você já enfrentou dificuldades ao tentar gerenciar limites de tempo em containers? Quais estratégias funcionaram melhor na sua experiência? Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.