Backup & Restore Jenkins

Mục lụcCopy Anchor Link

• Mục tiêu phục hồi
• Phạm vi cần bảo vệ
  • Dữ liệu thuộc JENKINS_HOME
  • Dữ liệu không nên sao lưu mù
• Chiến lược nhất quán
  • Chọn cửa sổ và phương pháp
  • Docker, package/systemd và Kubernetes
• Chính sách bảo vệ bản sao
• Quy trình tạo backup tham chiếu
  • Ghi nhận inventory và cửa sổ backup
  • Tạo điểm dữ liệu đứng yên
  • Backup persistent data và xác minh ngay
  • Ghi nhận bằng chứng và khôi phục dịch vụ
• Quy trình restore trên controller cô lập
  • Chọn bản sao và kiểm tra tính phù hợp
  • Chuẩn bị controller cô lập
  • Đặt dữ liệu và khóa theo đúng quan hệ
  • Khởi động có kiểm soát và đối chiếu môi trường
  • Quyết định chuyển đổi hoặc rollback
• Kiểm chứng phục hồi và restore drill
• Lab local sandbox
  • Tạo workspace lab và dữ liệu giả
  • Đóng gói, tạo checksum và kiểm tra archive
  • Restore sang thư mục cô lập và đối chiếu nội dung
  • Cleanup đúng phạm vi lab
• Khắc phục sự cố
• Checklist vận hành
• Tài liệu liên quan
• Nguồn chính thức

Mục tiêu phục hồiCopy Anchor Link

Backup Jenkins không chỉ là nén một thư mục. Mục tiêu là khôi phục một controller về trạng thái có thể đăng nhập, đọc cấu hình job, giải mã credential bằng đúng khóa gốc, nhận diện plugin và chạy một kiểm tra không phá hủy.

Trước khi chọn công cụ, chốt hai mục tiêu với owner dịch vụ:

RPO quyết định tần suất và loại snapshot. RTO quyết định vị trí bản sao, băng thông, tài liệu runbook và mức độ tự động hóa. Cả hai phải tính cả thời gian tải bản sao offsite, giải mã, kiểm tra checksum và xác nhận của người vận hành.

Phạm vi cần bảo vệCopy Anchor Link

Dữ liệu thuộc JENKINS_HOMECopy Anchor Link

JENKINS_HOME là trạng thái bền vững của controller, không chỉ là thư mục job. Vị trí thực tế phụ thuộc cách cài đặt; xác nhận nó tại Manage Jenkins → System hoặc qua biến môi trường của service/container trước khi đưa vào policy.

Nếu artifact được đẩy sang object storage, artifact manager hoặc repository ngoài JENKINS_HOME, backup home không bao hàm dữ liệu đó. Lập inventory cho từng backend và kiểm tra cơ chế backup/retention của backend tương ứng.

Dữ liệu không nên sao lưu mùCopy Anchor Link

Không phải byte nào gần Jenkins cũng đáng đưa vào backup. Sao lưu mù làm tăng chi phí, kéo dài RTO và có thể thu thập dữ liệu tạm hoặc secret bị rò trong workspace.

• Cache và dữ liệu tái tạo được: download cache, update center cache, thư mục tạm và file lock nên được loại trừ sau khi xác nhận chúng không chứa cấu hình cần giữ.
• Agent workspace: workspace là vùng làm việc của agent, không phải nguồn khôi phục controller. Nó có thể lớn, ngắn hạn, chứa checkout hoặc file sinh ra từ build. Hãy tái tạo từ source, dependency cache có kiểm soát và Pipeline.
• Remote agent và ephemeral agent: dữ liệu trên VM agent, Docker agent hoặc Pod agent có vòng đời riêng. Xác định retention theo workload thay vì gộp vào backup JENKINS_HOME.
• Log và artifact lớn: chỉ đưa vào bản sao khi RPO/RTO và yêu cầu audit cần chúng. Nếu chuyển sang log/artifact backend riêng, kiểm tra policy của backend đó.

Xem tổng quan Jenkins, kiến trúc Jenkins, Pipeline và agents để phân biệt controller, agent, executor và workspace.

Chiến lược nhất quánCopy Anchor Link

Một bản sao nhất quán có các file phản ánh cùng một thời điểm logic. Copy JENKINS_HOME khi controller đang ghi config.xml, build record hoặc credential metadata có thể tạo tập file nửa cũ nửa mới. Không khuyến nghị copy live tùy tiện rồi coi đó là backup có thể restore.

Chọn cửa sổ và phương phápCopy Anchor Link

