Cấu hình hệ thống Jenkins

Cấu hình ở Manage Jenkins quyết định cách controller tự nhận diện, xếp lịch và tích hợp với hệ thống bên ngoài. Vì nó ảnh hưởng nhiều job cùng lúc, mỗi thay đổi global cần có owner, review, dấu vết và đường quay lui; đây không phải nơi sửa nhanh để một Pipeline tạm thời chạy được.

Mục lụcCopy Anchor Link

• Ranh giới và bản đồ cấu hình
  • Controller setting không phải Pipeline hoặc agent setting
  • Bảng scope và thời điểm áp dụng
• Global settings trong Manage Jenkins
  • Jenkins URL location và timezone
  • Quiet period executors và markup formatter
  • Email và proxy
• Global Tools chạy ở đâu
  • Đăng ký tool và installer
  • Pin version checksum và provenance
• Environment properties và system properties
  • Phân biệt ba loại giá trị
  • Precedence và thời điểm thay đổi có hiệu lực
  • Secret không thuộc global environment
• Configuration ownership và thay đổi có kiểm soát
  • Owner review audit và backup
  • UI as code plugin và drift
  • Change window và rollback an toàn
• Ví dụ cấu hình và Jenkinsfile an toàn
• Lab sandbox: quan sát một thay đổi global
  • Điều kiện lab
  • Các bước thực hiện
    • Ghi baseline và chọn một thay đổi vô hại
    • Lưu Global property và xác minh scope
    • Quan sát controller queue và agent
    • Dọn sạch và ghi nhận
  • Kết quả mong đợi
• Troubleshooting
• Checklist vận hành
• Nguồn Jenkins chính thức
• Đọc tiếp

Ranh giới và bản đồ cấu hìnhCopy Anchor Link

Trong giao diện Jenkins, Manage Jenkins → System chứa các thiết lập instance và một số Global properties. Manage Jenkins → Tools (tên có thể là Global Tool Configuration ở UI cũ) đăng ký toolchain dùng chung. Các trang này thay đổi cấu hình controller trong JENKINS_HOME, không sửa source của một repository.

Đường đi của một giá trị cần được hiểu trước khi đổi nó:

direction: down
owner: Quản trị viên / configuration repository
config: "Manage Jenkins\nSystem / Tools hoặc JCasC"
controller: "Controller\nqueue, URL, proxy/email"
agent: "Agent\ntool đã khai báo + build env"
file: "Jenkinsfile\nscope stage/block riêng"
owner -> config: Review và phê duyệt
config -> controller: Lưu cấu hình instance
controller -> agent: Cấp build cho node phù hợp
agent -> file

Mô hình controller, queue và agent được giải thích kỹ hơn tại Kiến trúc Jenkins. Thay đổi global có blast radius lớn hơn một Jenkinsfile: một URL sai có thể làm hỏng link email và webhook; một proxy sai có thể chặn cập nhật plugin hoặc SCM; một executor sai có thể làm controller quá tải.

Controller setting không phải Pipeline hoặc agent settingCopy Anchor Link

Một vấn đề hay gặp là đặt giá trị ở global scope vì nó khiến một job hết lỗi, rồi vô tình đổi hành vi của mọi job khác. Hãy đặt giá trị tại scope hẹp nhất giải quyết đúng vấn đề.

Tài liệu Tổng quan Jenkins Pipeline, Environment & Parameters và Chọn agent cho Pipeline mô tả các scope nằm ở phía Pipeline/agent. Một global setting không thay thế permission, network policy hay credential scope.

Bảng scope và thời điểm áp dụngCopy Anchor Link

Các plugin có thể thêm field, thay đổi nhãn UI hoặc có lifecycle riêng. Vì vậy, bảng này là bản đồ vận hành, không phải lời hứa rằng một plugin cụ thể sẽ reload nóng.

Global settings trong Manage JenkinsCopy Anchor Link

Jenkins URL location và timezoneCopy Anchor Link

