Permanent Agents

Permanent agent là node có host và cấu hình được giữ lâu dài để phục vụ một pool workload ổn định, ví dụ build cần hardware, toolchain hoặc cache chuyên biệt. Nó giảm thời gian provision, nhưng đổi lại đội vận hành phải chủ động quản lý capacity, dữ liệu tồn lưu, vá lỗi và vòng đời của máy.

Mục lụcCopy Anchor Link

• Khi nào dùng permanent agent
  • Permanent không đồng nghĩa với launcher
  • Giới hạn và ranh giới tin cậy
• Mô hình node, queue và lifecycle
• Cấu hình node trong Jenkins
  • Node configuration
  • Labels và executors
  • Remote root directory
• Launcher và kết nối
  • Inbound agent và WebSocket
  • SSH launcher và các giả định plugin
  • Phân biệt Jenkins core, UI và plugin
• Toolchain, filesystem và workspace
  • Quyền tối thiểu và ownership
  • Chuẩn hóa toolchain và dọn dữ liệu
• Retention, maintenance và không gián đoạn build
  • Chọn retention strategy
  • Drain, temporarily offline và maintenance mode
  • Reconnect và trở lại phục vụ
• Capacity, isolation và bảo mật
  • Sizing pool ổn định
  • Controller và security boundary
  • Credential, secret và pull request fork
  • Patching và ownership vận hành
• Jenkinsfile mẫu an toàn
• Lab sandbox: tạo và drain một permanent agent
  • Điều kiện lab
  • Các bước thực hiện
  • Kết quả mong đợi
• Troubleshooting
• Checklist vận hành
• Nguồn Jenkins chính thức
• Đọc tiếp

Khi nào dùng permanent agentCopy Anchor Link

Chọn permanent/static agent khi số lượng workload tương đối dự đoán được và môi trường chạy cần tồn tại lâu: máy Windows có Visual Studio đã chuẩn hóa, runner có GPU, thiết bị phần cứng, hoặc một toolchain lớn mà provision lại cho mọi build quá tốn thời gian. Node vẫn xuất hiện trong Jenkins khi tiến trình agent tạm mất kết nối; vì vậy cần theo dõi cả node configuration lẫn trạng thái kết nối của agent.

Nếu workload tăng giảm mạnh, cần môi trường mới sau mỗi build, hoặc nhận code không tin cậy từ nhiều tenant, agent dynamic/ephemeral thường là lựa chọn cô lập dễ hơn. Nền tảng controller, queue, executor và workspace được giới thiệu tại Tổng quan Jenkins và Kiến trúc Jenkins.

Permanent không đồng nghĩa với launcherCopy Anchor Link

Permanent mô tả lifecycle hạ tầng: host và node được giữ lại sau build. Inbound, SSH hoặc WebSocket mô tả cách tiến trình agent được khởi chạy/kết nối. Do đó một máy có thể là permanent + inbound, hoặc permanent + SSH-launched.

Giới hạn và ranh giới tin cậyCopy Anchor Link

Static agent không phải security boundary. Jenkinsfile, source, dependency và lệnh build có thể chạy dưới identity của agent. Hai job có workspace khác tên nhưng cùng user OS vẫn có thể để lại cache, process hoặc file mà job khác tác động được. Labels chỉ giúp scheduler route build; chúng không phải ACL.

Mô hình node, queue và lifecycleCopy Anchor Link

direction: right
config: "Node config\nlabels, root, executors, launcher"
controller: Controller điều phối
queue: Build Queue
agent: "Permanent agent\nexecutor → workspace\ntoolchain + service user"
config -> agent
controller -> queue
queue -> agent: Có node phù hợp
queue -> queue: Không có node phù hợp
agent -> controller: Log/trạng thái

Một build chỉ rời queue khi controller tìm được node Online, thỏa label expression và còn executor trống. Sau khi executor được cấp, agent tạo hoặc chọn workspace dưới remote root, chạy step rồi trả executor. Offline, temporarily offline hoặc agent mất kết nối đều làm capacity của node không còn dùng được cho allocation mới.

