Recarregando Configurações do Jenkins com Segurança Sem Necessitar de Reinicialização
Recarregue a configuração do Jenkins do disco com segurança, saiba quando uma reinicialização segura é melhor e evite atalhos arriscados do Script Console.
Recarregando Configurações do Jenkins com Segurança Sem Necessitar de Reinicialização
Recarregar a configuração do Jenkins parece inofensivo até que você faça isso em um controlador ocupado e descubra que nem toda alteração pode ser aplicada de forma limpa enquanto os jobs estão em execução. O comando correto depende do que mudou.
Se você editou arquivos XML em JENKINS_HOME, restaurou jobs de um backup ou alterou arquivos fora da interface web, o Jenkins pode recarregar a configuração do disco. Se você instalou ou atualizou plugins, alterou opções do Java ou precisa atualizar o estado de tempo de execução, uma reinicialização segura geralmente é a ferramenta mais adequada. Essas são operações diferentes.
O atalho enganoso a evitar é System.exit(10) no Script Console. Isso pode fazer com que um supervisor de processo, contêiner servlet ou wrapper de serviço reinicie o Jenkins, dependendo de como o Jenkins é iniciado, mas não é um comando limpo de "recarregar configuração". Pode interromper o trabalho e esconde a intenção. Use a CLI do Jenkins ou as ações de gerenciamento integradas.
Recarregar configuração do disco com a CLI
O comando mais claro é reload-configuration:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration
Isso instrui o Jenkins a descartar a configuração carregada e lê-la novamente do disco. É útil após alterações controladas de arquivos, como restaurar a configuração de um job ou aplicar configuração gerada por automação.
Antes de executá-lo, verifique três coisas:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null
A conta precisa de permissão administrativa para recarregar a configuração. Não use um token de administrador pessoal de um laptop de alguém para automação de rotina. Use uma conta de administrador gerenciada, mantenha o token em um cofre de segredos e gire-o de acordo com sua política.
Se preferir a interface web, use Gerenciar Jenkins e a opção de recarregar quando disponível em sua versão do Jenkins e componentes instalados. A CLI é mais fácil de auditar porque o comando pode estar em um runbook.
Quando a reinicialização segura é a melhor escolha
Uma reinicialização segura aguarda a conclusão das builds em execução e então reinicia o Jenkins. É mais lenta que um recarregamento, mas é mais honesta quando o estado de tempo de execução precisa ser reconstruído.
Use a reinicialização segura após instalação ou atualização de plugins, alterações nas opções do Java, atualizações do núcleo do Jenkins ou comportamento que só aparece após uma reinicialização completa do controlador.
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" safe-restart
Você também pode usar o endpoint /safeRestart se seu ambiente permitir, mas a forma da CLI é mais fácil de padronizar.
Não prometa zero tempo de inatividade. Um recarregamento pode afetar brevemente a interface do usuário, e uma reinicialização segura intencionalmente reinicia o controlador após as builds serem drenadas. Se agentes desconectarem ou plugins se comportarem mal, os usuários podem notar. Agende a operação quando o raio de impacto for aceitável.
Um runbook de recarregamento mais seguro
Primeiro, anuncie a janela de manutenção, mesmo que seja curta. Depois, verifique o que está em execução:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs
Para uma verificação rápida da fila, use Groovy através da CLI:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
println "Na fila: ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
computer.executors.findAll { it.isBusy() }.each { executor ->
println "Executando em ${computer.displayName}: ${executor.currentExecutable}"
}
}
EOF
Faça backup da configuração que você está prestes a usar. No mínimo, tenha um backup recente de JENKINS_HOME, especialmente config.xml, diretórios de jobs, metadados de credenciais e estado de plugins. Tenha cuidado com arquivos de credenciais; proteja os backups como segredos.
Execute o recarregamento:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration
Em seguida, verifique se o controlador está respondendo:
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null
Verifique o log do sistema e um job representativo antes de considerar o trabalho concluído. Um recarregamento que retorna com sucesso ainda pode expor um XML de job ruim, plugin ausente ou problema de permissão.
Sobre scripts Groovy de recarregamento
O Script Console é poderoso porque é executado dentro do controlador Jenkins. É também por isso que merece cautela. Qualquer usuário do console de script pode ler segredos, modificar jobs, desabilitar controles de segurança ou quebrar o controlador.
Se você precisar de Groovy para inspeção, mantenha-o somente leitura e curto. Por exemplo:
println Jenkins.instance.version
println Jenkins.instance.items.size()
println Jenkins.instance.queue.items.size()
Evite chamadas de recarregamento interno não documentadas, a menos que você as tenha testado em sua versão do Jenkins e plugins. APIs internas podem mudar, e métodos de recarregamento específicos de plugins podem não recarregar o estado que você precisa.
Para configurações do tipo Configuration as Code, use o mecanismo de recarregamento documentado do plugin em vez de um recarregamento genérico do Jenkins. O JCasC tem seu próprio modelo e comportamento de validação, e um arquivo de configuração que parece correto no disco ainda pode falhar ao ser aplicado.
O que fazer se o recarregamento der errado
Se o Jenkins voltar com jobs ausentes, visualizações quebradas ou erros de plugin, não continue clicando em recarregar. Capture o log do sistema, anote a hora e compare os arquivos alterados com o backup. Causas comuns são XML malformado, uma configuração de job que referencia um plugin que não está mais instalado ou edições manuais feitas enquanto o Jenkins ainda estava escrevendo arquivos.
Se a interface do usuário estiver instável, mas o processo estiver em execução, uma reinicialização segura pode limpar o estado transitório. Se a configuração estiver realmente ruim, restaure os arquivos anteriores primeiro, depois recarregue ou reinicie.
O padrão mais seguro é simples: use reload-configuration para alterações de configuração no disco, use safe-restart para alterações de tempo de execução e plugins, e reserve o Script Console para scripts administrativos deliberados que você possa explicar linha por linha.