Jenkins URL là URL chuẩn mà Jenkins dùng khi tạo absolute link trong email, thông báo, callback và một số integration. Đặt nó thành URL người dùng và hệ thống bên ngoài thực sự đi tới, gồm HTTPS hostname và context path nếu có, ví dụ https://ci.example.test/jenkins/. Không dùng http://localhost:8080/ cho instance sau reverse proxy chỉ vì quản trị viên đang mở UI từ host đó.

Trước khi lưu URL mới, xác minh theo thứ tự:

1. DNS, certificate và reverse proxy đã phục vụ URL đích.
2. Host, scheme và context path được proxy chuyển tiếp đúng.
3. Một user đăng nhập qua URL đích mà không redirect loop.
4. Một build sandbox sinh link và một webhook/integration không tác động được kiểm tra lại.

Thông tin instance như System Admin e-mail address thuộc cùng vùng location. Dùng mailbox nhóm có owner và quy trình tiếp nhận, không dùng địa chỉ cá nhân đã nghỉ việc. Hướng dẫn thiết lập URL lần đầu nằm tại Thiết lập ban đầu.

Timezone cần được quyết định nhất quán, không sửa ngẫu nhiên để “chữa” một cron. Thực hành dễ kiểm toán là dùng UTC cho host, controller và log; sau đó chọn timezone hiển thị hoặc lịch theo chính sách nhóm nếu cần. Đồng bộ clock bằng NTP trên controller, reverse proxy và agent. Nếu một plugin hoặc JVM cần -Duser.timezone=..., coi đó là thay đổi process: kiểm thử timestamp, lịch trigger và log trên staging rồi restart trong change window.

Quiet period executors và markup formatterCopy Anchor Link

Quiet period là khoảng Jenkins chờ trước khi đưa một trigger vào queue. Nó có thể giúp gộp các thay đổi liên tiếp hoặc giảm build dư thừa, nhưng kéo dài thời gian phản hồi CI. Đặt một giá trị có lý do đo được; nếu repository cần hành vi khác, ưu tiên cấu hình job/Pipeline hẹp hơn thay vì ép mọi workload nhận cùng độ trễ. Khi build “chậm bắt đầu”, phân biệt quiet period với queue: quiet period chưa đến giai đoạn xin executor, còn queue sẽ hiển thị lý do không có agent phù hợp.

Number of executors của controller/built-in node là giới hạn build chạy tại controller. Trên production, đặt 0; thêm/tuning executor phải xảy ra trên agent pool sau khi đo CPU, RAM, I/O, disk và queue theo label. Executor không phải CPU core. Xem Tổng quan Jenkins Agent để chọn capacity và cô lập workload.

Markup Formatter quyết định cách Jenkins hiển thị text do người dùng nhập, ví dụ description. Giữ formatter an toàn/mặc định trừ khi có use case được review. Cho phép HTML hoặc markup mạnh hơn có thể biến nội dung job/build do người dùng kiểm soát thành bề mặt XSS. Thử rendering bằng nội dung vô hại trong sandbox, đọc tài liệu plugin/formatter tương ứng và đánh giá quyền người có thể sửa description trước khi nới policy.

Email và proxyCopy Anchor Link

Cấu hình email thường nằm trong Manage Jenkins → System; plugin cung cấp notification nâng cao có thể thêm một block khác. Đặt SMTP host, port, TLS/CA, sender và recipient policy theo hạ tầng mail đã phê duyệt. Dùng một mailbox gửi có ownership, giới hạn relay và credential scope tối thiểu. Không đặt SMTP password vào một ô global environment, Jenkinsfile hoặc command line; dùng Jenkins Credentials hay secret manager theo plugin/khả năng đã được duyệt.

Trước khi bật email cho mọi job, gửi một test vô hại đến mailbox lab. Xác minh sender, URL trong mail, TLS, relay policy và việc log không in credential. Nếu cấu hình thuộc plugin, ghi rõ plugin/version là một phần của change; Jenkins core không bảo đảm cùng behavior cho mọi plugin email.

