Workspace Management

Workspace là thư mục làm việc tạm thời trên agent nơi Jenkins checkout source và chạy build. Nó rất tiện cho dữ liệu ngắn hạn, nhưng không phải artifact store, cache dùng chung mặc định hay nơi an toàn để giữ secret. Bài này dùng ví dụ Pipeline trên agent Linux; tên label, đường dẫn và plugin phải được đối chiếu với controller của bạn trước khi áp dụng ngoài sandbox.

Mục lụcCopy Anchor Link

• Mục tiêu
• Vòng đời workspace
  • Từ queue đến cleanup
  • Điều gì không được workspace bảo đảm
• Custom workspace: lợi ích và đánh đổi
  • Khi nào dùng
  • Khi nào không dùng
• Cleanup policy
  • deleteDir(): lựa chọn mặc định trong Pipeline
  • Workspace Cleanup Plugin và cleanWs
  • Retention không phải cleanup
• Concurrent builds và cô lập với ws
• Credential, secret và filesystem hygiene
• Lab sandbox: quan sát cấp phát, cô lập và dọn workspace
  • Điều kiện
  • Jenkinsfile lab
  • Kết quả mong đợi
• Troubleshooting
• Checklist xác minh
• Nguồn Jenkins chính thức
• Đọc tiếp

Mục tiêuCopy Anchor Link

Sau bài này, bạn có thể xác định workspace nào một build thực sự được cấp, chọn giữa workspace mặc định, custom workspace và ws, rồi dọn đúng dữ liệu mà build sở hữu. Bạn cũng biết cách tách cleanup filesystem khỏi retention build, tránh để hai build cùng ghi một đường dẫn, và không biến workspace thành nơi lưu credential hoặc output phát hành.

Vòng đời workspaceCopy Anchor Link

Từ queue đến cleanupCopy Anchor Link

Workspace chỉ tồn tại trong ngữ cảnh agent/executor. Khi Pipeline hoặc stage yêu cầu agent, Jenkins xếp build vào queue, chọn node khớp label và có executor trống, rồi cấp một thư mục làm việc trên filesystem của agent. Biến WORKSPACE và lệnh pwd cho biết đường dẫn mà step hiện tại đang dùng; chúng là bằng chứng tốt hơn việc đoán path từ tên job.

Một vòng đời điển hình là:

1. Cấp agent và workspace. Jenkins chọn agent, executor và workspace cho allocation hiện tại. Với Pipeline có agent none, mỗi stage có agent riêng có thể nhận node và workspace khác nhau.
2. Tạo dữ liệu tạm. Checkout, dependency đã tải, file build, report test và log cục bộ được tạo dưới workspace. Một build trước trên agent cố định có thể đã để lại file nếu không có policy dọn phù hợp.
3. Xuất dữ liệu cần giữ. Archive output theo allowlist, publish vào artifact repository, hoặc stash lượng file nhỏ cho stage sau trước khi dọn. Workspace không phải nguồn lưu trữ bền vững.
4. Cleanup. deleteDir() hoặc policy plugin xóa dữ liệu do build sở hữu sau khi evidence cần thiết đã được lưu. Với agent ephemeral, pod/VM có thể bị hủy sau build; đây là lớp dọn bổ sung, không thay thế việc thiết kế output và secret an toàn.
5. Tái sử dụng hoặc mất workspace. Agent cố định có thể tái sử dụng thư mục cho run sau. Agent ephemeral, disk cleanup của hệ điều hành, node offline hoặc agent bị thay thế có thể làm workspace biến mất bất kỳ lúc nào.

direction: down
queue: Queue
agent: Agent/executor
workspace: Workspace
run: Checkout/build/test
archive: Archive/publish output cần giữ
cleanup: Cleanup dữ liệu tạm do build sở hữu
queue -> agent -> workspace -> run
run -> archive
run -> cleanup

WORKSPACE không phải một path toàn cục. Nó thay đổi theo node, job, folder, stage agent, container/pod và cấu hình node. Đừng truyền path của nó sang một agent khác rồi giả định filesystem được mount chung. Khi stage sau cần file từ stage trước trên agent khác, dùng artifact, repository, hoặc stash/unstash cho dữ liệu nhỏ trong cùng Pipeline theo thiết kế rõ ràng.

Điều gì không được workspace bảo đảmCopy Anchor Link

Workspace không tự cung cấp các tính chất sau:

Kết luận thực hành: coi workspace là vùng scratch của một allocation. Chỉ đặt ở đó dữ liệu có thể tái tạo hoặc có policy xử lý rõ ràng.

Custom workspace: lợi ích và đánh đổiCopy Anchor Link

Custom workspace là đường dẫn do cấu hình job hoặc Pipeline yêu cầu thay vì vị trí mặc định Jenkins chọn. Trong Declarative Pipeline, customWorkspace là thuộc tính của agent { node { ... } }; Freestyle job có trường cấu hình workspace riêng. Cú pháp và đường dẫn thực tế phải được xác nhận trong Pipeline Syntax/UI trên controller đích.

pipeline {
  agent {
    node {
      label 'trusted-linux'
      customWorkspace '/srv/jenkins-workspaces/release-ci'
    }
  }

  stages {
    stage('Build') {
      steps {
        sh 'pwd'
      }
    }
  }
}

Ví dụ chỉ minh họa cấu trúc. Không sao chép /srv/jenkins-workspaces/release-ci vào production khi chưa có owner filesystem, quyền truy cập, quota, backup/exclusion và policy concurrent build. Đường dẫn tuyệt đối có thể thuộc filesystem dùng chung, mount ngoài dự kiến hoặc chứa dữ liệu của job khác.

Khi nào dùngCopy Anchor Link

Custom workspace có thể hợp lý khi có một lý do vận hành cụ thể, chẳng hạn:

• build cần filesystem/node-local có dung lượng hoặc hiệu năng được quản trị riêng;
• tool legacy yêu cầu một vị trí làm việc cố định và không thể cấu hình lại;
• đội vận hành đã provision một mount riêng cho một workload, có ownership và cleanup policy rõ;
• cần tách workspace khỏi remote root mặc định của agent vì giới hạn path hoặc filesystem.

Trước khi dùng, kiểm tra path nằm trên đúng agent pool, service user Jenkins có quyền tối thiểu cần thiết, không đi qua symlink bất ngờ, không chia với source không tin cậy và có đủ dung lượng/inode. Ghi rõ owner, quota, backup policy và điều gì được phép tồn tại sau build.

Khi nào không dùngCopy Anchor Link

Không đặt custom workspace chỉ để "dễ nhớ" hoặc để nhiều job nhìn thấy cùng file. Nó thường làm mất cơ chế cấp phát workspace của Jenkins và tăng nguy cơ hai run ghi đè, cleanup nhầm hoặc lưu dữ liệu lâu hơn dự kiến.

customWorkspace cũng không phải security boundary. Một path khác không cô lập process cùng user, Docker socket, network, cache mount, credential scope hay code không tin cậy. Tách agent/pool, identity filesystem và quyền credential theo trust boundary vẫn là yêu cầu riêng.

Cleanup policyCopy Anchor Link

Cleanup là việc trả lại dữ liệu tạm của build hiện tại. Policy tốt phải nói rõ path nào, ai sở hữu, khi nào xóa, evidence nào phải được xuất trước, và ai xử lý nếu cleanup không hoàn thành. Không dùng lệnh xóa đệ quy tự viết với path từ parameter, branch name hay biến không được kiểm soát.

deleteDir(): lựa chọn mặc định trong PipelineCopy Anchor Link

deleteDir() là Pipeline: Basic Steps để xóa đệ quy thư mục làm việc hiện hành, gồm file và thư mục con. Nó không cần shell, nên tránh khác biệt quoting giữa hệ điều hành. Gọi step này tại workspace Jenkins đã cấp; không dir() sang một path dùng chung rồi xóa, không thay bằng rm -rf, rmdir /s hay wildcard.

Mẫu sau archive output hẹp trước, sau đó dọn workspace trong post { cleanup }. Điều kiện cleanup của Declarative chạy sau các post condition khác; vì vậy evidence đã được publish trước khi xóa.

pipeline {
  agent { label 'sandbox-linux' }

  options {
    skipDefaultCheckout(true)
  }

  stages {
    stage('Tạo output vô hại') {
      steps {
        sh '''#!/bin/sh
          set -eu
          mkdir -p dist
          printf 'workspace cleanup demo\n' > dist/result.txt
        '''
      }
    }
  }

  post {
    always {
      archiveArtifacts artifacts: 'dist/result.txt', allowEmptyArchive: false
    }
    cleanup {
      deleteDir()
    }
  }
}

