Nâng cấp Jenkins

Nâng cấp Jenkins không chỉ là thay một binary hoặc image tag. Jenkins core, Java, plugin, JENKINS_HOME, agent và Pipeline tạo thành một thay đổi vận hành có trạng thái. Trang này mô tả cách đưa thay đổi đó qua staging trước, bảo vệ dữ liệu và chỉ mở lại lịch chạy khi có bằng chứng hoạt động.

Mục lụcCopy Anchor Link

• Chọn phiên bản có hỗ trợ
  • LTS và weekly release
  • Đọc thông tin thay đổi và ghi version pin
• Kiểm tra compatibility trước khi đổi
  • Ma trận tương thích
  • Core, plugin và Pipeline
  • Storage, controller và agent
• Kế hoạch nâng cấp có kiểm soát
  • Timeline và điểm quyết định
  • Inventory, backup và diễn tập restore
  • Staging và tiêu chí go-no-go
• Runbook triển khai
  • Chuẩn bị cửa sổ thay đổi
    • Đóng băng thay đổi và thông báo
    • Dừng nhận workload có kiểm soát
    • Xác nhận điểm khôi phục
    • Áp dụng artifact đã pin
    • Khởi động, xác minh rồi mới mở lịch
  • Triển khai theo đường cài đặt
  • Health check và evidence sau nâng cấp
• Rollback thực tế
  • Khi nào rollback
  • Thực hiện rollback
  • Kiểm thử sau rollback
• Lab sandbox local
  • Tạo baseline cô lập
  • Backup, nâng cấp và kiểm tra
  • Khôi phục và cleanup an toàn
• Troubleshooting
• Checklist phát hành
• Nguồn Jenkins chính thức

Chọn phiên bản có hỗ trợCopy Anchor Link

LTS và weekly releaseCopy Anchor Link

Jenkins phát hành hai dòng core. Weekly nhận tính năng và thay đổi mới sớm hơn; nó phù hợp khi đội có staging thường xuyên, cần một sửa đổi cụ thể và chấp nhận cadence thay đổi nhanh. LTS là dòng ổn định cho đa số controller production: các bản LTS nhận backport bug fix và security fix đã được chọn lọc trong vòng đời hỗ trợ của dòng đó.

Không chọn chỉ theo số version lớn nhất. Với mỗi controller, xác định phiên bản đích từ Support Policy, trạng thái LTS trên changelog và policy nội bộ. Không bắt đầu một thay đổi production với một weekly hoặc LTS đã hết support. Nếu cần đi qua nhiều LTS, đọc từng mốc trong LTS Upgrade Guide thay vì nhảy qua các cảnh báo trung gian.

Đọc thông tin thay đổi và ghi version pinCopy Anchor Link

Trước khi phê duyệt, đọc bốn nguồn cho mọi version được đi qua: LTS Upgrade Guide, changelog/release notes, Jenkins Security Advisories và trang release/compatibility của từng plugin quan trọng. Security advisory có thể buộc phải nâng core hoặc plugin; nó không thay thế kiểm thử behavior.

Ghi một bản kế hoạch bất biến trong ticket thay đổi hoặc repository vận hành. Bản ghi tối thiểu gồm:

Một tag trôi như lts-jdk21 hoặc latest không phải version pin. Với Docker, lưu cả digest đã inspect. Với Helm, pin chart version và image controller trong values.yaml; chart mới có thể đổi default image. Với package, lưu chính xác version package và repository/channel đã dùng. Tất cả artifact cũ cần còn truy xuất được đến hết cửa sổ rollback.

Kiểm tra compatibility trước khi đổiCopy Anchor Link

Ma trận tương thíchCopy Anchor Link

Dùng một ma trận cho từng controller, không suy luận từ một controller khác. So sánh trạng thái hiện tại, đích và kết quả staging; ô chưa được xác minh là lý do trì hoãn production.

Nền tảng controller, queue và agent được giải thích trong Kiến trúc Jenkins; yêu cầu Java, storage và network nằm ở Yêu cầu hệ thống.

Core, plugin và PipelineCopy Anchor Link

Plugin là mã chạy trong controller. Nâng core mà giữ nguyên toàn bộ plugin không mặc nhiên an toàn; nâng hàng loạt plugin cùng lúc cũng làm rộng phạm vi sự cố. Phân nhóm plugin thành: bắt buộc cho controller khởi động, bắt buộc cho Pipeline/SCM/credential, và plugin ít dùng. Trong Manage Jenkins → Plugins, ghi plugin đang cài cùng dependency; sau đó xem Update Center và release notes để lập một plugin plan có version cụ thể.