Proxy controller quyết định các outbound request của chính controller, chẳng hạn Update Center hoặc endpoint mà plugin dùng. Nó không tự cấu hình proxy cho agent: agent/container chạy git, npm, Maven hoặc tool installer có thể cần egress/proxy/CA riêng theo pool của chúng. Cấu hình NO_PROXY cho hostname nội bộ cần đi thẳng; không giải quyết lỗi certificate bằng cách tắt TLS verification hoặc dùng curl -k.

Global Tools chạy ở đâuCopy Anchor Link

Đăng ký tool và installerCopy Anchor Link

Tại Manage Jenkins → Tools, Jenkins có thể đăng ký tên và version cho JDK, Maven, Gradle, NodeJS hoặc tool do plugin cung cấp. Tool definition là một contract đặt tên để job/Pipeline yêu cầu tool; nó không chứng minh mọi agent có tool đó, cũng không biến tool thành capability của controller.

Một tool có thể được cung cấp bằng ba cách:

Khi Pipeline dùng directive tools, Jenkins resolve tool cho node/agent được cấp build. Installer, nếu được chọn, cần download/cài vào agent đó và phụ thuộc OS, network, filesystem, plugin và permission của agent. Đừng “cài trước” JDK/Maven/Gradle/Node lên controller để tránh lỗi agent. Controller chỉ cần Java runtime tương thích để chạy Jenkins; JDK compile ứng dụng là nhu cầu của agent. Các yêu cầu Java và ranh giới controller–agent nằm tại Yêu cầu hệ thống.

Pin version checksum và provenanceCopy Anchor Link

Tên như jdk-latest hoặc node-current không tái lập được: cùng Jenkinsfile có thể chạy binary khác sau lần installer tải mới. Dùng tên có version rõ ràng, chẳng hạn temurin-21.0.6, maven-3.9.9, gradle-8.12.1 hoặc node-22.14.0; cập nhật tên/version qua review thay vì thay nội dung sau một alias chung.

Mỗi tool change nên trả lời được các câu hỏi sau:

• Version nào? Pin exact release; với container pin thêm immutable digest đã kiểm thử.
• Nó đến từ đâu? Lưu URL vendor/registry nội bộ, artifact repository và provenance/SBOM hoặc signature policy nếu tổ chức có.
• Có nguyên vẹn không? Đối chiếu SHA-256, chữ ký hoặc checksum chính thức khi cơ chế installer/artifact repository hỗ trợ; không tự bịa checksum trong cấu hình.
• Ai đã duyệt và thử? Ghi Jenkins core, plugin, OS/architecture agent, test build và ngày review.
• Rollback thế nào? Giữ tool/image trước đó còn khả dụng, tool definition cũ và artifact cache/proxy có thể phục hồi.

Checksum xác nhận bytes khớp giá trị tin cậy; provenance trả lời artifact được tạo/phát hành từ nguồn nào và qua chuỗi kiểm soát nào. Cả hai không thay thế việc quét lỗ hổng, license review và giới hạn quyền agent.

Environment properties và system propertiesCopy Anchor Link

Phân biệt ba loại giá trịCopy Anchor Link

Cụm từ “property” dễ gây nhầm lẫn. Ba loại dưới đây có consumer, scope và cách rollout khác nhau:

Global environment property không phải System.getProperty() của JVM Jenkins. Ngược lại, -D property không tự xuất hiện trong shell của Pipeline. Một plugin có thể đọc environment hoặc Java property riêng; luôn đọc tài liệu chính thức của plugin/core đang dùng thay vì đổi tên một biến với hy vọng nó có hiệu lực.

Precedence và thời điểm thay đổi có hiệu lựcCopy Anchor Link

Không tồn tại một precedence phổ quát cho mọi property Jenkins. Process environment, Java -D, Global properties, node properties, Declarative environment, withEnv, container image và plugin đều có consumer riêng. Khi một giá trị logic cần có ở nhiều lớp, coi đó là xung đột thiết kế cần loại bỏ, không phải mẹo precedence.