Để tránh controller vừa điều phối vừa chạy code build, cấu hình built-in node/controller với numExecutors: 0 trong production:

jenkins:
  numExecutors: 0

Giá trị này không tắt controller hoặc queue. Nó chỉ ngăn controller nhận build executor; job chưa có label phù hợp sẽ ở queue và phải được route đến pool agent đúng loại.

Cấu hình node trong JenkinsCopy Anchor Link

Tại Manage Jenkins → Nodes, tạo node permanent và mở Configure. Tên trường và các lựa chọn UI có thể chênh lệch nhẹ giữa Jenkins LTS; ý nghĩa vận hành dưới đây quan trọng hơn việc sao chép một ảnh chụp UI cũ.

Node configurationCopy Anchor Link

Cấu hình node là một contract: người quản lý node xác nhận toolchain, labels, root directory, executor và launcher phản ánh máy thật. Người viết Pipeline phải yêu cầu đúng contract thay vì dùng agent any để bỏ qua lỗi thiếu môi trường.

Labels và executorsCopy Anchor Link

Labels nên mô tả capability có thể kiểm chứng, chẳng hạn linux, java21, android, ci-sandbox hoặc trusted-release. Một Jenkinsfile yêu cầu linux && java21 && ci-sandbox chỉ được chạy ở node có đủ ba labels. Tên host hoặc self-label chỉ phù hợp khi thật sự cần một thiết bị duy nhất; nó làm pool mất khả năng thay thế khi máy offline.

Number of executors là giới hạn scheduler, không thêm CPU, RAM, IOPS, Docker daemon hay license. Ví dụ một agent 4 vCPU có 4 executors có thể vẫn OOM hoặc nghẽn disk khi bốn build Gradle chạy cùng lúc. Đo CPU, RAM, I/O wait, disk/inode, queue time và thời lượng build trước khi tăng. Hướng dẫn sâu về biểu thức label, queue và sizing có tại Labels & Executors.

Remote root directoryCopy Anchor Link

Remote root phải là đường dẫn tuyệt đối trên chính agent, không phải đường dẫn trên controller, URL hoặc relative path. Ví dụ an toàn theo hệ điều hành:

Jenkins/Remoting dùng root này cho file agent và thường đặt workspace bên dưới nó. Đường dẫn cần tồn tại hoặc có thể được tạo bởi account chạy agent, có dung lượng/inode đủ và không trỏ vào JENKINS_HOME của controller. Tránh dùng home directory cá nhân, ổ mạng không được kiểm thử locking/latency, hoặc một root chung ghi được giữa trust tier.

Khi nhiều build chạy song song, Jenkins có thể dùng workspace có hậu tố để tránh đụng tên. Điều đó không ngăn một process cùng user đọc thư mục khác. Thiết kế quyền filesystem, user/VM/container riêng và cleanup mới là kiểm soát isolation thực sự.

Launcher và kết nốiCopy Anchor Link

Launcher quyết định agent process xuất hiện và kết nối, không biến host thành một agent an toàn. Trước khi chọn, kiểm tra Java version tương thích, DNS, HTTPS/TLS, firewall, proxy và hướng network flow. Baseline runtime và network xem tại Yêu cầu hệ thống.

Inbound agent và WebSocketCopy Anchor Link

Với inbound, agent chủ động kết nối tới controller. Trong trang cấu hình node, Jenkins hiển thị lệnh/URL phù hợp cho node đó; dùng chính hướng dẫn từ controller lab, lưu agent secret trong secret store hoặc cấu hình service có quyền đọc giới hạn, và không chép secret vào Jenkinsfile, history hoặc console log.

WebSocket đi qua HTTP(S), nên thường chỉ cần agent ra được URL controller qua 443 khi reverse proxy hỗ trợ WebSocket. Inbound TCP dùng cổng agent riêng đã được controller cấu hình; chỉ mở cổng đó từ mạng agent cần thiết. Cả hai đều cần xác minh controller URL và TLS từ agent trước khi coi lỗi là lỗi Jenkins.