Ưu tiên một thay đổi dễ điều tra: core trước hoặc một plugin bundle đã kiểm thử, trừ khi release note yêu cầu nâng cùng nhau. Không chép file .jpi từ controller khác, không xóa plugin để “sửa” boot failure, và không downgrade plugin trên JENKINS_HOME production khi chưa có hướng dẫn của plugin. Một dependency downgrade có thể tạo một tổ hợp core-plugin chưa từng được hỗ trợ.

Kiểm thử Pipeline bằng workload đại diện, không chỉ job echo. Bộ mẫu nên bao gồm checkout từ SCM, shared library, Declarative và Scripted Pipeline nếu đều đang dùng, credentials binding không lộ secret, artifact/test report, post action, agent label và một đường deploy bị chặn ở môi trường staging. Xem nền tảng tại Tổng quan Jenkins Pipeline, cách chọn executor tại Chọn agent cho Pipeline và giới hạn credential tại Credentials trong Pipeline.

Storage, controller và agentCopy Anchor Link

Snapshot storage chỉ hữu ích khi nhà cung cấp xác nhận tính nhất quán và có thể restore. Để tạo backup ở trạng thái biết trước, quiet down, chờ build kết thúc hoặc abort theo policy, rồi dừng controller trước khi chụp/archive JENKINS_HOME. Backup cần bao gồm cấu hình, plugin, job/build metadata và key/secret liên quan theo policy bảo mật; mã hóa, phân quyền và tách failure domain. Thực hiện restore drill vào home/PVC/volume mới, không ghi đè home đang phục vụ.

Controller điều phối, giữ queue và dữ liệu. Nó không phải build farm: đặt built-in node/controller bằng 0 executor ở production và chạy workload trên agent riêng. Trước và sau nâng cấp, kiểm tra agent inbound/SSH/Kubernetes, certificates, URL công khai, label, toolchain, workspace và quyền network. Một agent online nhưng không có đúng label hoặc Java/toolchain vẫn làm Pipeline chờ hoặc fail.

Kế hoạch nâng cấp có kiểm soátCopy Anchor Link

Timeline và điểm quyết địnhCopy Anchor Link

direction: down
inventory: "T-7 đến T-2: Inventory\nmatrix Java/OS/plugin/agent/Pipeline"
restore: "Restore drill\nbackup vào môi trường cô lập"
go: "T-1: Go/no-go\nowner, freeze config, rollback"
quiet: Quiet down
backup: "Backup\nID backup + snapshot đã xác nhận"
deploy: Deploy
validate: Validate boot/plugin/Pipeline
evidence: Evidence
resume: Mở lịch
rollback: Rollback
inventory -> restore -> go -> quiet -> backup -> deploy -> validate -> evidence
validate -> rollback: Lỗi boot/plugin/Pipeline
evidence -> resume: Đạt tiêu chí
evidence -> rollback: Không đạt

Người phê duyệt cần định nghĩa rõ ai có quyền dừng lịch, ai xác nhận backup, ai theo dõi ứng dụng và thời gian tối đa để quyết định rollback. Ghi các mốc UTC, người thao tác, lệnh/manifest được dùng và link evidence. Không để một thao tác viên vừa thay đổi vừa là nguồn xác nhận duy nhất.

Inventory, backup và diễn tập restoreCopy Anchor Link

Trước cửa sổ thay đổi, chụp inventory read-only: version Jenkins từ Manage Jenkins → System Information, Java, JENKINS_HOME/PVC/volume, package/image/chart pin, plugin inventory, agent list/labels, số executor, queue/build đang chạy, cấu hình as-code và integration quan trọng. Lưu output vào nơi được kiểm soát; inventory có thể chứa hostname, URL hoặc metadata nhạy cảm.

Tạo backup nhất quán và đặt tên có timestamp/ID. Xác nhận backup hoàn tất, checksum/retention, mã hóa, quyền đọc và vị trí ngoài failure domain trước khi bắt đầu deploy. Sau đó restore backup đó vào một môi trường cô lập, khởi động bằng core/plugin pin dự kiến cho rollback và kiểm tra login, job metadata, plugin load, một agent thử cùng một Pipeline smoke test. Một archive tồn tại không chứng minh khả năng restore.

