Jenkins CLI를 사용하여 실패한 빌드 신속하게 문제 해결하기
Jenkins는 수많은 조직의 지속적 통합 및 지속적 배포(CI/CD) 파이프라인의 중추입니다. 빌드, 테스트 및 배포 프로세스를 자동화하지만, 빌드 실패는 소프트웨어 개발의 불가피한 부분입니다. 빌드가 실패하면 다운타임을 최소화하고 개발을 계속 진행하기 위해 신속한 진단 및 해결이 중요합니다.
Jenkins 웹 UI는 방대한 정보를 제공하지만, 때로는 Jenkins 명령줄 인터페이스(CLI)를 통해 직접 문제를 해결하는 것이 가장 빠른 방법입니다. CLI는 특히 반복적인 작업이나 수많은 빌드 로그를 처리할 때 UI 탐색에 대한 강력하고 스크립트 가능한, 종종 더 빠른 대안을 제공합니다. 이 가이드에서는 Jenkins CLI를 활용하여 빌드 실패를 신속하게 진단하고, 상세 로그를 검색하고, 환경 변수를 검사하고, 효율적으로 빌드를 다시 시작하는 방법을 안내합니다.
문제 해결에 Jenkins CLI를 사용해야 하는 이유?
Jenkins CLI는 문제 해결에 여러 가지 이점을 제공합니다:
- 속도: 브라우저 탐색 없이 로그와 정보를 신속하게 가져옵니다.
- 자동화: 문제 해결 단계를 스크립트 또는 자동화된 보고서에 통합합니다.
- 원격 액세스: Jenkins 인스턴스에 네트워크 액세스가 가능한 모든 터미널에서 진단을 수행합니다.
- 효율성:
grep,awk,sed와 같은 표준 셸 도구를 사용하여 로그 및 정보를 필터링합니다.
사전 요구 사항
Jenkins CLI로 문제 해결을 시작하기 전에 다음을 확인하십시오:
- 실행 중인 Jenkins 서버: 관리자 액세스 권한이 있는 활성 Jenkins 인스턴스.
- Jenkins CLI JAR: Jenkins 인스턴스에서
jenkins-cli.jar파일을 다운로드합니다. 일반적으로JENKINS_URL/jnlpJars/jenkins-cli.jar에서 찾을 수 있습니다. - 인증: CLI에는 인증이 필요합니다. 권장되는 방법은 Jenkins 사용자에 대한 API 토큰을 사용하는 것입니다. API 토큰은
Your_User_Name -> Configure -> Add new Token을 통해 생성합니다.
CLI 설정
먼저 jenkins-cli.jar를 다운로드합니다:
wget JENKINS_URL/jnlpJars/jenkins-cli.jar
# 또는 curl 사용
curl -O JENKINS_URL/jnlpJars/jenkins-cli.jar
명령을 단순화하기 위해 Jenkins URL, 사용자 이름 및 API 토큰에 대한 환경 변수를 설정할 수 있습니다:
export JENKINS_URL="http://your-jenkins-instance.com"
export JENKINS_USER="your_username"
export JENKINS_API_TOKEN="your_api_token"
# 편의를 위해 CLI 명령에 별칭 지정
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'
이제 jcli 뒤에 명령만 사용하면 됩니다.
실패한 빌드 식별
문제 해결의 첫 번째 단계는 어떤 작업과 빌드가 실패했는지 식별하는 것입니다. CLI에는 실패한 빌드만 나열하는 직접적인 명령은 없지만, 작업을 나열한 다음 검사하거나 더 고급 필터링을 위해 Groovy를 사용할 수 있습니다.
작업 나열
Jenkins 인스턴스의 모든 작업 목록을 보려면:
jcli list-jobs
이것은 기본 목록을 제공합니다. 마지막 빌드 상태를 포함한 특정 작업에 대한 자세한 정보를 얻으려면 get-job을 사용합니다:
jcli get-job MyPipelineJob
출력(기본적으로 XML 형식)에는 lastFailedBuild, lastSuccessfulBuild 등과 같은 정보가 포함되어 있으며, 이를 구문 분석할 수 있습니다.
팁: 고급 필터링을 위한 Groovy 사용
특히 특정 실패 빌드를 찾기 위한 고급 필터링의 경우, CLI를 통해 Groovy 스크립트를 실행할 수 있습니다. 이것은 매우 강력합니다.
jcli groovy =
'Jenkins.instance.getAllItems(hudson.model.Job.class).each { job ->
def lastBuild = job.getLastBuild()
if (lastBuild != null && lastBuild.result == hudson.model.Result.FAILURE) {
println "Failed Job: ${job.name}, Build: ${lastBuild.number}"
}
}'
상세 빌드 로그 검색
문제 해결에서 가장 일반적이고 중요한 단계는 빌드 로그(콘솔 출력)를 검토하는 것입니다. Jenkins CLI는 이를 간단하게 만듭니다.
콘솔 출력 가져오기
특정 빌드의 전체 콘솔 출력을 검색하려면 console 명령을 사용합니다:
jcli console MyPipelineJob 123
MyPipelineJob을 작업 이름으로, 123을 빌드 번호로 바꾸십시오. 이렇게 하면 전체 로그가 터미널에 덤프됩니다.
오류를 위해 로그 필터링
로그가 방대한 경우 수동으로 구문 분석하는 것은 비효율적입니다. grep을 활용하여 관련 오류 메시지, 스택 추적 또는 키워드를 신속하게 찾으십시오.
jcli console MyPipelineJob 123 | grep -iE "error|fail|exception|stacktrace"
-i: 대소문자 무시.-E: 확장 정규 표현식 사용 (OR의 경우|허용).
이 명령은 출력을 크게 좁혀 실패 원인을 더 빠르게 파악하는 데 도움이 됩니다.
실시간 빌드 모니터링
아직 실행 중이지만 멈춘 것처럼 보이거나 느리게 실패하는 빌드의 경우, tail -f와 유사하게 실시간으로 콘솔 출력을 모니터링할 수 있습니다:
jcli console MyPipelineJob LAST_BUILD_NUMBER --follow
빌드가 완료되거나 명령을 중지할 때까지 새로 나타나는 로그 항목을 지속적으로 스트리밍합니다.
빌드 환경 변수 검사
환경 변수는 종종 빌드 실행에서 중요한 역할을 하며 경로, 비밀 및 구성을 영향을 미칩니다. 잘못되었거나 누락된 환경 변수는 빌드 실패로 이어질 수 있습니다. 과거 빌드의 모든 환경 변수를 나열하는 직접적인 CLI 명령은 없지만, CLI를 통해 실행되는 Groovy 스크립트를 사용하여 검색할 수 있습니다.
먼저 파이프라인이 관련 환경 변수를 명시적으로 출력하거나 dumpEnvVars 단계(Pipeline Utility Steps 플러그인 사용 시)에 액세스할 수 있는지 확인하십시오. 그렇지 않은 경우 Groovy를 사용할 수 있습니다.
Groovy를 사용하여 환경 변수 액세스
jcli groovy =
'def job = Jenkins.instance.getItemByFullName("MyPipelineJob")
def build = job.getBuildByNumber(123)
if (build) {
build.getEnvironment().each { key, value ->
println "${key}=${value}"
}
} else {
println "Build 123 not found for MyPipelineJob"
}'
이 스크립트는 Jenkins API에 연결하고, 지정된 작업 및 빌드를 검색한 다음, 해당 빌드 실행 중에 설정된 모든 환경 변수를 반복하고 출력합니다.
- 보안 경고: 환경 변수에는 API 키, 비밀번호 등 민감한 정보가 포함될 수 있으므로 출력할 때 주의하십시오. 안전한 환경에서만 수행하고 적절한 액세스 제어를 보장하십시오.
파이프라인에서 스테이지별 실패 분석
Jenkins 파이프라인의 경우 어떤 스테이지가 실패했는지 아는 것이 중요합니다. 원시 console 출력은 스테이지를 구분하는 데 도움이 되는 [Pipeline] stage 마커를 표시하지만, CLI 자체는 UI(예: Blue Ocean)에서와 같이 스테이지 상태를 직접 쿼리하는 구조화된 방법을 제공하지 않습니다.
로그에서 스테이지 실패 찾기
console 출력을 검토할 때 오류 메시지 또는 스택 추적 전에 마지막 [Pipeline] stage 항목을 찾으십시오. 이것이 일반적으로 실패가 발생한 스테이지를 나타냅니다.
jcli console MyPipelineJob 123 | less
less 내에서 [Pipeline] stage를 검색한 다음 스크롤하여 오류를 찾을 수 있습니다.
실패한 빌드 다시 실행 또는 재시작
실패의 근본 원인을 식별하고 수정(예: 새 코드 푸시, 구성 업데이트)을 적용한 후에는 빌드를 다시 실행해야 합니다. CLI는 이를 수행하는 간단한 방법을 제공합니다.
전체 빌드 다시 실행
작업에 대한 새 빌드를 트리거하려면:
jcli build MyPipelineJob
작업이 매개변수를 허용하는 경우 -p 플래그를 사용하여 전달할 수 있습니다:
jcli build MyPipelineJob -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
--wait(-s): 빌드 완료 대기.--verbose(-v): 진행 상황 및 빌드 로그 표시.
jcli build MyPipelineJob -p BRANCH=master --wait --verbose
특정 스테이지부터 다시 시작 (고급)
Jenkins CLI에는 직접적인 restart-stage 명령이 없습니다. 파이프라인을 특정 스테이지부터 다시 시작하는 것은 주로 Jenkins UI(종종 "Pipeline Steps" 플러그인으로 활성화됨)의 기능이거나 특정 파이프라인 로직이 필요합니다.
그러나 초기 스테이지를 건너뛸 수 있도록 매개변수를 허용하도록 파이프라인을 설계하여 유사한 효과를 얻을 수 있습니다. 예:
// Jenkinsfile에서
parameters {
booleanParam(name: 'SKIP_SETUP_STAGE', defaultValue: false, description: 'Skip the initial setup stage')
}
pipeline {
agent any
stages {
stage('Setup') {
when {
expression { !params.SKIP_SETUP_STAGE }
}
steps {
echo 'Running setup...'
// ... setup steps ...
}
}
stage('Build') {
steps {
echo 'Building application...'
// ... build steps ...
}
}
// ... other stages ...
}
}
그런 다음 CLI를 통해 이 매개변수화된 빌드를 트리거하여 "Setup" 스테이지를 건너뛸 수 있습니다:
jcli build MyPipelineJob -p SKIP_SETUP_STAGE=true
이 접근 방식은 Jenkinsfile 디자인에 대한 사전 계획이 필요하지만 CLI를 통한 파이프라인 실행에 대한 강력한 제어를 제공합니다.
Groovy를 사용한 고급 문제 해결 (CLI 경유)
groovy 및 groovy-script 명령을 사용하면 Jenkins 컨트롤러에서 임의의 Groovy 코드를 실행할 수 있습니다. 이를 통해 Jenkins의 내부 API에 대한 탁월한 액세스를 얻어 심층적인 검사 및 조작이 가능합니다.
예: 빌드 세부 정보 가져오기
jcli groovy =
'def job = Jenkins.instance.getItemByFullName("MyPipelineJob")
def build = job.getBuildByNumber(123)
if (build) {
println "Build #${build.number} for ${job.name}"
println "Status: ${build.result}"
println "Duration: ${build.durationString}"
println "Description: ${build.description ?: "N/A"}"
println "Causes:"
build.getCauses().each { cause ->
println " - ${cause.shortDescription}"
}
} else {
println "Build 123 not found for MyPipelineJob"
}'
이 스크립트는 특정 빌드에 대한 포괄적인 정보를 검색하며, 콘솔 로그가 덜 명확한 경우 빌드가 실패한 이유를 이해하는 데 귀중할 수 있습니다.
로컬 Groovy 스크립트 실행
더 복잡한 Groovy 스크립트의 경우 .groovy 파일에 작성하고 groovy-script를 통해 실행합니다:
# my_troubleshooting_script.groovy
def jobName = System.getenv('JOB_NAME') ?: 'MyPipelineJob'
def buildNumber = System.getenv('BUILD_NUMBER') ? Integer.parseInt(System.getenv('BUILD_NUMBER')) : 123
def job = Jenkins.instance.getItemByFullName(jobName)
def build = job?.getBuildByNumber(buildNumber)
if (build) {
println "Build details for ${job.name} #${build.number}"
println "Status: ${build.result}"
build.getAction(hudson.model.ParametersAction.class)?.getParameters()?.each { p ->
println "Param: ${p.name} = ${p.value}"
}
} else {
println "Job ${jobName} or Build ${buildNumber} not found."
}
그런 다음 실행합니다:
JOB_NAME=MyPipelineJob BUILD_NUMBER=123 jcli groovy-script my_troubleshooting_script.groovy
이를 통해 문제 해결 도구를 버전 관리할 수 있습니다.
효율적인 문제 해결을 위한 팁
- 구체적으로 하십시오:
grep을 사용할 때 패턴을 개선하십시오. 특정 오류 코드, 고유한 메시지 또는 타임스탬프를 찾으십시오. - 맥락이 중요합니다: 항상 주변 로그 줄을 고려하십시오. 오류에는 더 많은 맥락을 제공하는 사전 또는 후속 메시지가 자주 있습니다.
- 파이프라인 구조: 명확한 스테이지 이름과 중요한 단계 내에 상세한 로깅으로 Jenkinsfile을 설계하십시오. 이렇게 하면 문제를 더 쉽게 식별할 수 있습니다.
tee사용: CLI 명령을 실행할 때 출력을tee로 파이프하여 표시하고 나중에 분석할 수 있도록 파일에 저장할 수 있습니다.
bash jcli console MyPipelineJob 123 | tee build_123_log.txt | grep -i error- Jenkins 시스템 로그: Jenkins 자체에도 시스템 로그(
JENKINS_HOME/logs)가 있다는 것을 기억하십시오. 때로는 빌드 실패가 파이프라인 코드 때문이 아니라 Jenkins 시스템 문제 때문일 수 있습니다. UI(Manage Jenkins -> System Log)를 통해 또는 Jenkins 서버 파일 시스템에서 직접 액세스할 수 있습니다.
결론
Jenkins CLI는 관리자와 개발자 모두에게 필수적인 도구로, Jenkins 인스턴스와 상호 작용할 수 있는 빠르고 강력한 방법을 제공합니다. 로그 검색, 환경 변수 검사(Groovy 경유), 빌드 트리거 효율화와 같은 명령을 숙달하면 빌드 실패 진단 및 해결에 소요되는 시간을 크게 줄일 수 있습니다. 이러한 CLI 기술을 일상 워크플로에 통합하여 고성능의 안정적인 CI/CD 파이프라인을 유지하십시오.
광범위한 Jenkins CLI 명령 목록(jcli help)과 Groovy 스크립팅의 강력한 기능을 계속 탐색하여 더 많은 고급 자동화 및 문제 해결 기능을 잠금 해제하십시오.