Đối với permanent inbound agent, chạy process bằng service manager với user chuyên dụng và chính sách restart có giới hạn. Restart loop không phải health check: nó có thể che DNS/TLS sai, Java không tương thích, disk đầy hoặc controller quá tải.

SSH launcher và các giả định pluginCopy Anchor Link

SSH-launched agent yêu cầu controller đi đến agent qua SSH. Đây là lựa chọn phù hợp khi controller được phép chủ động vào host và host được quản trị tập trung. Không tắt host-key verification để “cho kết nối được”; lưu và đối chiếu host key theo policy, dùng account SSH chuyên biệt, giới hạn lệnh/quyền và chỉ cấp quyền ghi remote root cần thiết.

SSH launch thường cần plugin launcher, ví dụ SSH Build Agents Plugin. Plugin, version, credential type, Java location và implementation launcher không phải lời hứa cố định của Jenkins core. Kiểm tra plugin đã cài, advisory, compatibility với Jenkins LTS và snippet/UI của chính controller trước khi áp dụng.

Phân biệt Jenkins core, UI và pluginCopy Anchor Link

Nói ngắn gọn: Jenkins core điều phối node và executor; plugin/launcher cùng hạ tầng mới cung cấp chi tiết transport hoặc provision. Không khẳng định một lựa chọn có mặt chỉ vì nó xuất hiện trong bài viết của phiên bản Jenkins khác.

Toolchain, filesystem và workspaceCopy Anchor Link

Permanent agent có lợi thế toolchain luôn sẵn, nhưng cũng tích lũy drift. Ghi version Java, compiler, package manager, browser, SDK và image/runtime cần thiết trong inventory hoặc cấu hình được review. Cài tool qua image/baseline cấu hình có version rõ ràng; không để mỗi Pipeline curl | sh vào host để tự chữa thiếu dependency.

Quyền tối thiểu và ownershipCopy Anchor Link

Tạo service account riêng cho agent, chỉ có quyền đọc/chạy toolchain và quyền tạo/sửa/xóa trong remote root cùng các cache đã được phê duyệt. Account đó không cần Administrator/root mặc định, không nên dùng account cá nhân và không cần quyền ghi JENKINS_HOME của controller.

Chuẩn hóa toolchain và dọn dữ liệuCopy Anchor Link

Workspace có thể tồn tại sau build. Dọn checkout, file tạm và cache theo policy, đặc biệt trước khi đổi trust tier hoặc đưa node trở lại sau một incident. Có thể giữ cache có chủ đích để giảm thời gian build, nhưng cache cần owner, quota, key phân vùng và cơ chế loại bỏ dữ liệu cũ.

Stage chạy trên agent khác không được giả định thấy cùng filesystem. Hãy checkout lại hoặc truyền artifact qua cơ chế được thiết kế. Cú pháp route stage/Pipeline và lifecycle workspace xem tại Chọn agent cho Pipeline và Declarative Pipeline.

Retention, maintenance và không gián đoạn buildCopy Anchor Link

Chọn retention strategyCopy Anchor Link

Tên chính xác của mục Availability thay đổi theo Jenkins LTS, launcher và plugin, nhưng các policy thường tương đương bảng sau. Xác nhận UI và help text trên controller trước khi đặt cho production.

Retention điều khiển sự sẵn sàng cho allocation mới, không thay thế autoscaling hay khôi phục host. Với static inbound agent, always thường cần một service supervisor trên agent để process khởi động sau reboot và reconnect. Với SSH launch, khả năng start/reconnect phụ thuộc plugin, SSH account và host còn hoạt động. Thử policy trong sandbox với đúng Jenkins/plugin version trước khi tin vào nó.

Drain, temporarily offline và maintenance modeCopy Anchor Link