Staging và tiêu chí go-no-goCopy Anchor Link

Staging cần dùng bản sao dữ liệu đã được làm sạch theo policy hoặc cấu hình tương đương, cùng Java, hình thức cài đặt và plugin plan như production. Không cho staging gửi webhook, email, deploy hoặc dùng credential production. Ghi version đích sau khi staging boot thành công và kết quả của test matrix.

Chỉ go khi các điều kiện sau đều đúng: backup ID có restore drill pass; storage/snapshot đã xác nhận; Java và artifact pin khớp; không còn build không thể ngắt hoặc migration chưa hiểu; plugin plan được owner chấp nhận; agent/Pipeline smoke test pass trên staging; kênh thông báo và rollback owner sẵn sàng. Một trong các điều kiện sai là no-go, không phải việc “sửa nhanh” trong production.

Runbook triển khaiCopy Anchor Link

Chuẩn bị cửa sổ thay đổiCopy Anchor Link

Triển khai theo đường cài đặtCopy Anchor Link

Các ví dụ dưới đây minh họa điểm kiểm soát, không phải lệnh chung để áp vào một controller chưa inventory. Thay các biến bằng pin đã được review. Không thay đổi đường dẫn JENKINS_HOME, UID/GID, PVC hoặc dữ liệu trong khi đổi artifact.

TARGET_IMAGE='jenkins/jenkins:<approved-version>-jdk21'
docker pull "$TARGET_IMAGE"
docker image inspect "$TARGET_IMAGE" \
  --format 'tag={{index .RepoTags 0}} digest={{index .RepoDigests 0}}'

# Sau quiet down, backup và khi controller đã dừng theo Compose runbook:
docker compose config > compose-rendered-before-upgrade.yaml
docker compose pull jenkins
docker compose up -d --no-deps --force-recreate jenkins
docker compose ps
docker compose logs --tail=200 jenkins

Health check và evidence sau nâng cấpCopy Anchor Link

Trước khi mở scheduling, theo dõi log đến khi Jenkins hoàn tất khởi động và không còn lỗi plugin/dependency lặp lại. Xác nhận giao diện qua URL TLS chuẩn, core version, Java runtime, plugin set, cấu hình global, credentials chỉ ở mức hiện diện (không đọc secret), queue và disk/storage health.

Chạy smoke test có kiểm soát trên agent cho từng pool quan trọng: checkout repository thử, resolve shared library nếu dùng, build/test không đặc quyền, publish test report/artifact và một credential binding staging. Không chạy workload trên controller để “kiểm tra nhanh”. Ghi build URL/number, Console Output, agent label, thời lượng, result và metric CPU/RAM/disk/queue trước–sau vào ticket.

Mở lại scheduling theo từng nhóm job nếu policy cho phép. Theo dõi webhook, queue, agent reconnect, error rate và thời lượng Pipeline trong khoảng quan sát đã định. Giữ backup, artifact cũ và khả năng rollback cho đến khi owner chấp nhận evidence.

Rollback thực tếCopy Anchor Link

Khi nào rollbackCopy Anchor Link

Quyết định rollback theo tiêu chí được chốt trước cửa sổ, ví dụ: controller không boot trong timeout, plugin nền tảng không load, agent quan trọng không kết nối, smoke test Pipeline fail có thể tái hiện, hoặc chỉ số lỗi vượt ngưỡng. Không rollback chỉ vì một cảnh báo đã biết nhưng không ảnh hưởng tiêu chí; ngược lại, không kéo dài troubleshooting khi đã vượt thời gian quyết định.

Trước khi hành động, dừng scheduling, giữ log và trạng thái lỗi, thông báo owner và kiểm tra xem core/plugin đã chạy migration một chiều chưa. Nếu chưa có bằng chứng tương thích ngược, chọn restore backup thay vì khởi động binary cũ trên home đã bị phiên bản mới ghi.

Thực hiện rollbackCopy Anchor Link

1. Giữ nguyên home/PVC/volume hiện tại để điều tra; không ghi đè backup duy nhất.
2. Pin lại core, Java, package/image digest hoặc chart revision đã được staging cho đường rollback.
3. Restore backup nhất quán trước nâng cấp vào storage mới hoặc volume/PVC đã được kiểm soát; khôi phục key/secret liên quan theo chính sách bảo mật.
4. Chỉ để một controller cũ dùng bản dữ liệu restore đó. Kiểm tra quyền storage, URL và network trước boot.
5. Khởi động, giữ quiet down, rồi chạy health check và smoke test giống acceptance của bản mới.
6. Chỉ mở lịch lại sau khi evidence pass; lưu thời điểm rollback, backup ID, version đã pin và nguyên nhân.

