Jenkins: Controller/Agent, pipeline as code và Shared Library

- Published on
- 11 mins read
Job build đỏ, và chẳng ai biết vì sao. Cấu hình nằm trên UI, do ai đó click từ lâu, không có lịch sử thay đổi để xem lại. Mười mấy service là mười mấy bản Jenkinsfile copy-paste, sửa một chỗ phải đi sửa cả chục chỗ.
Nói tới điều phối cả luồng CI/CD, từ lúc commit tới lúc chạy trên production, Jenkins vẫn là cái tên quen thuộc nhất. Theo mình, phần lớn nỗi khổ kiểu trên đến từ cách dùng nhiều hơn là từ bản thân Jenkins.
# bản chất
Nhiều người nghĩ Jenkins chỉ để "chạy test và build code". Thực ra Jenkins là một open-source automation server. Nó không tự làm hết mọi thứ mà điều phối (orchestrate) các công cụ khác (Maven, Docker, Kubernetes, SonarQube...) để ghép thành một Pipeline hoàn chỉnh.
Điểm mạnh nhất của Jenkins là Plugin-based Architecture. Với hơn 2.000 plugin (trang chủ jenkins.io ghi 2300+), nó tích hợp được với gần như mọi công nghệ, nên hay được dùng làm "Hub" trung tâm cho việc tự động hóa. Mặt trái là plugin cũng là nguồn lỗ hổng bảo mật và xung đột phiên bản lớn nhất; cài càng ít plugin càng đỡ khổ lúc nâng cấp.
# kiến trúc
Để CI/CD không thành nút thắt cổ chai (bottleneck) khi dự án lớn dần, Jenkins chia kiến trúc thành các phần rõ ràng:

Controller (Master) là "bộ não". Nó quản lý cấu hình, lên lịch (schedule) các job, giao tiếp với người dùng qua UI và phân phối công việc. Nguyên tắc ở đây là không chạy build trực tiếp trên Controller (đặt số executor của built-in node về 0). Vừa để khỏi cạn tài nguyên, vừa vì lý do bảo mật: build chạy trên controller đọc được cả thư mục JENKINS_HOME, nơi chứa credentials đã mã hoá cùng khoá giải mã.
Agents (Nodes/Slaves) là những "công nhân" chạy job. Muốn scale horizontally thì thêm agent, chạy trên Linux, Windows, hoặc spin-up tự động dưới dạng Docker containers/Kubernetes pods.
Executors là số luồng (slots) trên mỗi agent, quyết định có bao nhiêu build chạy song song trên agent đó.
# pipeline as code (jenkinsfile)
Cấu hình Job bằng cách click chuột trên UI là nguồn gốc của cảnh ở đầu bài. CI/CD nên được quản lý như source code: có version, có review. Jenkins có Declarative Pipeline, một cú pháp Groovy kiểu khai báo, dễ đọc và dễ bảo trì.
Đây là một Pipeline mẫu, gồm các khâu Checkout, Build, Unit Test, Code Quality, Build Docker và Deploy lên Kubernetes. Điều kiện when { branch ... } chỉ có tác dụng trong Multibranch Pipeline (xem phần dưới); junit, jacoco, withSonarQubeEnv, docker.build, slackSend, cleanWs đều đến từ plugin riêng, phải cài trước:
pipeline {
agent any
environment {
MAVEN_OPTS = '-Xmx512m'
NEXUS_CREDS = credentials('nexus-credentials')
}
options {
timeout(time: 30, unit: 'MINUTES') // Ngăn chặn treo job vĩnh viễn
disableConcurrentBuilds() // Đảm bảo tính nhất quán khi deploy
buildDiscarder(logRotator(numToKeepStr: '10')) // Tối giản không gian lưu trữ (Digital Danshari)
}
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Build') {
steps {
sh './mvnw clean package -DskipTests -s settings.xml'
}
}
stage('Unit Tests') {
steps {
sh './mvnw test -s settings.xml'
}
post {
always {
junit '**/target/surefire-reports/*.xml'
jacoco(execPattern: '**/target/jacoco.exec')
}
}
}
stage('Code Quality') {
parallel {
stage('SonarQube Analysis') {
steps {
withSonarQubeEnv('sonar') {
sh './mvnw sonar:sonar'
}
}
}
stage('Security Scan (Fortify)') {
steps {
sh 'scancentral -url ${FORTIFY_URL} start -bt mvn'
}
}
}
}
stage('Build & Push Docker Image') {
when { branch 'main' }
steps {
script {
def image = docker.build("registry/backend-service:${env.BUILD_NUMBER}")
docker.withRegistry('https://registry.example.com', 'docker-creds') {
image.push()
image.push('latest')
}
}
}
}
stage('Deploy to Staging') {
when { branch 'develop' }
steps {
sh 'kubectl apply -f k8s/staging/ --namespace=staging'
}
}
stage('Deploy to Production') {
when { branch 'main' }
input {
message "Duyệt deploy lên Production?" // Manual Gate
ok "Deploy"
}
steps {
sh 'kubectl apply -f k8s/prod/ --namespace=prod'
}
}
}
post {
success {
slackSend(channel: '#deployments', message: "✅ [${env.JOB_NAME}] Build #${env.BUILD_NUMBER} thành công. Chuẩn bị release.")
}
failure {
slackSend(channel: '#deployments', message: "[${env.JOB_NAME}] Build #${env.BUILD_NUMBER} thất bại. Cần kiểm tra ngay.")
}
always {
cleanWs() // Dọn dẹp Workspace để tránh leak data và tốn dung lượng
}
}
}Pipeline mẫu này có vài chỗ nên chỉnh khi dùng thật:
inputgiữ executor: vì cóagent anyở cấp pipeline, trong lúc chờ người bấm "Deploy" thì job vẫn chiếm một executor trên agent, có khi chờ cả buổi. Thêm nữa,timeout30 phút tính cả thời gian chờ duyệt. Cách thường làm là đểagent noneở cấp pipeline, khai báo agent cho từng stage, còn stage duyệt thì đặtinputkhông kèm agent và bọctimeoutriêng.- Image tag: stage build đẩy image tag
BUILD_NUMBER, nhưngkubectl apply -f k8s/prod/chỉ áp dụng manifest có sẵn trong repo. Nếu manifest trỏ tớilatestthì Kubernetes có thể không kéo image mới (pod không đổi spec thì không rollout). Nên thay tag trong manifest trước khi apply (kustomize edit set image,helm --set image.tag=...hoặckubectl set image). Nhánhdevelopcũng không build image nên staging chỉ apply lại manifest cũ. jacocostep thuộc plugin JaCoCo đã cũ; bản mới khuyên dùng plugin Coverage với steprecordCoverage.
# giải quyết bài toán scale
# multi-branch pipeline
Thay vì tạo tay từng Job cho từng nhánh, Multibranch Pipeline tự scan Git Repository. Thấy Jenkinsfile là nó tự tạo Pipeline tương ứng.
- main: tự chạy luồng Build + Deploy Production.
- develop: chạy luồng Build + Deploy Staging.
- feature/X hoặc PR: chỉ chạy Build, Unit Test và Security Scan.
Cơ chế đằng sau là mỗi nhánh thành một job con, và biến BRANCH_NAME (hoặc CHANGE_ID với PR) được set sẵn, nên các điều kiện when { branch 'main' } trong Jenkinsfile mới có nghĩa. Nhánh bị xoá thì job con cũng được dọn theo cấu hình "orphaned item strategy".
# shared libraries
Hệ thống lớn (ví dụ microservices với hàng chục services cùng stack Java/Spring Boot) mà copy-paste Jenkinsfile thì bảo trì rất khổ.
Shared Libraries đưa nguyên tắc DRY (Don't Repeat Yourself) vào CI/CD. Logic chung được gom vào một thư viện, còn Jenkinsfile của từng service chỉ việc gọi:
// File: vars/springBootPipeline.groovy (Đặt trong Repo Shared Library)
def call(Map config = [:]) {
pipeline {
agent any
stages {
stage('Build') {
steps {
sh "./mvnw clean package -P${config.profile ?: 'dev'} -s settings.xml"
}
}
stage('Test') {
steps {
sh './mvnw test -s settings.xml'
}
}
stage('Publish') {
when { expression { config.publish } }
steps {
sh './mvnw deploy -DskipTests -s settings.xml'
}
}
}
}
}
// File: Jenkinsfile (Nằm trong repo của từng Microservice)
@Library('my-shared-library') _
springBootPipeline(profile: 'dev', publish: true)Tên hàm gọi trong Jenkinsfile trùng với tên file trong thư mục vars/ (springBootPipeline.groovy → springBootPipeline(...)). Một file chỉ nên chứa nguyên một khối pipeline { } như trên; Jenkins hỗ trợ định nghĩa cả Declarative Pipeline trong shared library, nhưng chỉ ở dạng nguyên khối, không trộn được một nửa pipeline từ library với một nửa từ Jenkinsfile.
Nhờ vậy pipeline gọn hơn, và muốn nâng cấp logic CI/CD cho tất cả service thì chỉ sửa một chỗ. Mặt trái cũng ở đó: sửa library là ảnh hưởng mọi service cùng lúc. Nên gắn version cho library (@Library('my-shared-library@v1.4') _) và nâng dần, thay vì để mọi service luôn chạy nhánh main của library.
# credentials management
Không hardcode API Keys, Passwords hay Certificates vào code. Jenkins có Credentials Management để lo việc này. Để ý các lệnh sh bên dưới đều dùng nháy đơn: biến như $PASS được shell đọc từ biến môi trường lúc chạy. Nếu dùng nháy kép ("curl -u ${USER}:${PASS}") thì Groovy thay giá trị secret vào chuỗi lệnh trước, secret có thể lộ trong log hoặc danh sách process, và Jenkins sẽ cảnh báo "insecure interpolation of sensitive variables":
// Ẩn giấu cấu hình xác thực tinh tế
withCredentials([usernamePassword(
credentialsId: 'nexus-creds',
usernameVariable: 'USER',
passwordVariable: 'PASS')]) {
sh 'curl -u $USER:$PASS https://nexus/...'
}
// Secret text
withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
sh 'curl -H "Authorization: Bearer $API_KEY" ...'
}
// SSH key
withCredentials([sshUserPrivateKey(
credentialsId: 'deploy-key',
keyFileVariable: 'SSH_KEY')]) {
sh 'ssh -i $SSH_KEY user@server "deploy.sh"'
}
// File
withCredentials([file(credentialsId: 'kubeconfig', variable: 'KUBECONFIG')]) {
sh 'kubectl --kubeconfig=$KUBECONFIG apply -f ...'
}# triggers
pipeline {
triggers {
// Poll SCM every 5 minutes
pollSCM('H/5 * * * *')
// Cron schedule
cron('H 2 * * *') // daily at ~2am
// Webhook (GitLab/GitHub push)
gitlab(triggerOnPush: true, triggerOnMergeRequest: true)
}
}Ví dụ trên gom cả ba kiểu cho dễ nhìn, thực tế chọn một: có webhook thì bỏ pollSCM (poll liên tục chỉ tốn tải cho Git server). Chữ H trong cron là "hash": Jenkins rải giờ chạy theo tên job để hàng trăm job không cùng khởi động đúng một phút. Trigger gitlab(...) cần plugin GitLab; với GitHub thì dùng githubPush() hoặc cấu hình webhook ở Multibranch Pipeline.
# docker in jenkins
pipeline {
agent {
docker {
image 'maven:3.9-eclipse-temurin-21'
args '-v $HOME/.m2:/root/.m2' // cache dependencies
}
}
stages {
stage('Build') {
steps {
sh 'mvn clean package'
}
}
}
}# gitlab ci vs jenkins
| Aspect | Jenkins | GitLab CI |
|---|---|---|
| Config | Jenkinsfile (Groovy - lập trình được logic phức tạp) | .gitlab-ci.yml (YAML - khai báo tĩnh, cấu trúc chặt) |
| Hosting | Self-hosted | Built into GitLab |
| Plugins | 2000+ plugins | Ít hơn, chủ yếu tính năng built-in và CI/CD components |
| Flexibility | Rất cao (Groovy scripting), hợp với workflow orchestration phức tạp | Structured, less flexible - tốt cho các flow chuẩn, chuẩn hóa nhanh |
| Maintenance | Cần nguồn lực vận hành Server, update Plugins, vá lỗi bảo mật | Gần như không nếu dùng gitlab.com; self-managed vẫn phải vận hành |
| Docker | Plugin-based | Native Docker support |
| Scaling | Node/Agent mạnh nhưng cần setup cẩn thận | Runner-based, hỗ trợ Docker/K8s native sẵn |
# best practices
Vài nguyên tắc để vận hành Jenkins cho trơn tru:
- Pipeline as Code: Jenkinsfile nên nằm cùng repo code và được version hóa.
- Tách Controller và Agent: giữ Controller nhẹ, việc nặng đẩy xuống Agents.
- Dùng Docker Agent: đừng cài thẳng JDK, Node.js hay Maven lên Agent. Dùng Docker Image (VD: maven:3.9-eclipse-temurin-21) làm môi trường build, để tránh "Works on my machine" hoặc xung đột phiên bản giữa các job.
- Luôn set Timeout: để job bị treo (deadlock) không âm thầm ngốn tài nguyên.
- Dọn dẹp (Clean Workspace): thêm bước cleanWs() ở cuối pipeline, đỡ các lỗi khó hiểu do cache cũ để lại.
- Dùng Parallel Stages: các khâu độc lập như Unit Test, quét SonarQube, check lỗ hổng Fortify... cho chạy song song để dev đỡ phải chờ.
- Giữ code Groovy trong Jenkinsfile thật mỏng: mọi câu lệnh Groovy của Pipeline thực chất chạy trên JVM của Controller (theo cơ chế CPS để lưu trạng thái), còn các step như
sh,batmới thực sự chạy trên Agent. Parse JSON nặng hay tính toán phức tạp bằng Groovy sẽ làm đơ luôn Controller.
# common patterns
# maven build với settings dùng chung
configFileProvider (plugin Config File Provider) lấy file settings.xml lưu trên Jenkins ra một file tạm, nên khỏi commit settings.xml chứa thông tin repository nội bộ vào từng repo. Muốn cache dependency giữa các build thì vẫn phải mount thư mục .m2 như phần Docker ở trên.
stage('Build') {
steps {
configFileProvider([configFile(fileId: 'maven-settings', variable: 'MAVEN_SETTINGS')]) {
sh "./mvnw clean package -s $MAVEN_SETTINGS -DskipTests"
}
}
}# conditional deployment
stage('Deploy') {
when {
allOf {
branch 'main'
not { changeRequest() }
}
}
steps { ... }
}# matrix builds (multiple jdk versions)
stage('Test') {
matrix {
axes {
axis {
name 'JDK'
values '17', '21'
}
}
stages {
stage('Test') {
agent { docker { image "eclipse-temurin:${JDK}" } }
steps { sh './mvnw test' }
}
}
}
}Nếu đang tiếp quản một Jenkins có sẵn, mình sẽ làm theo thứ tự này: đặt số executor của built-in node về 0, chuyển các job click tay thành Jenkinsfile nằm cùng repo, rồi soát những lệnh sh dùng nháy kép có chèn secret. Khi Jenkinsfile giữa các service giống nhau tới mức copy-paste thì tách ra Shared Library, nhớ gắn version. Phần build image cho agent và pipeline thì xem thêm bài docker & container.
Chỉ là những ghi chép cá nhân với hy vọng mang lại chút giá trị. Nếu thấy hữu ích, đừng ngại chia sẻ cho bạn bè & đồng nghiệp nhé!
Happy coding 😎 👍🏻 🚀 🔥.
On this page
- # bản chất
- # kiến trúc
- # pipeline as code (jenkinsfile)
- # giải quyết bài toán scale
- # multi-branch pipeline
- # shared libraries
- # credentials management
- # triggers
- # docker in jenkins
- # gitlab ci vs jenkins
- # best practices
- # common patterns
- # maven build với settings dùng chung
- # conditional deployment
- # matrix builds (multiple jdk versions)