Ưu tiên theo thứ tự sau, sau khi đánh giá RPO/RTO và cơ chế storage:

1. Quiet down rồi dừng controller sạch sẽ. Quiet down ngăn build mới vào queue; đợi build đang chạy kết thúc hoặc xử lý theo quyết định đã phê duyệt, sau đó stop service/container/Pod và tạo bản sao khi dữ liệu đứng yên. Đây là phương án dễ giải thích nhất cho backup file-level.
2. Snapshot application-consistent. Dùng snapshot volume/storage chỉ khi nền tảng và runbook chứng minh snapshot được điều phối sau quiet down hoặc stop, có điểm khôi phục rõ ràng và đã restore drill thành công.
3. Backup do nền tảng quản lý. Có thể dùng công cụ backup volume hoặc filesystem, nhưng nó phải bao phủ đúng persistent data, mã hóa, checksum, retention và quy trình khôi phục đã kiểm chứng.

Docker, package/systemd và KubernetesCopy Anchor Link

Tham khảo hướng dẫn Docker, Linux, Kubernetes và Windows để đối chiếu cách cài đặt. Với agent chạy container hoặc Pod, xem Docker agents và Kubernetes agents.

direction: right
controller: "Jenkins controller"
home: "JENKINS_HOME\nkeys + data" {shape: cylinder}
backup: "Encrypted backup\nchecksum + manifest"
offsite: "Kho offsite\nquyền truy cập tách biệt" {shape: cylinder}
restore: "Controller cô lập\nrestore + verify"
controller -> home: "Quiet down / stop\nđiểm khôi phục đã kiểm chứng"
home -> backup: Snapshot / archive
backup -> offsite: Offsite copy
offsite -> restore
controller -> restore: Khôi phục đã kiểm chứng {style.stroke-dash: 4}

Chính sách bảo vệ bản saoCopy Anchor Link

Một policy tối thiểu phải trả lời được ai tạo/đọc/restore bản sao, bản sao được giữ ở đâu, trong bao lâu, và có thể chứng minh nó không bị thay đổi thế nào.

• Mã hóa: mã hóa khi truyền và khi lưu. Lưu khóa mã hóa backup trong hệ thống quản lý khóa được phê duyệt, tách khỏi nơi chứa archive; định kỳ kiểm tra khả năng giải mã theo quy trình kiểm soát.
• Offsite: duy trì ít nhất một bản sao ở fault domain khác với controller, ví dụ account/project hoặc site khác. Offsite không đồng nghĩa public bucket; chặn public access và dùng IAM tối thiểu.
• Retention: định nghĩa chu kỳ daily/weekly/monthly, thời gian giữ và cơ chế xóa theo policy. Giữ đủ generations để rollback về trước thời điểm lỗi được phát hiện, đồng thời kiểm soát chi phí artifact/log lớn.
• Access control: cấp quyền đọc bản sao, quyền dùng khóa và quyền khởi tạo restore theo vai trò riêng. Bật audit log cho thao tác tải, xóa, thay policy và restore.
• Checksum và chain of custody: tạo manifest ghi backup ID, thời điểm, nguồn, công cụ, phiên bản, checksum SHA-256 và người/automation tạo. Kiểm tra checksum sau upload và trước restore. Lưu log phê duyệt, vị trí archive và kết quả drill để truy vết ai đã chạm vào bản sao.

Ví dụ dưới đây chỉ minh họa manifest cho archive đã mã hóa. Thay <backup-file> bằng tên file trong sandbox hoặc runbook nội bộ; không dùng tên, bucket hay khóa thật trong tài liệu công khai.

sha256sum <backup-file>.tar.enc > <backup-file>.tar.enc.sha256
sha256sum --check <backup-file>.tar.enc.sha256

Kết quả mong đợi của lệnh thứ hai là <backup-file>.tar.enc: OK. Checksum chỉ chứng minh file đã kiểm tra không đổi so với manifest; nó không chứng minh archive chứa một snapshot Jenkins nhất quán.

Quy trình tạo backup tham chiếuCopy Anchor Link

Điều chỉnh câu lệnh theo công cụ backup đã được phê duyệt. Các giá trị minh họa dưới đây cố ý không thể chạy trực tiếp trên một hệ thống thật.

find <lab-jenkins-home>/plugins -maxdepth 1 -name '*.jpi' -printf '%f\n' | sort > <lab-backup-dir>/plugin-inventory.txt

Quy trình restore trên controller cô lậpCopy Anchor Link

