Controle de timeout em comandos executados dentro de containers Docker

Executar comandos em containers Docker com limite de tempo é uma necessidade comum, especialmente em ambientes de CI/CD ou automação de testes. No entanto, há uma confusão frequente sobre o funcionamento do parâmetro '--stop-timeout' e sua aplicabilidade para limitar a duração de comandos específicos.

Problema Concreto

Muitos desenvolvedores tentam usar o '--stop-timeout' para encerrar comandos longos ou processos que ultrapassam um tempo limite, assumindo que o próprio comando será interrompido após o período definido. Na prática, '--stop-timeout' é um parâmetro que define o tempo de espera do Docker ao parar um container, não ao limitar a execução de um comando interno. Assim, comandos como 'sleep 100' ainda podem rodar por mais tempo do que o esperado, mesmo com esse parâmetro configurado.

Diagnóstico

O entendimento errado do '--stop-timeout' leva a soluções ineficazes. Quando se deseja interromper uma execução após um determinado período, o ideal é implementar uma lógica de timeout dentro do próprio container ou usar ferramentas externas de gerenciamento de processos. Além disso, comandos tradicionais como 'sleep' ou scripts que executam tarefas demoradas não respeitam automaticamente limites de tempo do Docker.

Abordagem Prática

Para controlar o tempo de execução de comandos dentro de containers, recomenda-se criar um script de entrada (entrypoint) que gerencie o timeout. Por exemplo, um script Bash que inicia o comando principal em background, monitora seu tempo de execução e termina o processo se o limite for atingido. Essa estratégia garante maior controle e previsibilidade. 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. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar.

Aqui um exemplo prático:

Dockerfile:

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

entrypoint.sh:

#!/bin/bash
# Tempo limite em segundos
TIMEOUT=5
# Comando que será executado
COMMAND="sleep 100"

# Inicia o comando em background
$COMMAND &
CMD_PID=$!

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

Tradeoffs e Limitações

Implementar um script de gerenciamento de timeout aumenta a complexidade do container, além de precisar de manipulação cuidadosa para evitar processos zumbis ou encerramentos abruptos que possam comprometer dados ou estados internos.

Outra abordagem é usar ferramentas externas no host, como o comando 'timeout' do Linux, que pode ser chamado via 'docker exec' para limitar o tempo de um comando específico. Contudo, isso demanda gerenciamento adicional para sincronizar tempos de execução. 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. 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.

Falhas comuns

• Confundir '--stop-timeout' com timeout de execução do comando.
• Não implementar uma lógica de timeout no próprio container, confiando apenas em sinais do Docker.
• Usar comandos que não respondem a sinais de término, como processos que ignoram 'SIGTERM'.

Passos práticos para implementação

1. Avalie se o comando pode ser controlado via uma ferramenta de timeout.
2. Crie um script de entrypoint que monitore e finalize o processo após o limite.
3. Teste em ambiente de staging para garantir que o timeout funciona corretamente.
4. Automatize a construção e deploy do container com o script embutido.

Controlar o tempo de execução de comandos em containers é uma questão de entender as ferramentas à disposição e aplicar uma estratégia que garanta segurança, previsibilidade e controle. O uso de scripts internos com monitoração é uma solução mais confiável do que depender de parâmetros do Docker que não atendem ao propósito desejado. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. A decisão fica mais saudável quando o time consegue medir o impacto depois. 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. A decisão fica mais saudável quando o time consegue medir o impacto depois.