Với environment mà một sh thực sự nhận, scope gần build thường che scope ngoài: withEnv trong block che stage-level environment, stage-level che pipeline-level, và các giá trị đó chỉ áp dụng khi Pipeline chạy. Tuy nhiên, params.NAME là namespace khác env.NAME; một parameter cùng tên không tự ghi đè environment. Xem bảng precedence và ví dụ cụ thể tại Environment & Parameters.

Đừng restart production chỉ để thử giá trị. Đầu tiên xác minh consumer, chuẩn bị rollback và test trên controller/agent sandbox tương đương. Với service Linux, dùng systemctl edit jenkins để tạo drop-in thay vì sửa vendor unit; với container, thay manifest/image được version hóa. Quy trình cài đặt deployment tương ứng nằm tại Cài Jenkins trên Linux và Chạy Jenkins với Docker.

Secret không thuộc global environmentCopy Anchor Link

Global environment dễ bị nhiều job, process con, diagnostic command, plugin và log kế thừa. Vì thế nó không phải kho credential. Không đặt password SMTP, API token, private key, kubeconfig, connection string nhạy cảm hay bootstrap secret vào Global properties, systemd Environment=, Compose environment: hoặc JCasC trong Git thường.

Dùng Jenkins Credentials hoặc secret manager đã được tổ chức phê duyệt, cấp scope folder/job nhỏ nhất và bind trong stage/block ngắn nhất. Không in secret, dump env, bật set -x, archive file binding hoặc giả định masking là boundary bảo mật. Nếu secret từng xuất hiện trong log/artifact/config repository, thu hồi hoặc rotate theo incident process; xóa một dòng log không thu hồi bản sao đã bị đọc.

Configuration ownership và thay đổi có kiểm soátCopy Anchor Link

Owner review audit và backupCopy Anchor Link

Mỗi nhóm cấu hình global cần một owner rõ ràng, backup và audit trail. “Mọi admin đều có thể sửa” không phải ownership: khi proxy sai hoặc một tool bị compromise, đội cần biết ai đánh giá, ai triển khai và ai có quyền rollback.

Trước change production, tạo backup nhất quán của JENKINS_HOME và xác minh cách khôi phục. Backup chứa configuration, credential đã mã hóa và key liên quan nên phải được mã hóa, giới hạn quyền đọc và lưu tách failure domain. Không coi export UI, screenshot hay Git repo JCasC là thay thế duy nhất cho backup. Giữ change record liên kết với ticket, commit, approver, thời gian thực hiện, config/plugin version và kết quả xác minh.

UI as code plugin và driftCopy Anchor Link

UI phù hợp cho discovery, lab nhỏ hoặc thay đổi khẩn cấp được phê duyệt. Configuration as Code (JCasC) hoặc infrastructure configuration phù hợp khi tổ chức cần reviewable diff, tái lập controller và đồng bộ nhiều instance. Hai cách chỉ an toàn khi có một source of truth và quy trình hòa giải rõ ràng.

Ví dụ JCasC tối giản dưới đây chỉ minh họa intent không nhạy cảm. Nó giả định plugin Configuration as Code đã được cài, version tương thích và schema export của instance đã được xác minh; không dán nó vào production như một manifest hoàn chỉnh.

jenkins:
  systemMessage: "Managed configuration; changes require review."
  globalNodeProperties:
    - envVars:
        env:
          - key: "ORG_BUILD_TZ"
            value: "UTC"

unclassified:
  location:
    url: "https://ci.example.test/"

Không ghi secret vào ví dụ JCasC. Tên field của plugin, tool installer, email publisher và cloud configuration có thể khác theo plugin/version; dùng export/schema/linter của chính instance sandbox và quản lý plugin lock/bundle theo policy. JCasC không tự version pin plugin, không cài tool trên agent và không thay backup/rollback.