Restore là một thay đổi rủi ro cao. Làm trên network/namespace/account cô lập trước; controller thử nghiệm không được có quyền gửi webhook, trigger production agent hay ghi vào artifact repository production.

Kiểm chứng phục hồi và restore drillCopy Anchor Link

Một restore drill là phép thử định kỳ rằng người, khóa, công cụ, backup và runbook cùng hoạt động. Lên lịch drill theo RPO/RTO và sau thay đổi lớn như nâng Jenkins, thay storage, đổi artifact backend hoặc xoay quyền truy cập.

Đặt tiêu chí pass/fail trước khi thử:

• controller cô lập start thành công, không có lỗi permission hoặc plugin nghiêm trọng;
• job/folder và một mẫu build record xuất hiện như inventory mong đợi;
• credential metadata có mặt nhưng không xem/in/tiết lộ credential value;
• một Pipeline vô hại chỉ thực hiện echo trên agent sandbox chạy thành công;
• checksum, backup ID, thời gian restore thực tế và người xác nhận được ghi vào biên bản;
• kiểm tra DNS/URL, webhook và agent endpoint không chạm production.

Không cần dùng credential thật để chứng minh khả năng restore. Nếu policy cho phép kiểm tra credential, chỉ kiểm tra qua quy trình nội bộ có ủy quyền và không làm lộ giá trị vào console log.

Lab local sandboxCopy Anchor Link

Lab này minh họa chuỗi backup → restore → verify bằng dữ liệu giả. Nó không dùng Docker volume thật, không cần Jenkins đang chạy và cleanup chỉ xóa thư mục do lab tự tạo dưới ${TMPDIR:-/tmp}.

LAB_ROOT="${TMPDIR:-/tmp}/jenkins-backup-lab-$USER"
mkdir -p "$LAB_ROOT/source/jobs/demo/builds/1" "$LAB_ROOT/source/plugins" "$LAB_ROOT/source/secrets" "$LAB_ROOT/restore"
printf '<project/>\n' > "$LAB_ROOT/source/jobs/demo/config.xml"
printf 'lab build record\n' > "$LAB_ROOT/source/jobs/demo/builds/1/log"
printf 'lab plugin marker\n' > "$LAB_ROOT/source/plugins/example.jpi"
printf 'lab key marker; not a real secret\n' > "$LAB_ROOT/source/secrets/master.key"
printf 'Jenkins-Version: <lab-version>\n' > "$LAB_ROOT/source/backup-manifest.txt"

tar --create --file "$LAB_ROOT/jenkins-home-lab.tar" -C "$LAB_ROOT/source" .
sha256sum "$LAB_ROOT/jenkins-home-lab.tar" > "$LAB_ROOT/jenkins-home-lab.tar.sha256"
sha256sum --check "$LAB_ROOT/jenkins-home-lab.tar.sha256"

tar --extract --file "$LAB_ROOT/jenkins-home-lab.tar" -C "$LAB_ROOT/restore"
test -f "$LAB_ROOT/restore/jobs/demo/config.xml"
test -f "$LAB_ROOT/restore/secrets/master.key"
printf 'restore verification: PASS\n'

case "$LAB_ROOT" in
  "${TMPDIR:-/tmp}"/jenkins-backup-lab-*) rm -rf -- "$LAB_ROOT" ;;
  *) printf 'Refuse cleanup outside lab: %s\n' "$LAB_ROOT" ;;
esac

Khắc phục sự cốCopy Anchor Link

Checklist vận hànhCopy Anchor Link

• Đã xác định JENKINS_HOME, artifact backend, plugin inventory, owner, RPO và RTO.
• Scope gồm cấu hình, job, build record cần giữ, plugin, credential metadata đã mã hóa và secrets/ cùng generation.
• Cache, temp, agent workspace và dữ liệu tái tạo được có policy riêng, không bị sao lưu mù.
• Điểm backup được tạo sau quiet down + stop hoặc snapshot application-consistent đã kiểm chứng.
• Archive được mã hóa, giữ offsite, có retention, IAM tối thiểu, checksum và chain of custody.
• Restore drill diễn ra trên controller cô lập với version, Java, quyền file và plugin inventory tương thích.
• DNS/URL, webhook, agent và artifact endpoint của sandbox không chạm production.
• Biên bản drill ghi thời gian thực tế, pass/fail, sai lệch RPO/RTO và hành động khắc phục.

Tài liệu liên quanCopy Anchor Link

Nguồn chính thứcCopy Anchor Link

• Jenkins: Backing up
• Jenkins: Managing Jenkins
• Jenkins: Using credentials
• Jenkins: Security
• Jenkins: Plugins