deleteDir() không phải bằng chứng rằng file đã bị xóa trong mọi tình huống. Nếu agent bị mất, controller dừng, permission không đủ, process còn mở file hoặc workspace nằm trên filesystem lỗi, step có thể không chạy hoặc fail. Giữ Console Output/build result làm evidence, theo dõi disk agent và để owner agent xử lý orphan bằng quy trình có kiểm soát. Không chạy lại cleanup với một path tự chọn để "chắc chắn".

Workspace Cleanup Plugin và cleanWsCopy Anchor Link

Workspace Cleanup Plugin cung cấp step cleanWs và các tùy chọn cleanup cho job. Đây là plugin, không phải Jenkins core; cài đặt, version, permission và tham số phải được review theo policy. Dùng Pipeline Syntax → Snippet Generator của controller đang chạy để lấy câu lệnh chính xác thay vì sao chép một danh sách option từ Internet.

Ví dụ tối thiểu dưới đây chỉ minh họa vị trí step. Nó cần plugin đã được phê duyệt.

post {
  cleanup {
    cleanWs()
  }
}

Các caveat quan trọng:

• Với pattern include/exclude, plugin có ngữ nghĩa riêng: kiểm tra kỹ pattern và thư mục được chọn trong sandbox. Pattern rộng có thể giữ hoặc xóa nhiều hơn người viết Jenkinsfile dự tính. Bắt đầu bằng workspace dành riêng, không dùng pattern để bảo vệ dữ liệu nhạy cảm.
• Plugin có thể dùng deferred wipeout để giao việc xóa một workspace lớn cho Async Resource Disposer. Điều này cải thiện thời gian kết thúc build nhưng cleanup vật lý có thể diễn ra sau; theo dõi disposer/disk và đừng coi build SUCCESS là xác nhận directory đã biến mất ngay lập tức.
• Khi policy yêu cầu wipeout đồng bộ hoặc filesystem không phù hợp deferred wipeout, chỉ thay đổi option/node property sau khi thử trên sandbox và có owner vận hành. Đừng vô hiệu hóa cơ chế chỉ vì một lần cleanup chậm.
• Nếu muốn dọn trước checkout trong Declarative Pipeline, cần skipDefaultCheckout(true) rồi gọi cleanup ở bước đầu; nếu không Jenkins có thể checkout trước lúc step cleanup chạy. Việc này chỉ phù hợp khi job thật sự sở hữu toàn workspace và source cần được checkout lại.
• cleanWs hay deleteDir() không sửa được secret đã bị archive, upload, in log hoặc process khác đọc. Với nghi ngờ lộ credential, thu hồi/rotate theo quy trình incident thay vì chỉ dọn disk.

Chọn một cơ chế chính cho một job. deleteDir() thường đủ cho Pipeline nhỏ với workspace được cấp riêng. Dùng cleanWs khi plugin đã được phê duyệt và bạn cần hành vi/policy của plugin đã được kiểm chứng; không thêm cả hai chỉ để cảm thấy an tâm.

Retention không phải cleanupCopy Anchor Link

buildDiscarder(logRotator(...)) quản lý build record, log và artifact theo thời gian/số lượng. Nó không dọn ngay filesystem của agent. Ngược lại, deleteDir()/cleanWs dọn data tạm trong workspace nhưng không xóa artifact đã archive, build record, cache ngoài workspace hay object ở artifact repository.

Thiết kế hai policy riêng, rồi xác minh cả workspace disk lẫn controller/artifact storage. Artifact cần điều tra hoặc phát hành phải được archive/publish theo allowlist trước cleanup, không giữ lại trong workspace chỉ vì retention của job đang dài.

Concurrent builds và cô lập với wsCopy Anchor Link

Một job có thể có nhiều build đồng thời nếu có executor và cấu hình job cho phép. Jenkins thường cấp workspace thay thế với hậu tố như @2 khi path cơ sở đang bận, nhưng đây không phải lý do để build dựa vào một tên directory cố định. Chỉ pwd/WORKSPACE của run hiện tại cho biết path đã được cấp.

Step ws yêu cầu Jenkins cấp một workspace cho block. Khi path yêu cầu đang được dùng, Jenkins có thể chọn một path thay thế, thường có hậu tố @2; do đó code không được giả định chính xác suffix hay tự tạo path @2. Hãy để Jenkins trả lời path nào thuộc về build, và luôn thao tác qua context ws đó.

