Devops/Jenkins

[Jenkins] 젠킨스(Jenkins) - 설치부터 운영까지 클라우드 네이티브 실전 예제 (+망 분리 환경)

일요일좋아하는사람 2025. 4. 19. 23:19
728x90
반응형

젠킨스

 

이 문서는 Jenkins를 실제 운영 환경에 구축하려는 분들을 위한 실전 중심 가이드입니다. 단순히 Jenkins 설치만으로 끝나는 것이 아니라, Jenkinsfile 작성법, 플러그인 설정, 그리고 폐쇄망(망 분리) 환경에서의 사용 전략까지 담아, 현실적인 고민에 맞는 대응법을 함께 다루겠습니다.

"Jenkins를 처음 설치했는데 뭘 해야 하지?" "플러그인은 무엇부터 써야 하고, 어떤 설정을 건드려야 할까?" "망 분리된 환경이라 HTTP 요청도 안 되는데 이거 어떻게 써야 해?"

이런 의문을 가진 분들이라면, 아마 이 문서에서 많은 힌트를 얻어갈 수 있을 거예요. 자, 그럼 시작해볼까요?

1️⃣ Jenkins 실전 구축 시작하기

🔧 설치 방법: 패키지 기반 vs WAR 파일 vs 컨테이너

운영 환경에서 Jenkins를 배포하는 방식은 여러 가지가 있어요. 가장 많이 쓰는 건 다음 세 가지죠.

  • 패키지 설치 (apt/yum): Ubuntu, RHEL 계열에서 전통적인 방식입니다.
  • WAR 파일 직접 실행: Java만 있으면 java -jar jenkins.war로 실행 가능
  • Docker 컨테이너: 가장 깔끔하고 재현 가능한 설치 방식

만약 여러분이 온프레미스에 Jenkins를 올린다면, Docker 또는 패키지 설치 중 하나를 추천드릴게요. 특히 폐쇄망 환경이라면 WAR 방식도 고려할 수 있습니다 (뒤에서 설명할게요).

2️⃣ Jenkins 기본 설정: 설치 후 꼭 해야 할 7가지

Jenkins를 설치하고 나면 바로 Job을 만들고 싶겠지만, 그 전에 꼭! 해줘야 할 초기 설정들이 있습니다. 예제처럼 나열하지 않고, 운영자 입장에서 왜 이걸 하는지와 함께 설명드릴게요.

  1. 관리자 계정 생성: 초기 보안 토큰 입력 후 첫 사용자 설정 필수입니다.
  2. 플러그인 설치: 기본 추천 플러그인 외에도 직접 선택 가능 (Git, Pipeline, Credentials 등은 거의 필수)
  3. 시스템 설정 변경 (Manage Jenkins > Configure System):
    • Java 경로, Git 경로 직접 지정
    • 빌드 디렉터리 경로 확인
  4. 빌드 이력 보존 정책 설정
  5. 슬레이브 노드 연결 여부
  6. 이메일 설정 (SMTP 서버 연결)
  7. 보안 설정 강화 (보안 영역, 인증 방식 등)

여기까지 하면 Jenkins는 "쓸 수 있는 상태"가 됩니다. 이제부터는 본격적으로 자동화를 만들어볼 차례죠!

3️⃣ Jenkinsfile 작성법: 진짜 자동화를 위한 코드 기반 파이프라인

Jenkins를 GUI에서 Job으로 하나하나 만드는 방식은 더 이상 권장되지 않아요. 이유는 간단해요:

  • 코드로 이력을 관리할 수 없어요.
  • 버전 관리가 안 됩니다.
  • 협업이 어렵고, 변경 추적이 불가능해요.

그래서 등장한 게 바로 Jenkinsfile입니다. 파이프라인을 코드로 관리하는 방식이죠.

🧬 Declarative Pipeline 기본 골격

pipeline {
  agent any
  stages {
    stage('Checkout') {
      steps {
        git url: 'https://github.com/example/repo.git', branch: 'main'
      }
    }
    stage('Build') {
      steps {
        sh './gradlew build'
      }
    }
    stage('Test') {
      steps {
        sh './gradlew test'
      }
    }
  }
}

이렇게 생긴 Jenkinsfile을 프로젝트 루트 디렉토리에 놓고, Jenkins Job에서 "Pipeline from SCM" 으로 연결해주면 됩니다.

💡 자주 쓰는 기능들:

  • post 블록: 성공/실패 후 작업
  • when 조건절: 환경별 분기
  • parallel: 병렬 처리
  • input: 수동 승인 (배포 승인 시 유용)