Configuration drift xảy ra khi trạng thái chạy khác source of truth, ví dụ một admin sửa proxy hoặc tool qua UI sau lần apply JCasC. Phát hiện drift bằng export/compare định kỳ, kiểm tra change audit và đối chiếu tool/image/version trên agent. Không tự động overwrite production chỉ vì diff xuất hiện: trước tiên phân loại diff là thay đổi khẩn cấp hợp lệ, lỗi apply, thay đổi plugin schema hay sửa ngoài quy trình; sau đó đưa trạng thái được chấp thuận trở lại source of truth.

Change window và rollback an toànCopy Anchor Link

Một change window tốt giảm rủi ro chứ không chỉ là một lịch calendar. Với thay đổi URL, proxy, tool, JVM property hoặc plugin, chuẩn bị theo thứ tự:

1. Đánh giá phạm vi. Liệt kê job, agent label, webhook, email, plugin và integration có thể bị ảnh hưởng. Đọc queue và build đang chạy; đừng restart giữa release chưa đánh giá.
2. Review và chuẩn bị. Có diff/export trước change, version Jenkins/Java/plugin, backup đã xác minh, owner/on-call và tiêu chí thành công/thất bại.
3. Thử ở sandbox/staging. Dùng URL/mailbox/repository không tác động và agent tách biệt. Xác nhận plugin/installer assumptions thay vì suy ra từ tài liệu chung.
4. Triển khai nhỏ nhất. Một thay đổi logic mỗi lần khi có thể. Không đồng thời nâng Jenkins, toàn bộ plugin, proxy và JDK rồi kỳ vọng điều tra được lỗi.
5. Xác minh. Kiểm tra login/URL, controller health, queue, agent online, tool --version, một Pipeline sandbox và integration liên quan.
6. Rollback hoặc kết thúc. Nếu tiêu chí thất bại, dừng rollout, trả cấu hình/version đã biết tốt hoặc restore vào bản sao cô lập theo runbook. Ghi kết quả và drift còn lại.

Rollback an toàn không phải luôn là “đổi một field về giá trị cũ”. Core/plugin mới có thể đã migrate state, tool cache mới có thể đã bị sử dụng, và restore JENKINS_HOME cần key/credential material tương ứng. Không chạy đồng thời hai controller ghi vào cùng một JENKINS_HOME. Khi cần khôi phục, ưu tiên restore sang home/volume mới cô lập, smoke test trước rồi mới chuyển integration theo runbook của tổ chức.

Ví dụ cấu hình và Jenkinsfile an toànCopy Anchor Link

Ví dụ này dùng một tool name có version rõ và chỉ in version tool trên agent. Nó giả định Declarative Pipeline, các tool temurin-21.0.6 và maven-3.9.9 đã được định nghĩa trong Manage Jenkins → Tools, agent Linux có label linux-ci, và plugin/tool installer cần thiết đã được kiểm thử. Nó không checkout, không dùng credential, không tải tool từ URL tùy ý và không chạy trên controller.

pipeline {
  agent none

  options {
    skipDefaultCheckout(true)
    timeout(time: 3, unit: 'MINUTES')
  }

  stages {
    stage('Xác minh toolchain trên agent') {
      agent { label 'linux-ci' }

      tools {
        jdk 'temurin-21.0.6'
        maven 'maven-3.9.9'
      }

      environment {
        ORG_BUILD_TZ = 'UTC'
      }

      steps {
        sh '''
          set -eu
          printf 'node=%s\\n' "$NODE_NAME"
          printf 'timezone-policy=%s\\n' "$ORG_BUILD_TZ"
          java -version
          mvn --version
        '''
      }
    }
  }
}

tools làm tool name thành contract được review; nó không có nghĩa mọi agent đều có cùng filesystem/cache. Stage environment giữ policy không nhạy cảm cục bộ; nó không thay global property và không biến UTC thành timezone JVM. Nếu tool cần installer, kiểm tra log của build để biết installer chạy trên agent nào và chỉ chấp nhận download từ nguồn/version đã được phê duyệt.

Lab sandbox: quan sát một thay đổi globalCopy Anchor Link

Điều kiện labCopy Anchor Link

