Jenkins 플러그인 충돌 해결: 모범 사례와 솔루션

Jenkins 플러그인은 유용하지만, 안정적인 컨트롤러를 예측 불가능하게 만드는 가장 쉬운 방법 중 하나이기도 합니다. 플러그인 업데이트는 종속성, 파이프라인 단계, 보안 동작, UI 양식 및 최소 Jenkins 코어 요구 사항을 변경할 수 있습니다. 플러그인 변경 직후 빌드가 실패하기 시작하면 이를 증거, 롤백 옵션 및 신중한 격리가 필요한 프로덕션 변경으로 취급하십시오.

실용적인 질문은 간단합니다. 하나의 플러그인이 실패했는지, 종속 플러그인이 실패했는지, 아니면 Jenkins 코어와 플러그인 세트가 호환성에서 벗어났는지입니다.

Jenkins 플러그인 충돌 이해

플러그인 충돌은 일반적으로 공유 라이브러리의 불일치, 호환되지 않는 버전 또는 심층적인 아키텍처 차이에서 비롯됩니다. Jenkins의 플러그인 로딩 메커니즘은 강력하지만, 여러 플러그인이 동일한 기본 라이브러리의 다른 버전을 사용하려고 하거나 플러그인의 내부 구조가 다른 플러그인과 충돌할 때 때때로 어려움을 겪을 수 있습니다. 이는 종종 "종속성 지옥"이라고 불리는 상황으로 이어집니다.

충돌의 일반적인 원인:

호환되지 않는 종속성: 가장 빈번한 원인입니다. 플러그인 A는 라이브러리 X 버전 1.0이 필요하고, 플러그인 B는 라이브러리 X 버전 2.0이 필요합니다. 둘 다 존재하면 하나의 플러그인이 실패하거나 예기치 않게 작동할 수 있습니다.
Jenkins 코어 버전 불일치: 플러그인이 현재 Jenkins 코어 버전과 호환되지 않거나 그 반대일 수 있습니다. 최신 Jenkins 버전은 종종 이전 플러그인을 손상시키는 변경 사항을 도입하고, 이전 Jenkins 버전은 최신 플러그인이 의존하는 기능이 부족할 수 있습니다.
전이 종속성: 간접 종속성에서 충돌이 발생할 수 있습니다. 플러그인 A는 플러그인 C에 의존하고, 플러그인 B도 플러그인 C에 의존하지만, 서로 다른 버전이 필요하거나 플러그인 C에 대한 충돌하는 요구 사항이 있습니다.
클래스로더 문제: Jenkins는 계층적 클래스로더 시스템을 사용합니다. 때때로 동일한 라이브러리의 다른 버전에 있는 클래스가 다른 클래스로더에 의해 로드되어 상호 작용하려고 할 때 java.lang.LinkageError 또는 java.lang.IncompatibleClassChangeError가 발생할 수 있습니다.

플러그인 충돌 식별

충돌을 해결하는 첫 번째 단계는 충돌을 식별하는 것입니다. 충돌은 명백한 오류 메시지부터 미묘하고 진단하기 어려운 문제까지 다양한 방식으로 나타납니다.

단서를 찾을 곳:

Jenkins 시스템 로그: 이것이 주요 정보 소스입니다. JENKINS_HOME/logs/jenkins.log(또는 Tomcat에서 실행 중인 경우 catalina.out)를 확인하십시오. 다음을 포함하는 스택 추적을 찾으십시오:
- java.lang.NoClassDefFoundError: 예상된 클래스를 찾을 수 없습니다. 종종 누락되거나 호환되지 않는 종속성을 나타냅니다.
- java.lang.NoSuchMethodError: 예상된 메서드를 찾을 수 없습니다. 일반적으로 라이브러리나 클래스가 로드되었지만 플러그인이 호출하려는 메서드가 없는 이전 버전일 때 발생합니다.
- java.lang.AbstractMethodError: NoSuchMethodError와 유사하며, 종종 인터페이스 변경을 나타냅니다.
- java.lang.LinkageError(예: java.lang.IllegalAccessError, java.lang.IncompatibleClassChangeError): 클래스가 로드되었지만 버전 간에 정의가 호환되지 않게 변경되었거나 액세스 규칙이 위반된 경우 발생합니다.
- 플러그인 시작 실패 또는 예기치 않은 종료를 나타내는 메시지.
1. Jenkins UI 알림: Jenkins 관리 -> 플러그인 관리 섹션에는 오래되었거나 호환되지 않는 플러그인 또는 로드에 실패한 플러그인에 대한 경고가 자주 표시됩니다.
2. 빌드 실패: 플러그인 설치 또는 업데이트 직후 빌드가 실패하기 시작하고, 특히 빌드 콘솔 출력에 ClassNotFoundException 또는 유사한 오류가 있는 경우 플러그인 충돌이 강력한 용의자입니다.
3. 예기치 않은 동작: 기능이 작동을 멈추고, UI 요소가 사라지거나 구성 옵션을 사용할 수 없게 됩니다. 이는 더 깊은 충돌의 증상일 수 있습니다.