4️⃣ 실무에서 꼭 쓰는 플러그인 TOP 10

"무슨 플러그인을 깔아야 해요?" 라는 질문 많이 받습니다. 무조건 아래는 깔아두세요. 이유도 함께 정리할게요.

플러그인 설명

Git Plugin Git 저장소 연결 필수
Pipeline Plugin Jenkinsfile 파이프라인 실행 핵심
Blue Ocean 파이프라인 시각화 UI (초보자용)
Credentials Binding 비밀번호, API 키 등 안전하게 처리
Email Extension 실패 시 알림 메일 발송
Slack Notification 슬랙 알림 연동
Matrix Authorization 역할 기반 접근 제어
Workspace Cleanup 빌드 후 디렉토리 자동 삭제
Timestamper 로그에 시간 추가
Kubernetes Plugin 쿠버네티스 연동에 필수

5️⃣ 폐쇄망(망 분리) 환경에서 Jenkins 설치 및 플러그인 관리

이제 현실적으로 가장 많이 마주치는 환경, 바로 망 분리/폐쇄망 환경이에요. 인터넷 연결이 안 되기 때문에,

  • 플러그인 다운로드가 불가능하고
  • GitHub clone도 불가능하고
  • 외부 서비스 알림도 불가능하죠

그럼에도 Jenkins는 잘 사용됩니다. 아래 방법으로 운영합니다.

🔌 플러그인 수동 설치 방법

  1. 외부에서 jenkins update center URL에서 .hpi 파일 다운로드
  2. Jenkins 서버에 전송
  3. Jenkins UI > Manage Plugins > Advanced 탭에서 직접 업로드

📂 Git repository 복제 방식

  • GitHub 대신 내부 GitLab/Bitbucket 서버 운영 필요
  • 또는 미러링 서버 구성
  • Jenkins에서는 SCM URL로 내부 주소 입력

🧭 알림 시스템

  • 이메일 알림은 내부 SMTP 연동 (사내메일)
  • Slack 대체: Rocket.Chat, Mattermost 등 온프레미스 도입 가능

망 분리 환경은 자동화보다도 초기 세팅과 리소스 유통이 가장 어렵습니다. 이를 위해 보통 Jenkins 운영자는 내부에 "플러그인 백업 저장소"를 따로 관리하곤 해요.

🧪 빌드 예외 처리와 QA 파이프라인 설계 전략

"빌드 실패 시 멈춰야 하나요? 무시해야 하나요?" 이 질문에는 정답이 없지만, 일반적으로 다음과 같은 전략이 쓰입니다:

  • 단위 테스트 실패: 무조건 실패 처리하고 종료
  • 커버리지 부족: Warning만 표시, 실패 처리 안함 (post 블록에서 처리)
  • 문서 빌드 실패: 경고, 하지만 다음 단계 진행
  • 배포 실패: 실패 처리, Slack + 메일 알림

또한 QA에서는 다음과 같은 파이프라인이 유용합니다:

stage('Test Matrix') {
  matrix {
    axes {
      axis { name 'OS'; values 'ubuntu', 'centos' }
      axis { name 'JAVA'; values '8', '11' }
    }
    stages {
      stage('Run Test') {
        steps {
          sh './run_test.sh'
        }
      }
    }
  }
}

이렇게 하면 Jenkins가 다양한 OS와 자바 버전 조합으로 테스트를 병렬 실행해줍니다.

 

☁️ Jenkins + Kubernetes 통합 예제: 클라우드 네이티브 자동화를 위한 실전 구성

이제 본격적으로 Jenkins를 쿠버네티스 환경에 통합하는 방법을 알아볼게요. 많은 기업이 Jenkins를 Kubernetes 위에 올려놓고 사용하고 있는데요, 그 이유는 다음과 같습니다:

  • 빌드 에이전트를 Pod 단위로 동적으로 생성할 수 있어서 효율적입니다.
  • 빌드 격리성이 확보되고 리소스 낭비도 줄어듭니다.
  • Helm, ArgoCD, GitOps 등과도 손쉽게 연결할 수 있어요.

자, 이 챕터에서는 Kubernetes 위에서 Jenkins를 설치하고, PodTemplate 기반으로 빌드 에이전트를 생성하는 전체 흐름을 안내할게요.

🔹 1. Jenkins를 쿠버네티스에 설치하는 방법

1.1 Helm Chart로 설치하기 (추천)

