Jenkins 설치와 파이프라인

Jenkins는 소프트웨어 개발의 지속적 통합(CI) 과 지속적 배포(CD) 를 지원하는 오픈소스 자동화 서버입니다. 코드 변경을 자동으로 빌드·테스트하고 배포까지 이어줍니다.

Docker로 설치

가장 간단한 건 Docker로 올리는 방법입니다.

docker run --name jenkins -d \
  -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  jenkins/jenkins:lts

8080은 웹 UI, 50000은 에이전트 통신용 포트입니다. jenkins_home 볼륨을 붙여 설정과 빌드 기록을 보존합니다. 권한 에러가 나면 볼륨 디렉토리 소유권을 맞춰줍니다(chown -R 1000:1000 ./jenkins_home).

브라우저로 http://[IP]:8080 에 접속한 뒤 초기 관리자 비밀번호를 확인합니다.

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

버전 선택: lts 태그는 안정화된 Long Term Support 릴리스입니다. Weekly(최신)는 새 기능이 빠르지만 버그 가능성이 있으니, 운영에는 LTS를 권장합니다. 특정 버전을 고정하려면 jenkins/jenkins:2.xxx 처럼 태그를 명시하세요.

파이프라인

Jenkins Pipeline은 빌드·테스트·배포 과정을 코드(워크플로우)로 정의합니다.

pipeline {
    agent any
    stages {
        stage('clone') {
            steps {
                git branch: "main", url: 'https://github.com/user/project'
            }
        }
        stage('build') {
            steps {
                sh "go build main.go"
            }
        }
        stage('execute') {
            steps {
                sh "./main"
            }
        }
    }
}

Agent: 파이프라인이 실행될 환경
Stage: 파이프라인의 단계 (이름으로 구분)
Step: 각 단계에서 수행하는 작업 단위

Git 저장소를 붙이려면 Jenkins 관리 → Credentials 에서 Username(Git ID)과 Password(Git Token)로 자격 증명을 추가하고 파이프라인에서 참조합니다.

쿠버네티스 연동

빌드마다 에이전트 파드를 동적으로 띄우려면 Kubernetes 플러그인을 씁니다. Jenkins 관리 → Plugins에서 “Kubernetes”를 설치한 뒤 Clouds → Kubernetes에 클러스터를 등록합니다.

Kubernetes URL: 클러스터 안에서는 https://kubernetes.default.svc
Namespace: jenkins
Credentials: Jenkins가 클러스터 안에 있으면 마운트된 ServiceAccount 사용
WebSocket: 외부 Jenkins나 리버스 프록시 환경에서 에이전트 포트 개방을 줄일 때 사용

Jenkins 전용 ServiceAccount를 만들고 필요한 네임스페이스에만 권한을 줍니다. 예전 방식처럼 clusterrole=admin을 바로 부여하면 자격 증명이 유출됐을 때 클러스터 전체가 위험합니다.

apiVersion: v1
kind: Namespace
metadata:
  name: jenkins
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: jenkins-agent
  namespace: jenkins
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: jenkins-agent-manager
  namespace: jenkins
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch", "create", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: jenkins-agent-manager
  namespace: jenkins
subjects:
  - kind: ServiceAccount
    name: jenkins-agent
    namespace: jenkins
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: jenkins-agent-manager

Jenkins 컨트롤러 Pod의 serviceAccountName을 jenkins-agent로 지정하면 플러그인이 마운트된 자격 증명을 사용할 수 있습니다. 클러스터 밖의 Jenkins에서 토큰 인증이 꼭 필요하다면 만료되는 토큰을 발급합니다.

kubectl -n jenkins create token jenkins-agent --duration=1h

장기 토큰 Secret은 자동 갱신되지 않고 유출 위험이 크므로 마지막 선택지로 둡니다. Test Connection이 성공한 뒤 실제 파이프라인으로 에이전트 파드가 생성·삭제되는지도 확인하세요.

pipeline {
  agent {
    kubernetes {
      defaultContainer 'golang'
      yaml '''
apiVersion: v1
kind: Pod
spec:
  containers:
    - name: golang
      image: golang:1.24
      command: [sleep]
      args: [99d]
'''
    }
  }
  stages {
    stage('test') {
      steps {
        sh 'go test ./...'
      }
    }
  }
}

문제가 생기면 kubectl -n jenkins get pods -w와 kubectl describe pod 이벤트부터 확인합니다. 설정 기준은 Jenkins Kubernetes 플러그인 문서와 Kubernetes ServiceAccount 문서를 참고했습니다.

CI/CD는 처음 세팅이 번거롭지만, 한 번 붙여두면 “푸시하면 알아서 빌드·배포”가 되니 그 뒤로는 정말 편해집니다.