해결 전략

충돌이 의심되면 이를 해결하기 위해 체계적인 접근 방식이 필요합니다.

1. 기본 사항: 업데이트, 다운그레이드, 비활성화

모든 플러그인 업데이트: 종종 모든 플러그인을 최신 버전으로 업데이트하는 것만으로도 충돌을 해결할 수 있습니다. 최신 버전에는 종종 종속성 수정 및 호환성 개선 사항이 포함되어 있기 때문입니다. Jenkins 관리 -> 플러그인 관리 -> 업데이트 탭으로 이동하여 모두 선택하고 지금 다운로드하고 재시작 후 설치를 클릭하십시오.
- 팁: 주요 플러그인 업데이트 또는 변경 전에 항상 JENKINS_HOME 디렉토리를 백업하십시오.
플러그인 다운그레이드: 특정 플러그인을 업데이트한 직후 충돌이 나타난 경우 이전 작업 버전으로 다운그레이드해 보십시오. 이를 위해서는 수동 프로세스가 필요합니다:
1. Jenkins 업데이트 센터로 이동: https://updates.jenkins-ci.org/download/plugins/<plugin-name>/ (<plugin-name>을 실제 플러그인 ID(예: git)로 바꾸십시오).
2. 원하는 이전 버전의 .jpi 파일을 다운로드하십시오.
3. .jpi 파일을 JENKINS_HOME/plugins 디렉토리에 복사하여 기존 파일을 교체하십시오.
4. 해당 플러그인에 대해 .jpi.disabled 파일이 있으면 제거하십시오(이렇게 하면 Jenkins가 최신 버전을 다시 다운로드하는 것을 방지할 수 있습니다).
5. Jenkins를 다시 시작하십시오.
문제 플러그인 비활성화/제거: 특정 플러그인이 원인으로 식별되고 중요하지 않은 경우 일시적으로 비활성화해 보십시오. Jenkins 관리 -> 플러그인 관리 -> 설치됨 탭으로 이동하여 플러그인을 선택 해제하고 Jenkins를 다시 시작하십시오. 안정성이 돌아오면 충돌을 찾은 것입니다. 플러그인이 필요하지 않은 경우 제거를 고려하십시오.

2. 고급 문제 해결 기술

충돌 격리: 새로 설치하거나 업데이트한 플러그인이 의심되는 경우 플러그인을 하나씩(또는 소그룹으로) 비활성화하고 문제가 사라질 때까지 Jenkins를 다시 시작해 보십시오. 이렇게 하면 정확한 원인을 파악하는 데 도움이 됩니다.
Jenkins 안전 재시작 사용: 플러그인 변경 직후 Jenkins가 시작되지 않거나 불안정해지면 "안전 재시작"을 시도할 수 있습니다. 이렇게 하면 모든 플러그인이 비활성화된 상태로 Jenkins가 시작되어 플러그인 관리 페이지에 액세스하고 문제를 해결할 수 있습니다.

안전 재시작을 수행하려면:
```
# Jenkins가 서비스로 실행 중인 경우(예: systemd)
sudo systemctl stop jenkins
java -Dhudson.model.UpdateCenter.safeMode=true -jar jenkins.war --httpPort=8080 # 또는 원하는 포트
# 그런 다음 UI를 통해 문제를 해결한 후 정상적으로 다시 시작
sudo systemctl start jenkins
```
또는 Jenkins를 시작하기 전에 JENKINS_HOME/plugins에서 .jpi 파일의 이름을 .jpi.disabled로 바꾸어 플러그인을 수동으로 비활성화할 수 있습니다.
수동 종속성 검토: 특히 NoClassDefFoundError 또는 NoSuchMethodError와 관련된 지속적인 문제의 경우 플러그인 종속성을 수동으로 검사해야 할 수 있습니다. 대부분의 플러그인에는 .jpi(ZIP 파일) 내에 META-INF/MANIFEST.MF 파일이 있어 직접 종속성을 나열합니다. .jpi의 압축을 풀고 이 파일을 검사할 수 있습니다. 이러한 종속성을 충돌할 수 있는 다른 플러그인의 종속성과 비교하십시오.
Jenkins 코어 호환성 검토: Jenkins 웹사이트(plugins.jenkins.io)에서 플러그인의 호환성 매트릭스를 항상 확인하십시오. 각 플러그인은 일반적으로 필요한 최소 Jenkins 코어 버전을 나열합니다. Jenkins 코어가 설치된 모든 플러그인에 대해 충분히 최신 상태인지 확인하십시오.