Helm은 Kubernetes에서 Jenkins를 쉽게 배포할 수 있도록 도와주는 패키지 관리 도구입니다. 공식 chart도 잘 되어 있고, 유지보수도 활발합니다.

helm repo add jenkins https://charts.jenkins.io
helm repo update
helm upgrade --install jenkins jenkins/jenkins \
  --namespace jenkins --create-namespace \
  --set controller.adminUser=admin \
  --set controller.adminPassword=admin123 \
  --set controller.serviceType=LoadBalancer

설치가 완료되면 LoadBalancer IP로 Jenkins UI에 접속할 수 있습니다.

kubectl get svc -n jenkins

1.2 PVC, RBAC, Ingress 등 커스터마이징

Helm의 values.yaml을 수정하여 다음을 설정할 수 있어요:

  • persistence.enabled=true (빌드 데이터 유지)
  • rbac.create=true
  • controller.ingress.enabled=true (도메인 연결 시)
  • agent.image=jenkins/inbound-agent:latest (빌드용 기본 이미지)

🔹 2. Kubernetes Plugin 설치 및 설정

Jenkins UI에서 다음 플러그인을 설치합니다:

  • Kubernetes Plugin (cloud에 k8s 등록)
  • Pipeline Plugin
  • Credentials Binding Plugin

설정 경로: Manage Jenkins > Configure Cloud > Kubernetes

  • Kubernetes URL: https://kubernetes.default
  • Credentials: Jenkins에 등록된 ServiceAccount 토큰 사용
  • Jenkins URL: 내부 DNS 기준으로 http://jenkins.jenkins.svc.cluster.local:8080
  • Jenkins tunnel: jenkins-agent.jenkins.svc.cluster.local:50000

🔹 3. PodTemplate을 이용한 동적 Agent 정의

Jenkinsfile에서 agent를 아래처럼 정의하면, 빌드 시 Pod가 생성됩니다.

pipeline {
  agent {
    kubernetes {
      label 'mypod'
      defaultContainer 'jnlp'
      yaml """
apiVersion: v1
kind: Pod
spec:
  containers:
    - name: maven
      image: maven:3.8.1-jdk-11
      command:
        - cat
      tty: true
    - name: docker
      image: docker:20.10
      command:
        - cat
      tty: true
"""
    }
  }
  stages {
    stage('Build') {
      steps {
        container('maven') {
          sh 'mvn clean install'
        }
      }
    }
  }
}

이 코드는 빌드 시작 시 maven, docker 컨테이너가 포함된 Pod를 동적으로 생성하고, Build 단계에서는 maven 컨테이너 안에서 실행됩니다.

🔹 4. GitOps 연동과 ArgoCD 파이프라인 구성 (선택)

Kubernetes 기반 자동화의 핵심은 "Git이 진실의 원천"이 되는 구조입니다. Jenkins에서도 이를 실현할 수 있어요:

  • Git에서 values.yaml, deployment.yaml을 수정하고 PR을 생성
  • Jenkins가 이를 감지하고 Helm upgrade 수행
  • ArgoCD는 이 변경이 적용되었는지 상태를 추적

향후 챕터에서는 이 부분을 확장해 Jenkins → Helm → ArgoCD → K8s 클러스터 배포 흐름을 자동화하는 전략도 다룰 수 있어요.

📝 마무리 정리

쿠버네티스에서 Jenkins를 사용하면, 기존의 정적인 빌드 머신 구조보다 훨씬 더 유연하고 강력한 자동화 구조를 만들 수 있어요. 특히 빌드 컨테이너를 정의하는 YAML을 Jenkinsfile 안에 포함시킬 수 있다는 점이 가장 큰 장점입니다.

  • 빌드 머신이 부족하지 않음
  • 에이전트가 과부하 걸릴 일도 없음
  • 컨테이너 환경 덕분에 이식성과 테스트 용이성 향상
728x90
반응형

'Devops > Jenkins' 카테고리의 다른 글

[Jenkins] 젠킨스(Jenkins) - 유용한 플러그인(Plugin) 모음  (0) 2025.04.19
[Jenkins] 젠킨스(Jenkins)란? 역사와 등장 배경, 구조와 활용 방법  (0) 2025.04.19

'Devops/Jenkins'의 다른글

  • 현재글[Jenkins] 젠킨스(Jenkins) - 설치부터 운영까지 클라우드 네이티브 실전 예제 (+망 분리 환경)

관련글

티스토리툴바