Với Docker, rollback thường là recreate bằng image digest cũ và volume đã restore, không phải chỉ đổi tag trong container hiện tại. Với package, cài đúng version cũ còn có trong repository/cache theo runbook distro, rồi dùng home restore. Với Helm, có thể dùng helm rollback cho manifest, nhưng PVC vẫn cần được khôi phục từ snapshot/backup tương thích; revision Helm cũ không làm dữ liệu tự quay lại. Với Windows, dùng MSI LTS cũ đã pin cùng bản backup restore, không dùng một copy live của home.

Kiểm thử sau rollbackCopy Anchor Link

Đối chiếu core/Java/plugin inventory với baseline. Xác minh login, job/config metadata, agent chính, credential binding staging, Pipeline smoke test và queue. Quan sát một khoảng tương tự sau nâng cấp trước khi kết luận ổn định. Nếu restore fail hoặc behavior còn sai, giữ scheduling đóng, bảo toàn evidence và chuyển sang quy trình incident/recovery của tổ chức; không thử nhiều tổ hợp version trực tiếp trên cùng dữ liệu.

Lab sandbox localCopy Anchor Link

Lab này mô phỏng quy trình bằng Docker named volume riêng, không dùng controller thật, credential thật, webhook hay repository production. Chọn hai image Jenkins đã đối chiếu support policy: một baseline và một target. Mỗi image phải là tag/digest đã pin, không dùng latest.

Tạo baseline cô lậpCopy Anchor Link

export LAB_PREFIX='jenkins-upgrade-lab'
export BASELINE_IMAGE='jenkins/jenkins:<approved-baseline>-jdk21'
export TARGET_IMAGE='jenkins/jenkins:<approved-target>-jdk21'
export BASELINE_VOL="${LAB_PREFIX}-baseline"
export CANDIDATE_VOL="${LAB_PREFIX}-candidate"
export ROLLBACK_VOL="${LAB_PREFIX}-rollback"
export BASELINE_CTR="${LAB_PREFIX}-baseline"
export CANDIDATE_CTR="${LAB_PREFIX}-candidate"

# Kiểm tra context, pull và ghi digest trước khi tạo dữ liệu lab.
docker context show
docker pull "$BASELINE_IMAGE"
docker pull "$TARGET_IMAGE"
docker image inspect "$BASELINE_IMAGE" --format '{{index .RepoDigests 0}}'
docker image inspect "$TARGET_IMAGE" --format '{{index .RepoDigests 0}}'

docker volume create "$BASELINE_VOL"
docker run -d --name "$BASELINE_CTR" \
  -p 127.0.0.1:18080:8080 \
  -v "$BASELINE_VOL":/var/jenkins_home \
  "$BASELINE_IMAGE"
docker logs -f "$BASELINE_CTR"

Kết quả mong đợi: log báo Jenkins sẵn sàng, UI chỉ mở ở http://127.0.0.1:18080, và docker volume inspect "$BASELINE_VOL" cho thấy volume lab. Hoàn tất setup tối thiểu trong UI nếu cần; không thêm secret. Dừng theo Ctrl-C chỉ dừng theo dõi log, không dừng container.

Backup, nâng cấp và kiểm traCopy Anchor Link

Dừng baseline để tạo bản archive ở trạng thái yên tĩnh. Copy archive vào thư mục lab được bảo vệ; lệnh không đụng volume của controller khác.

docker stop "$BASELINE_CTR"
mkdir -p .jenkins-upgrade-lab-backups
BACKUP_FILE=".jenkins-upgrade-lab-backups/${LAB_PREFIX}-baseline.tgz"
docker run --rm \
  -v "$BASELINE_VOL":/data:ro \
  -v "$PWD/.jenkins-upgrade-lab-backups":/backup \
  alpine:3.20 sh -c 'cd /data && tar czf /backup/jenkins-upgrade-lab-baseline.tgz .'
tar tzf "$BACKUP_FILE" | head

docker volume create "$CANDIDATE_VOL"
docker run --rm \
  -v "$CANDIDATE_VOL":/data \
  -v "$PWD/.jenkins-upgrade-lab-backups":/backup:ro \
  alpine:3.20 sh -c 'tar xzf /backup/jenkins-upgrade-lab-baseline.tgz -C /data'