3. 예방을 위한 모범 사례

충돌을 해결하는 것보다 예방하는 것이 항상 좋습니다.

정기적이고 점진적인 업데이트: 업데이트 사이에 너무 오래 기다리지 마십시오. 플러그인 업데이트를 정기적으로 적용하되 소규모 배치로 적용하십시오. 이렇게 하면 어떤 업데이트가 문제를 일으켰는지 식별하기가 더 쉬워집니다.
스테이징/테스트 환경: 프로덕션 Jenkins 인스턴스에 주요 플러그인 업데이트를 직접 적용하지 마십시오. 항상 프로덕션 설정을 미러링하는 전용 스테이징 또는 개발 환경에서 변경 사항을 테스트하십시오.
정기적으로 JENKINS_HOME 백업: 중요한 변경(플러그인 설치, 업데이트, Jenkins 코어 업그레이드) 전에 JENKINS_HOME 디렉토리를 백업하십시오. 이렇게 하면 문제가 발생할 경우 빠르게 복구할 수 있습니다.
Jenkins 로그 적극적으로 모니터링: Jenkins 인스턴스에 대한 로그 모니터링 및 알림을 구현하십시오. 이렇게 하면 플러그인 관련 새 오류를 신속하게 파악하는 데 도움이 될 수 있습니다.
플러그인 릴리스 노트 읽기: 플러그인을 업데이트하기 전에 알려진 호환성 문제, 주요 변경 사항 또는 새로운 종속성 요구 사항에 대한 릴리스 노트를 훑어보십시오.
최소한의 플러그인 설치: 실제로 필요한 플러그인만 설치하십시오. 추가 플러그인은 잠재적 충돌의 표면적을 증가시키고 유지 관리 오버헤드를 증가시킵니다.
플러그인 상호 종속성 이해: 일부 플러그인은 함께 작동하도록 설계되었습니다(예: Pipeline 및 다양한 SCM/빌드 도구). 이러한 관계를 인식하십시오. 예를 들어, Jenkins Pipeline을 사용하는 경우 Workflow 플러그인이 호환되는지 확인하십시오.
JENKINS_HOME/.jenkins-plugins.yaml 사용(고급): 고도로 제어된 환경의 경우 플러그인 목록을 선언적으로 관리할 수 있습니다. 이 파일은 정확한 플러그인 버전을 지정하여 일관성을 보장합니다. 모든 충돌을 방지하지는 않지만 항상 알려진 플러그인 버전 세트를 배포하고 있음을 보장합니다.
```
plugins:
  - git:4.11.5
  - pipeline-stage-view:2.27
  - workflow-aggregator:2.6
```
참고: 이 파일은 일반적으로 JCasC와 같은 도구를 통해 Jenkins 인스턴스를 설정하거나 재현 가능한 환경을 위해 플러그인을 관리할 때 사용됩니다.

단계별 문제 해결 가이드

의심되는 플러그인 충돌이 발생하면 다음 단계를 따르십시오:

JENKINS_HOME 백업: 중요한 첫 번째 단계입니다.
최근 변경 사항 확인: 마지막으로 설치하거나 업데이트한 것은 무엇입니까(플러그인, Jenkins 코어, OS 패치)? 이것이 종종 원인입니다.
Jenkins 로그 검사: ERROR, WARNING, SEVERE 메시지, 특히 NoClassDefFoundError, NoSuchMethodError, LinkageError에 대한 스택 추적을 찾으십시오. 언급된 정확한 플러그인 이름을 기록하십시오.
안전 재시작 시도: Jenkins가 불안정하거나 시작되지 않는 경우 java -Dhudson.model.UpdateCenter.safeMode=true -jar jenkins.war를 사용하여 UI에 액세스하십시오.
의심 플러그인 비활성화: Jenkins 관리 -> 플러그인 관리 -> 설치됨에서 로그에서 식별되거나 가장 최근에 변경된 플러그인을 비활성화하십시오. Jenkins를 다시 시작하십시오.
- 문제가 해결되면 충돌하는 플러그인을 찾은 것입니다. 대안, 이전 버전을 조사하거나 플러그인 유지 관리자에게 문제를 보고하십시오.
모든 플러그인 업데이트(안전한 경우): 5단계가 도움이 되지 않고 Jenkins가 충분히 안정적이면 모든 플러그인을 업데이트해 보십시오. Jenkins를 다시 시작하십시오.
문제 플러그인 다운그레이드: 업데이트로 인해 문제가 발생한 경우 수동 .jpi 교체 방법을 사용하여 특정 플러그인을 다운그레이드하십시오.
플러그인 문서 및 커뮤니티 참조: plugins.jenkins.io의 공식 플러그인 페이지에서 알려진 문제, 호환성 정보 및 커뮤니티 포럼을 확인하십시오.
체계적인 롤백: 다른 모든 방법이 실패하고 문제가 시작되기 전의 JENKINS_HOME 백업이 있는 경우 이를 복원하십시오. 그런 다음 각 변경 후 테스트하면서 점진적으로 변경 사항을 다시 도입하십시오.

다음에 할 일

플러그인 세트를 작게 유지하고, 정확한 버전을 기록하고, 프로덕션에서 멀리 떨어진 곳에서 업데이트를 테스트하고, 마지막 실패 화면에서 추측하는 대신 첫 번째 의미 있는 스택 추적을 읽으면 Jenkins 플러그인 충돌을 더 쉽게 처리할 수 있습니다.

플러그인 변경을 프로덕션 변경처럼 취급

플러그인 업데이트는 Jenkins UI에 버튼이 있기 때문에 작게 느껴집니다. 작지 않습니다. 플러그인 업데이트는 파이프라인 단계, 전이 종속성, 자격 증명 처리, UI 양식, 직렬화 동작 또는 최소 Jenkins 코어 요구 사항을 변경할 수 있습니다. 바쁜 Jenkins 인스턴스에서는 이것이 프로덕션 변경 관리입니다.

플러그인을 건드리기 전에 현재 상태를 캡처하십시오. 최소한 Jenkins 버전, 버전이 포함된 플러그인 목록, JENKINS_HOME의 백업 또는 스냅샷을 저장하십시오. Jenkins가 컨테이너에서 실행 중인 경우 이미지 태그와 시작 인수도 저장하십시오. 롤백이 필요할 때 막연한 기억만으로는 충분하지 않습니다.

스크립트 콘솔 또는 CLI에서 설치된 플러그인 목록을 내보낼 수 있지만 환경에서 이미 표준인 방법을 사용하십시오. 중요한 것은 목록에 정확한 버전이 포함되어 있다는 것입니다. "최신 git 플러그인"은 롤백 계획이 아닙니다.

스택 추적으로 명명된 플러그인 찾기

Java 스택 추적에는 종종 많은 플러그인 이름이 포함됩니다. 첫 번째 이름이 원인이라고 가정하지 마십시오. 첫 번째 애플리케이션 수준 예외와 그 주변의 클래스를 찾으십시오. NoSuchMethodError는 라이브러리 플러그인의 클래스를 언급할 수 있는 반면, 누락된 메서드를 호출한 플러그인은 몇 줄 위에 나타납니다.

예를 들어, 업데이트 후 파이프라인 단계가 실패하고 스택 추적에 workflow-step-api와 클라우드 공급자 플러그인이 모두 포함된 경우 클라우드 공급자 플러그인이 설치된 워크플로 플러그인 세트와 더 이상 일치하지 않는 API 버전을 사용하고 있을 수 있습니다. 하나의 플러그인만 업데이트하면 파이프라인 제품군이 동기화되지 않은 상태로 남을 수 있습니다.

Jenkins 플러그인 페이지는 일반적으로 종속성과 필요한 코어 버전을 나열합니다. 추측하는 대신 해당 페이지를 사용하여 호환성을 확인하십시오. 플러그인에 실행 중인 것보다 최신 Jenkins 코어가 필요한 경우 플러그인만 업그레이드하는 것은 유효한 수정이 아닙니다.

손상된 컨트롤러에서 맹목적으로 모든 것을 업데이트하지 마십시오