node('sandbox-linux') {
  // WORKSPACE đã có sau khi node được cấp. Base giống nhau để Jenkins
  // minh họa việc cấp path riêng khi hai run overlap.
  ws("${env.WORKSPACE}-isolated") {
    sh '''#!/bin/sh
      set -eu
      printf 'build=%s\n' "$BUILD_TAG" > ownership.txt
      pwd
      cat ownership.txt
    '''
    deleteDir()
  }
}

Trong Declarative Pipeline, đặt ws { ... } trong script { ... } ở một steps block như lab bên dưới. ws chỉ cô lập workspace filesystem; nó không cô lập port TCP, Docker daemon, database, bucket, cache mount, license server hay resource ngoài Jenkins. Nếu hai build cùng thay đổi một resource external, hãy tạo resource theo build ID/namespace có owner hoặc dùng lock/serialization được phê duyệt cho resource đó.

Khi workload không thể chạy song song an toàn, biểu đạt điều đó rõ ràng thay vì hy vọng workspace suffix giải quyết mọi va chạm:

options {
  disableConcurrentBuilds()
}

disableConcurrentBuilds() đánh đổi throughput để tránh nhiều run của cùng job cùng chạy; nó không khóa job khác, không bảo vệ custom workspace dùng chung giữa nhiều job, và không thay thế isolation cho hạ tầng ngoài. Chọn serialization khi tool hoặc resource không hỗ trợ nhiều writer; chọn ws khi file tạm của các run cần tách riêng.

Credential, secret và filesystem hygieneCopy Anchor Link

Workspace có thể bị tái sử dụng, được browse bởi người có quyền job/agent, đưa vào backup hoặc bị glob quá rộng bởi archive/report/cache tool. Vì vậy secret không thuộc về workspace. Jenkins Credentials chỉ giảm việc đặt giá trị bí mật trong Git; khi bind credential, Pipeline, agent, process con và source code trong scope đó đều là một phần trust boundary.

Áp dụng các quy tắc sau:

• Chỉ bind credential trong closure/stage ngắn nhất cần nó. Không đặt token, password, private key, .env, kubeconfig hay secret bootstrap trong Jenkinsfile, parameter, custom workspace hoặc artifact.
• Không echo, printenv, env, set, cat file binding, bật set -x, hoặc Groovy-interpolate secret vào sh, bat, URL hay command line. Masking Console Output không ngăn exfiltration, encoding hay file/report chứa secret.
• Với credential file, tránh đặt dir('subdir') bên ngoài withCredentials theo cách làm file tạm nằm gần directory có thể browse. Nếu cần tách workspace, đặt ws { ... } bên ngoài binding rồi giữ binding bên trong scope ngắn nhất.
• Archive, stash, test report và upload chỉ dùng allowlist output đã biết, ví dụ dist/release/**; không dùng **/* hoặc copy cả workspace. Cleanup sau đó không cứu được file đã archive.
• Không chạy pull request/fork hoặc source không tin cậy cùng agent user/filesystem với release build có credential. Tách pool, identity, network và credential scope; built-in node/controller không phải build worker cho workload này.
• Nếu nghi ngờ secret đã lộ, dừng capability, thu hồi/rotate tại hệ thống phát hành secret và đánh giá log, artifact, cache, workspace, backup và bên nhận theo quy trình incident. Xóa workspace chỉ là một hành động containment có phạm vi hẹp.

Lab sandbox: quan sát cấp phát, cô lập và dọn workspaceCopy Anchor Link

Lab này không checkout SCM, không cần credential, không gọi network và chỉ tạo một marker vô hại trong workspace do Jenkins cấp. Nó chứng minh path được cấp và cleanup trong luồng bình thường; nó không chứng minh cleanup khi agent/host bị mất đột ngột.

Điều kiệnCopy Anchor Link

• Một Jenkins sandbox bạn kiểm soát, với agent Linux online mang label sandbox-linux, shell POSIX và quyền tạo Pipeline job.
• Không dùng built-in node/controller cho lab. Nếu agent có một executor, lab vẫn kiểm tra lifecycle; để quan sát hai path đồng thời, cần hai executor sandbox phù hợp hoặc hai agent cùng label.
• Không thêm SCM, credential, Docker socket, mount dùng chung hay plugin ngoài Pipeline cơ bản. Xác minh ws, deleteDir và Declarative Pipeline trong Pipeline Syntax/Steps Reference của controller.

Jenkinsfile labCopy Anchor Link