docker run -d --name "$CANDIDATE_CTR" \
  -p 127.0.0.1:18081:8080 \
  -v "$CANDIDATE_VOL":/var/jenkins_home \
  "$TARGET_IMAGE"
docker logs -f "$CANDIDATE_CTR"

Kết quả mong đợi: baseline archive liệt kê được, candidate boot từ bản sao home ở http://127.0.0.1:18081, và System Information hiển thị target core/Java. Ghi hai digest, thời gian boot và lỗi plugin nếu có. Tạo một job Pipeline chỉ in echo 'upgrade smoke test'; kết quả phải là SUCCESS. Nếu boot hoặc smoke test fail, không dùng candidate volume cho baseline—chuyển sang phần khôi phục.

Khôi phục và cleanup an toànCopy Anchor Link

Để diễn tập rollback, restore cùng archive vào volume thứ ba rồi boot nó bằng baseline image. Điều này kiểm tra backup và pin cũ mà không hạ version trên candidate đã được nâng cấp.

docker volume create "$ROLLBACK_VOL"
docker run --rm \
  -v "$ROLLBACK_VOL":/data \
  -v "$PWD/.jenkins-upgrade-lab-backups":/backup:ro \
  alpine:3.20 sh -c 'tar xzf /backup/jenkins-upgrade-lab-baseline.tgz -C /data'
docker run -d --name "${LAB_PREFIX}-rollback" \
  -p 127.0.0.1:18082:8080 \
  -v "$ROLLBACK_VOL":/var/jenkins_home \
  "$BASELINE_IMAGE"
docker logs -f "${LAB_PREFIX}-rollback"

Kết quả mong đợi: rollback controller boot bằng baseline pin từ volume restore mới; xác nhận version và job smoke test trong UI. Trước cleanup, liệt kê chính xác tài nguyên sẽ xóa. Chỉ khi danh sách chỉ có lab này và bạn không cần giữ evidence, chạy đoạn guard sau:

case "$LAB_PREFIX" in
  jenkins-upgrade-lab) ;;
  *) echo 'Từ chối cleanup: prefix không hợp lệ' >&2; exit 1 ;;
esac

docker ps -a --filter "name=${LAB_PREFIX}" --format 'table {{.Names}}\t{{.Status}}'
docker volume ls --format '{{.Name}}' | grep "^${LAB_PREFIX}-" || true
# Xem lại output ở trên trước khi bỏ comment ba dòng xóa bên dưới.
# docker rm -f "$BASELINE_CTR" "$CANDIDATE_CTR" "${LAB_PREFIX}-rollback"
# docker volume rm "$BASELINE_VOL" "$CANDIDATE_VOL" "$ROLLBACK_VOL"
# rm -rf .jenkins-upgrade-lab-backups

Các dòng phá hủy được comment có chủ đích. Không chạy docker volume prune, docker system prune --volumes hoặc cleanup toàn cục để dọn lab.

TroubleshootingCopy Anchor Link

Checklist phát hànhCopy Anchor Link

• Đã chọn LTS hoặc weekly còn được support và đọc mọi mốc upgrade guide đi qua.
• Đã ghi core, Java, package/image digest/chart, plugin và config version pin.
• Đã đọc changelog, security advisories và release notes của plugin quan trọng.
• Ma trận Java, OS/package/image/chart, plugin, Pipeline, storage và agent đã pass ở staging.
• Controller production có 0 executor; smoke test chạy trên agent phù hợp.
• Inventory, backup nhất quán, checksum/quyền lưu trữ và restore drill có evidence.
• Owner đã nhận thông báo; config/plugin freeze, quiet down và xử lý build đang chạy có kế hoạch.
• Snapshot/backup ID, rollback pin và tiêu chí quyết định đã được phê duyệt trước deploy.
• Đã kiểm tra boot, core/Java/plugin, agent, Pipeline, queue, storage và metric sau nâng cấp.
• Chỉ mở lại scheduling sau evidence; backup và artifact rollback vẫn được giữ theo retention.

Nguồn Jenkins chính thứcCopy Anchor Link

• Jenkins LTS Upgrade Guide
• Jenkins changelog
• Jenkins Security Advisories
• Jenkins Support Policy
• Java Support Policy
• Managing Plugins
• Installing Jenkins
• Jenkins Docker image
• Jenkins Helm chart upgrade notes