모든 플러그인을 업데이트하면 종속성 불일치를 해결할 수 있지만 작은 사고를 더 크게 만들 수도 있습니다. 하나의 플러그인을 변경한 직후 Jenkins가 중단된 경우 해당 변경부터 시작하십시오. 가능하면 롤백하거나 비활성화하십시오. 컨트롤러가 안정화되면 유지 관리 기간에 더 광범위한 업데이트를 계획하십시오.

인스턴스가 많이 뒤쳐져 있고, 많은 플러그인이 종속성 경고를 표시하며, 테스트된 백업이 있는 경우 모든 것을 업데이트하는 것이 더 합리적입니다. 그렇더라도 먼저 복제본 또는 스테이징 컨트롤러에서 업데이트하십시오. 특히 자격 증명, SCM 체크아웃, Docker, Kubernetes 에이전트, 공유 라이브러리 및 배포 플러그인을 사용하는 작업을 포함하여 대표적인 작업을 실행하십시오.

가장 위험이 높은 플러그인은 일반적으로 거의 모든 빌드에 참여하는 플러그인입니다: Pipeline, Git, Credentials, SCM API, Script Security, Docker, Kubernetes, Matrix Authorization 및 구성-코드 플러그인. 이를 공유 플랫폼 구성 요소로 취급하십시오.

안전 모드 및 수동 비활성화

Jenkins가 시작되지 않으면 안전 모드를 통해 플러그인이 비활성화된 상태로 UI에 다시 액세스할 수 있습니다. 패키징에서 사용할 수 없는 경우에도 .disabled 마커 파일을 만들거나 Jenkins 버전 및 시작 동작에 따라 JENKINS_HOME/plugins에서 플러그인 파일 이름을 바꾸어 수동 비활성화가 여전히 가능합니다.

한 번에 하나의 변경을 수행하고 메모를 유지하십시오. 한 번에 10개의 플러그인을 비활성화하고 Jenkins가 시작되면 생각보다 아는 것이 적습니다. 실패와 가장 밀접하게 관련된 플러그인부터 시작하십시오. Jenkins가 종속성 플러그인으로 인해 로드할 수 없는 경우 이를 비활성화하면 이에 의존하는 모든 플러그인도 비활성화될 수 있음을 기억하십시오.

수동 변경 후 UI와 로그를 모두 검사하십시오. Jenkins가 시작될 수 있지만 종속 플러그인이 실패한 상태로 남을 수 있습니다. 녹색 로그인 페이지가 플러그인 그래프가 정상임을 의미하지는 않습니다.

공유 라이브러리는 플러그인 충돌처럼 보일 수 있음

플러그인 업데이트 후 모든 오류가 플러그인 버그인 것은 아닙니다. 공유 라이브러리는 종종 플러그인 단계를 래핑합니다. 플러그인이 단계 매개변수, 반환 유형 또는 유효성 검사 규칙을 변경하면 오류가 공유 라이브러리 코드를 가리킬 수 있습니다. 여전히 호환성 문제이지만 수정 사항은 플러그인 버전 대신 라이브러리에 있을 수 있습니다.

플러그인을 직접 사용하는 간단한 작업이 여전히 작동하는지 확인하십시오. 직접 사용이 작동하고 라이브러리 기반 작업만 실패하면 라이브러리를 검사하십시오. 둘 다 실패하면 플러그인, 종속성 또는 Jenkins 코어에 집중하십시오.

플러그인 세트를 단순하게 유지

내가 본 가장 안정적인 Jenkins 컨트롤러는 사람들이 예상하는 것보다 더 적은 플러그인을 가지고 있습니다. 모든 작은 편의를 위해 플러그인을 설치하지 않습니다. 명확한 소유권, 최근 릴리스 및 광범위한 사용이 있는 유지 관리되는 플러그인을 선호합니다. 어떤 작업도 이에 의존하지 않는 것을 확인한 후 사용하지 않는 플러그인을 제거합니다.

1년에 몇 번 플러그인을 감사하십시오. 비활성화된 플러그인, 중단된 플러그인, 하나의 오래된 작업을 위해 설치된 플러그인 및 동일한 문제를 해결하는 중복 플러그인을 찾으십시오. 설치된 모든 플러그인은 로드할 코드, 해결할 종속성, 추적할 보안 권고 및 테스트할 업그레이드 경로를 추가합니다.

Jenkins Configuration as Code 또는 이미지 기반 Jenkins 배포를 사용하는 경우 플러그인 버전을 의도적으로 고정하십시오. 모든 빌드에서 최신 버전으로 플로팅하면 롤백이 어려워지고 아무도 유지 관리를 계획하지 않을 때 변경 사항이 도입될 수 있습니다.