Tạo Pipeline job tên workspace-lifecycle-lab, chọn Pipeline script, dán Jenkinsfile sau và chạy Build Now. skipDefaultCheckout(true) bảo đảm lab không checkout repository. ws dùng base sinh từ workspace hiện tại; Jenkins quản lý path thực tế nếu có run khác đang dùng cùng base. try/finally chỉ cleanup context ws vừa được cấp.

pipeline {
  agent { label 'sandbox-linux' }

  options {
    skipDefaultCheckout(true)
  }

  stages {
    stage('Cấp workspace cô lập') {
      steps {
        script {
          ws("${env.WORKSPACE}-workspace-lab") {
            try {
              sh '''#!/bin/sh
                set -eu
                printf 'BUILD_TAG=%s\n' "$BUILD_TAG" > ownership.txt
                printf 'NODE_NAME=%s\n' "$NODE_NAME" >> ownership.txt
                printf 'WORKSPACE=%s\n' "$WORKSPACE" >> ownership.txt
                printf 'allocated_path=%s\n' "$(pwd)"
                cat ownership.txt
                sleep 20
              '''
            } finally {
              deleteDir()
              echo 'Đã yêu cầu dọn workspace cô lập của lab.'
            }
          }
        }
      }
    }
  }
}

Để quan sát concurrency, bấm Build Now lần thứ hai trong lúc build đầu còn ngủ. Chỉ làm điều này trên sandbox có đủ hai executor; nếu build thứ hai chờ queue vì chỉ có một executor, đó là quan sát capacity hợp lệ chứ không phải lỗi của ws.

Kết quả mong đợiCopy Anchor Link

Sau lab, xóa job sandbox hoặc giữ history theo policy đội ngũ. Không dọn thủ công một path suy đoán, không xóa workspace của job khác, và không áp dụng custom workspace vào production chỉ vì lab đã thành công.

TroubleshootingCopy Anchor Link

Checklist xác minhCopy Anchor Link

• Tôi phân biệt workspace tạm trên agent với artifact, stash, cache và build retention.
• Mỗi Pipeline/stage in hoặc kiểm tra WORKSPACE/pwd ở sandbox thay vì giả định path hoặc node dùng chung.
• Artifact/report cần giữ được archive hoặc publish bằng allowlist trước cleanup; không có **/* quét toàn workspace.
• deleteDir() hoặc cleanWs chỉ chạy trong workspace/context do build vừa được cấp và không nhận path từ parameter, branch hay input tự do.
• Cleanup failure, abort và agent disconnect được coi là trạng thái cần xác minh; có owner/quy trình xử lý orphan disk.
• Nếu dùng Workspace Cleanup Plugin, version/plugin approval, generated snippet, pattern, deferred wipeout và pre-build cleanup đã được thử trên sandbox.
• Custom workspace chỉ tồn tại khi có lý do vận hành, owner filesystem, quyền tối thiểu, quota, backup/exclusion và concurrency policy đã review.
• Concurrent build được tách bằng ws hoặc bị serialize có chủ đích; external resource, cache, port và database có isolation/lock riêng.
• Credential/secret không nằm trong Jenkinsfile, parameter, workspace, cache, log, report, artifact hoặc URL; binding có scope ngắn và source không tin cậy không dùng chung agent với release.
• Lab sandbox đã cho thấy path được cấp, marker vô hại, cleanup request và hành vi queue/concurrency đúng với số executor thực tế.

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

• Using Jenkins agents — agent, executor và workspace.
• Pipeline Syntax — agent — agent, customWorkspace và cấu trúc Declarative Pipeline.
• Pipeline: Basic Steps — ws, deleteDir, stash và các step cơ bản.
• Pipeline Syntax — options, post, disableConcurrentBuilds và Snippet Generator.
• Workspace Cleanup Plugin — cleanWs, cleanup trước/sau build và deferred wipeout.
• Credentials Binding Plugin — binding, masking và cảnh báo credential file/workspace.
• Using credentials — credential store, scope và permission.
• Controller isolation — tách controller khỏi build workload.

Đọc tiếpCopy Anchor Link

• Chọn agent cho Pipeline — agent, executor, queue và workspace theo stage.
• Credentials trong Pipeline — bind secret theo scope hẹp và tránh leak qua workspace.
• Build Artifacts — phân biệt workspace, stash, archive và artifact repository.
• Hành động hậu xử lý Pipeline — publish evidence trước cleanup và thiết kế post action theo kết quả build.
• Chạy Pipeline song song — cô lập filesystem, artifact và tài nguyên ngoài khi fan-out.