Trong Jenkins core, temporarily offline là tín hiệu không nhận allocation mới kèm lý do cho operator. Nó là công cụ gần nhất để bắt đầu drain, nhưng Jenkins không có một lời hứa portable rằng mọi build đang chạy sẽ được pause, migrate hay khôi phục tự động. Đừng restart/reboot một permanent agent chỉ vì UI đã chuyển màu.

Quy trình bảo trì ít gián đoạn:

1. Lập kế hoạch capacity. Xác nhận pool cùng label còn đủ agent/executor cho queue và thông báo maintenance window. Nếu chỉ có một node chuyên dụng, dời workload hoặc chấp nhận queue có chủ đích.
2. Drain. Mark node temporarily offline với lý do và ticket/change ID. Xác nhận build mới cần label đó vẫn vào queue hoặc được agent thay thế nhận, thay vì rơi sang controller.
3. Chờ rỗng. Theo dõi trang node, Build Queue và Console Output đến khi executor đang chạy kết thúc. Không coi “offline” là đã không còn process build.
4. Bảo trì. Dừng agent service khi không còn workload, vá OS/Java/toolchain theo change đã phê duyệt, kiểm tra disk/permissions rồi khởi động lại. Không cấp root/Administrator vô điều kiện cho Pipeline để thay việc này.
5. Canary và mở lại. Xác minh agent Online, labels/root/toolchain đúng, chạy một build sandbox vô hại rồi đưa node trở lại nhận allocation.

Nếu cần kết thúc một build đang chạy, đánh giá artifact, side effect và timeout/rollback của chính Pipeline trước. Việc disconnect hoặc mất process có thể làm durable Pipeline báo lỗi hoặc chỉ khôi phục một phần tùy step, storage và version; không xem đó là cách drain bình thường.

Reconnect và trở lại phục vụCopy Anchor Link

Sau reconnect, không lập tức tăng capacity. Kiểm tra node log, agent service log, Java version, DNS/TLS/proxy, remote root free space/inode, labels và executor count. Chạy canary chỉ in metadata/tool version trong pool an toàn. Nếu reconnect lặp lại, ghi thời điểm và mã lỗi rồi xử lý nguyên nhân như network, certificate, proxy WebSocket, resource exhaustion hoặc plugin compatibility thay vì tăng retry vô hạn.

Capacity, isolation và bảo mậtCopy Anchor Link

Sizing pool ổn địnhCopy Anchor Link

Đo capacity theo label pool, không theo tổng executors toàn Jenkins. Hai executor linux && java21 không thay được một executor windows && vs2022; executor release cũng không nên hấp thụ queue của PR.

Ví dụ, ba permanent agent cùng label linux java21 ci có hai executors mỗi máy cho tối đa sáu allocation scheduler. Nếu build Java cùng lúc tiêu thụ RAM và disk lớn, sáu chỉ là giới hạn lịch, không phải cam kết performance. Bắt đầu ít executor, đo queue p95, duration p95, CPU/RAM peak, I/O wait, disk/inode và failure rate; thêm host cùng contract trước khi nhồi thêm executor lên một host.

Controller và security boundaryCopy Anchor Link

Controller chứa cấu hình, plugin, credentials và quyền điều phối, vì vậy đặt numExecutors: 0 và không chạy code build trên built-in node. Permanent agent cũng không tự cô lập code: cùng host/user, Docker socket, privileged container, host mount hoặc quyền cloud rộng có thể biến build thành quyền trên host/hạ tầng.

Dùng VM/host/pool riêng, service identity tối thiểu, network segment/egress policy và workspace/cache partition theo trust. Container đóng gói toolchain tốt nhưng không là boundary mạnh nếu privileged, chạy root hoặc mount Docker socket/hostPath. Tài liệu vận hành controller xem tại Cài Jenkins trên Linux, Cài Jenkins trên Windows và Chạy Jenkins với Docker.

Credential, secret và pull request forkCopy Anchor Link