Lab dùng controller học tập hoặc sandbox, không phải Jenkins production. Cần quyền cấu hình System trên sandbox, một agent Linux riêng có label linux-ci, một mailbox test nếu bạn thử email, và quyền tạo Pipeline job. Built-in node/controller vẫn để 0 executor. Chuẩn bị controller theo Chạy Jenkins với Docker hoặc Cài Jenkins trên Linux nếu cần.

Không dùng credential thật, endpoint production, agent release hay tool installer từ nguồn chưa duyệt. Nếu không có Global Tool definition tương ứng, chỉ làm phần Global property và Pipeline metadata; không cài tool lên controller để tiếp tục lab.

Các bước thực hiệnCopy Anchor Link

pipeline {
  agent { label 'linux-ci' }

  options {
    skipDefaultCheckout(true)
  }

  stages {
    stage('Đọc property không nhạy cảm') {
      steps {
        sh '''
          set -eu
          test "$LAB_CONFIG_MARKER" = "system-config-lab"
          printf 'marker=%s node=%s\\n' "$LAB_CONFIG_MARKER" "$NODE_NAME"
        '''
      }
    }
  }
}

Kết quả mong đợiCopy Anchor Link

Lab chứng minh scope và lifecycle của một global environment property, không chứng minh email, proxy, JCasC hay installer production hoạt động. Mỗi khả năng đó cần test riêng với owner và change window của nó.

TroubleshootingCopy Anchor Link

Khi một thay đổi có thể tác động login, agent, credential hay nhiều repository, dừng ở bằng chứng đầu tiên thay vì tiếp tục đổi thêm fields. Một diff nhỏ có thể cần rollback nhanh hơn một chuỗi thử-sai dài.

Checklist vận hànhCopy Anchor Link

• Jenkins URL khớp HTTPS hostname và context path thực tế; login, link/email và callback sandbox đã được thử sau thay đổi.
• Clock/NTP và timezone được quyết định tách biệt với URL; thay đổi JVM timezone có restart plan và test lịch/log.
• Quiet period có mục đích đo được; vấn đề queue được điều tra theo label/executor thay vì tăng controller executor.
• Built-in node/controller có 0 executors trên production; workload ở agent có toolchain và trust boundary phù hợp.
• Markup formatter, email và proxy được review về XSS, credential, TLS/CA, plugin và phạm vi controller/agent.
• JDK/Maven/Gradle/Node và tool installer có tên pin version; nguồn, digest/checksum/provenance, plugin và agent OS đã được ghi nhận.
• Không cài mù tool trên controller; tool được xác minh bằng --version trên đúng agent/pool.
• Global environment chỉ chứa cấu hình không nhạy cảm, có owner/mục đích/expiry; secret ở Credentials hoặc secret manager với scope hẹp.
• Service environment và JVM -D property được quản lý bằng manifest/unit, có restart/recreate trong change window và smoke test.
• UI và configuration as code có source of truth, review, export/compare phát hiện drift; plugin/schema assumptions đã được xác minh.
• Backup JENKINS_HOME, version/config export và rollback path đã sẵn sàng trước thay đổi high-impact; không chạy hai controller ghi cùng home.
• Lab sandbox đã chứng minh Global property trên agent và được cleanup mà không chạm production settings.

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

• System Configuration — Jenkins URL, global properties, proxy và cấu hình hệ thống.
• Managing systemd Services — quản lý service và JVM options trên Linux.
• Managing Nodes — node, executor, agent properties và capacity.
• Using Jenkins Agents — phân tách controller và agent.
• Using a Jenkinsfile — tools, environment và scope Pipeline.
• Pipeline Syntax — Declarative tools, environment và agent.
• Using Credentials — credential store, scope và thực hành an toàn.
• Configuration as Code plugin — metadata plugin và link tài liệu JCasC hiện hành.
• Jenkins Plugins — kiểm tra yêu cầu, version và security advisory của plugin.
• Jenkins Security — bảo vệ controller, quyền và bề mặt tấn công.

Đọc tiếpCopy Anchor Link