재시작 없이 Jenkins 설정을 안전하게 다시 로드하기

Jenkins 설정을 다시 로드하는 것은 바쁜 컨트롤러에서 작업이 실행 중인 동안 모든 변경 사항이 깔끔하게 적용될 수 없다는 사실을 알기 전까지는 무해해 보입니다. 올바른 명령은 무엇이 변경되었는지에 따라 달라집니다.

JENKINS_HOME에서 XML 파일을 편집했거나, 백업에서 작업을 복원했거나, 웹 UI 외부에서 파일을 변경한 경우 Jenkins는 디스크에서 설정을 다시 로드할 수 있습니다. 플러그인을 설치하거나 업그레이드했거나, Java 옵션을 변경했거나, 런타임 상태를 새로 고쳐야 하는 경우 일반적으로 안전한 재시작이 더 나은 도구입니다. 이들은 서로 다른 작업입니다.

피해야 할 오해의 소지가 있는 단축키는 Script Console에서 System.exit(10)을 사용하는 것입니다. 이는 Jenkins가 시작된 방식에 따라 프로세스 감독자, 서블릿 컨테이너 또는 서비스 래퍼가 Jenkins를 다시 시작하도록 할 수 있지만, 깔끔한 "설정 다시 로드" 명령이 아닙니다. 작업을 중단시킬 수 있고 의도를 숨깁니다. 대신 Jenkins CLI 또는 내장된 관리 작업을 사용하세요.

CLI로 디스크에서 설정 다시 로드

가장 명확한 명령은 reload-configuration입니다:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

이 명령은 Jenkins에게 로드된 설정을 폐기하고 디스크에서 다시 읽도록 지시합니다. 작업 구성을 복원하거나 자동화로 생성된 구성을 적용하는 등 통제된 파일 변경 후에 유용합니다.

실행하기 전에 세 가지를 확인하세요:

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

계정에는 설정 다시 로드를 위한 관리 권한이 필요합니다. 일상적인 자동화에 개인 노트북의 관리자 토큰을 사용하지 마세요. 관리형 관리자 계정을 사용하고, 토큰을 비밀 저장소에 보관하며, 정책에 따라 정기적으로 교체하세요.

웹 UI를 선호하는 경우, Jenkins 버전과 설치된 구성 요소에서 사용 가능할 때 Manage Jenkins 및 다시 로드 옵션을 사용하세요. CLI는 명령이 runbook에 저장될 수 있으므로 감사하기 더 쉽습니다.

안전한 재시작이 더 나은 선택인 경우

안전한 재시작은 실행 중인 빌드가 완료될 때까지 기다린 후 Jenkins를 다시 시작합니다. 다시 로드보다 느리지만, 런타임 상태를 다시 빌드해야 할 때 더 정직합니다.

플러그인 설치 또는 업그레이드, Java 옵션 변경, Jenkins 코어 업그레이드, 또는 전체 컨트롤러 재시작 후에만 나타나는 동작 후에는 안전한 재시작을 사용하세요.

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" safe-restart

환경이 허용하는 경우 /safeRestart 엔드포인트를 사용할 수도 있지만, CLI 형식이 표준화하기 더 쉽습니다.

제로 다운타임을 약속하지 마세요. 다시 로드는 UI에 일시적으로 영향을 줄 수 있으며, 안전한 재시작은 빌드가 소진된 후 의도적으로 컨트롤러를 다시 시작합니다. 에이전트가 연결을 끊거나 플러그인이 잘못 작동하면 사용자가 알아차릴 수 있습니다. 영향 범위가 허용 가능한 시간에 작업을 예약하세요.

더 안전한 다시 로드 Runbook

먼저, 짧더라도 유지보수 기간을 공지하세요. 그런 다음 실행 중인 작업을 확인하세요:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs

빠른 큐 확인을 위해 CLI를 통해 Groovy를 사용하세요:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
  println "Queued: ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
  computer.executors.findAll { it.isBusy() }.each { executor ->
    println "Running on ${computer.displayName}: ${executor.currentExecutable}"
  }
}
EOF

의존하려는 설정을 백업하세요. 최소한 JENKINS_HOME, 특히 config.xml, 작업 디렉토리, 자격 증명 메타데이터 및 플러그인 상태의 최근 백업이 있어야 합니다. 자격 증명 파일에 주의하세요. 백업을 비밀로 보호하세요.

다시 로드를 실행하세요:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

그런 다음 컨트롤러가 응답하는지 확인하세요:

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

작업이 완료되었다고 말하기 전에 시스템 로그와 대표적인 작업을 확인하세요. 성공적으로 반환된 다시 로드도 잘못된 작업 XML, 누락된 플러그인 또는 권한 문제를 드러낼 수 있습니다.

Groovy 다시 로드 스크립트에 관하여

Script Console은 Jenkins 컨트롤러 내에서 실행되기 때문에 강력합니다. 이것이 바로 주의가 필요한 이유이기도 합니다. 모든 스크립트 콘솔 사용자는 비밀을 읽고, 작업을 수정하고, 보안 제어를 비활성화하거나 컨트롤러를 손상시킬 수 있습니다.

검사를 위해 Groovy가 필요하다면 읽기 전용으로 유지하고 짧게 작성하세요. 예를 들어:

println Jenkins.instance.version
println Jenkins.instance.items.size()
println Jenkins.instance.queue.items.size()

Jenkins 버전과 플러그인에 대해 테스트하지 않은 경우 문서화되지 않은 내부 다시 로드 호출을 피하세요. 내부 API는 변경될 수 있으며, 플러그인별 다시 로드 메서드는 사용자가 관심 있는 상태를 다시 로드하지 않을 수 있습니다.

Configuration as Code 설정의 경우 일반 Jenkins 다시 로드 대신 플러그인의 문서화된 다시 로드 메커니즘을 사용하세요. JCasC에는 자체 모델과 유효성 검사 동작이 있으며, 디스크에 올바르게 보이는 구성 파일도 적용 시 실패할 수 있습니다.

다시 로드가 잘못되었을 때 대처 방법

Jenkins가 누락된 작업, 손상된 보기 또는 플러그인 오류로 돌아오면 계속해서 다시 로드를 클릭하지 마세요. 시스템 로그를 캡처하고, 시간을 기록하며, 변경된 파일을 백업과 비교하세요. 일반적인 원인은 잘못된 형식의 XML, 더 이상 설치되지 않은 플러그인을 참조하는 작업 구성, 또는 Jenkins가 여전히 파일을 쓰는 중에 수동 편집을 한 경우입니다.

UI가 불안정하지만 프로세스가 실행 중인 경우 안전한 재시작이 일시적인 상태를 지울 수 있습니다. 구성이 실제로 잘못된 경우 먼저 이전 파일을 복원한 다음 다시 로드하거나 재시작하세요.

가장 안전한 패턴은 간단합니다: 디스크 구성 변경에는 reload-configuration을 사용하고, 런타임 및 플러그인 변경에는 safe-restart를 사용하며, Script Console은 한 줄씩 설명할 수 있는 신중한 관리 스크립트를 위해 예약하세요.