Masking console log chỉ giảm lộ tình cờ. Khi credential được inject, code chạy trong stage thường vẫn có thể đọc biến/file credential; agent đã bị chiếm có thể tìm workspace, cache, process hoặc metadata mà nó có quyền truy cập.

• Không hard-code token, private key hoặc password trong Jenkinsfile, node configuration text, command line, artifact hay remote root.
• Cấp credential theo folder/job/environment và scope stage nhỏ nhất; tắt shell tracing trước block dùng secret.
• PR/fork là untrusted cho đến khi policy SCM và review chứng minh khác. Chỉ chạy test sandbox không có credential deploy, registry write, kubeconfig production, Docker socket hoặc network nội bộ nhạy cảm.
• Tách trusted-release khỏi untrusted-pr bằng hạ tầng và authorization; label chỉ hỗ trợ route.
• Khi nghi lộ secret, ngừng cấp vào pool bị ảnh hưởng, thu hồi/rotate theo runbook, giữ evidence cần thiết và điều tra trước khi chạy lại.

Patching và ownership vận hànhCopy Anchor Link

Một permanent agent cần owner rõ cho host OS, Java, toolchain/image, agent service, labels, remote-root storage, capacity, credential scope và decommission. Lập inventory có node name, IP/DNS, trust tier, account service, launcher, plugin dependency, maintenance window và người chịu trách nhiệm.

Vá OS, Java, Jenkins core, plugin launcher và toolchain theo chu kỳ có kiểm thử. Cập nhật controller/plugin có thể làm launcher hoặc Java compatibility đổi; drain agent, test reconnect và chạy canary sau change. Khi retire node, drain, chờ executors rỗng, lưu audit/artifact theo retention, revoke credential/access, dọn hoặc hủy data theo policy rồi mới xóa node configuration và host.

Jenkinsfile mẫu an toànCopy Anchor Link

Mẫu Declarative này chỉ dùng agent sandbox permanent có contract rõ. Nó không checkout SCM, không dùng credential và không gọi dịch vụ production. agent none tránh giữ executor ngoài stage cần quan sát; sleep chỉ để thấy allocation trong lab.

pipeline {
  agent none

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

  stages {
    stage('Kiểm tra permanent sandbox') {
      agent { label 'linux && ci-sandbox && !trusted-release' }

      steps {
        sh '''
          set -eu
          printf 'node=%s\n' "$NODE_NAME"
          printf 'workspace=%s\n' "$WORKSPACE"
          test -n "$WORKSPACE"
          java -version
          sleep 45
        '''
      }
    }
  }
}

Không thay nhãn mẫu bằng agent any nếu lab không có node phù hợp. Thay vào đó, tạo pool sandbox đúng contract hoặc đổi ví dụ để khớp capability đã xác minh. Xem cấu trúc Pipeline tại Tổng quan Pipeline và Declarative Pipeline.

Lab sandbox: tạo và drain một permanent agentCopy Anchor Link

Lab chỉ dùng một VM/host sandbox, user thường, Java tương thích và lệnh quan sát. Không dùng controller production, repository thật, secret thật, Docker socket, privileged container hoặc network production.

Điều kiện labCopy Anchor Link

• Một Jenkins lab; built-in node có numExecutors: 0.
• Một Linux host disposable có Java tương thích, shell sh, disk trống và account service không phải root. Nếu dùng Windows, tạo agent Windows và thay sh bằng bat/PowerShell tương ứng.
• Một remote root tuyệt đối riêng, ví dụ /srv/jenkins-agent-lab, writable bởi account agent; không đặt nó dưới controller JENKINS_HOME.
• Network từ agent đến URL Jenkins lab qua HTTPS nếu dùng inbound/WebSocket. Chỉ cài plugin launcher khi đã chọn launcher đó; lab inbound không yêu cầu SSH plugin.

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

1. Trong Manage Jenkins → Nodes, tạo node permanent tên lab-permanent-linux. Đặt Number of executors là 1, Remote root directory là /srv/jenkins-agent-lab, labels là linux ci-sandbox và mô tả ghi rõ owner/lab. Chọn usage để chỉ workload khớp label sử dụng node nếu UI phiên bản hiện tại cung cấp lựa chọn này.
2. Chọn inbound launch cho lab. Từ trang node, lấy lệnh kết nối do Jenkins lab hiển thị và chạy nó bằng account agent theo cơ chế service/terminal lab được kiểm soát. Không dán agent secret vào Jenkinsfile, repository, ticket hay log. Chờ node hiển thị Online.
3. Mở trang node và xác nhận remote root, labels, một executor và Java/toolchain thực tế. Nếu agent offline, dừng ở đây và đọc node log, DNS/TLS, Java, quyền root directory trước khi tạo job.
4. Tạo Pipeline job không liên kết SCM, dán Jenkinsfile mẫu an toàn, rồi chọn Build Now. Khi log in node= và workspace=, xác nhận đường dẫn workspace nằm dưới remote root kỳ vọng.
5. Trong lúc build đầu đang sleep 45, trigger build thứ hai. Mở Build Queue: build thứ hai phải chờ vì pool khớp chỉ có một executor. Nó không được chạy trên controller.
6. Trên node, chọn Mark this node temporarily offline và ghi lý do như lab drain: verify no new allocations. Build đang chạy được để kết thúc bình thường. Trigger build thứ ba: nó phải tiếp tục chờ trong queue sau khi build thứ hai đã xong, chứng minh node không nhận allocation mới khi đang drain.
7. Sau khi executor rỗng, dừng process agent lab, kiểm tra service/log và remote root. Khởi động lại agent, chờ Online, xác minh labels/toolchain/root, rồi bỏ trạng thái temporarily offline.
8. Trigger một build canary từ Jenkinsfile trên. Kết quả xanh cùng node= và workspace= chứng minh reconnect và phục vụ trở lại. Kết thúc lab bằng cách mark offline, chờ rỗng, dừng agent và xóa node/host sandbox theo policy lab.

Kết quả mong đợiCopy Anchor Link

TroubleshootingCopy Anchor Link

Checklist vận hànhCopy Anchor Link

• Node có tên, owner, trust tier, launcher, remote root tuyệt đối, labels và mục đích pool được ghi rõ.
• Remote root riêng, writable bởi service account tối thiểu, không nằm trong controller JENKINS_HOME và có quota/cleanup.
• Labels mô tả capability/trust đã kiểm chứng; executor được sizing từ CPU, RAM, I/O, disk và queue theo pool.
• Built-in node/controller dùng numExecutors: 0 trong production.
• Launcher network flow, TLS/DNS, Java compatibility, firewall/proxy và plugin dependency đã được kiểm thử theo phiên bản thực tế.
• Retention always, idle/scheduled hoặc demand phù hợp khả năng start/reconnect thật của host và launcher.
• Maintenance bắt đầu bằng temporarily offline/drain, chờ executor rỗng, bảo trì, reconnect, canary rồi mới mở capacity.
• Workspace/cache/artifact có lifecycle, ownership, quota và tách trust tier; static agent không bị coi là security boundary.
• PR/fork untrusted không có secret, Docker socket, quyền deploy hoặc network production; credential được scope tối thiểu.
• Có owner và lịch patch cho OS, Java, toolchain, Jenkins/plugin launcher; retire node có revoke access và xử lý data theo policy.

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

• Using Jenkins agents — mô hình agent, launch method, workspace và executor.
• Managing nodes — node configuration, remote root, executors và quản trị node.
• Pipeline Syntax — directive agent, labels và Declarative Pipeline.
• Controller Isolation — tách workload build khỏi controller.
• Jenkins Security — authorization, credentials và hardening.
• Java Support Policy — đối chiếu Java với Jenkins LTS.
• SSH Build Agents plugin — launcher SSH; kiểm tra version và advisory trước khi dùng.
• Jenkins Plugins — xác minh plugin launcher/provisioning của chính instance.

Đọc tiếpCopy Anchor Link