一、什么是流水線

jenkins 有 2 種流水線分為聲明式流水線與腳本化流水線，腳本化流水線是 jenkins 舊版本使用的流水線腳本，新版本 Jenkins 推薦使用聲明式流水線。文檔只介紹聲明流水線。

聲明式流水線

在聲明式流水線語法中，流水線過程定義在Pipeline{}中，Pipeline 塊定義了整個流水線中完成的所有工作，比如

參數(shù)說明：

• agent any：在任何可用的代理上執(zhí)行流水線或它的任何階段，也就是執(zhí)行流水線過程的位置，也可以指定到具體的節(jié)點

• stage：定義流水線的執(zhí)行過程（相當于一個階段），比如下文所示的 Build、Test、Deploy， 但是這個名字是根據(jù)實際情況進行定義的，并非固定的名字

• steps：執(zhí)行某階段具體的步驟。

腳本化流水線

在腳本化流水線語法中，會有一個或多個 Node（節(jié)點）塊在整個流水線中執(zhí)行核心工作

參數(shù)說明:

• node：在任何可用的代理上執(zhí)行流水線或它的任何階段，也可以指定到具體的節(jié)點

• stage：和聲明式的含義一致，定義流水線的階段。Stage 塊在腳本化流水線語法中是可選的，然而在腳本化流水線中實現(xiàn) stage 塊，可以清楚地在 Jenkins UI 界面中顯示每個 stage 的任務子集。

二、聲明式流水線

聲明式流水線必須包含在一個 Pipeline 塊中，比如是一個 Pipeline 塊的格式

在聲明式流水線中有效的基本語句和表達式遵循與 Groovy 的語法同樣的規(guī)則，但有以下例外

• 流水線頂層必須是一個 block，即 pipeline{}

• 分隔符可以不需要分號，但是每條語句都必須在自己的行上

• 塊只能由 Sections、Directives、Steps 或 assignment statements 組成

• 屬性引用語句被當做是無參數(shù)的方法調(diào)用，比如 input 會被當做 input()。

Sections

聲明式流水線中的 Sections 不是一個關鍵字或指令，而是包含一個或多個 Agent、Stages、 post、Directives 和 Steps 的代碼區(qū)域塊。

1.Agent

Agent 表示整個流水線或特定階段中的步驟和命令執(zhí)行的位置，該部分必須在 pipeline 塊的頂層被定義，也可以在 stage 中再次定義，但是 stage 級別是可選的。

any

在任何可用的代理上執(zhí)行流水線，配置語法

none

表示該 Pipeline 腳本沒有全局的 agent 配置。當頂層的 agent 配置為 none 時， 每個 stage 部分都需要包含它自己的 agent。配置語法

label

以節(jié)點標簽形式選擇某個具體的節(jié)點執(zhí)行 Pipeline 命令，例如：agent { label 'my-defined-label' }。節(jié)點需要提前配置標簽。

node

和 label 配置類似，只不過是可以添加一些額外的配置，比如 customWorkspace(設置默認工作目錄)

dockerfile

使用從源碼中包含的 Dockerfile 所構建的容器執(zhí)行流水線或 stage。此時對應的 agent 寫法如下

docker

相當于 dockerfile，可以直接使用 docker 字段指定外部鏡像即可，可以省去構建的時間。比如使用 maven 鏡像進行打包，同時可以指定 args

kubernetes

需要部署 kubernetes 相關的插件，官方文檔：

https://github.com/jenkinsci/kubernetes-plugin/

Jenkins 也支持使用 Kubernetes 創(chuàng)建 Slave，也就是常說的動態(tài) Slave。配置示例如下

• cloud: Configure Clouds 的名稱，指定到其中一個 k8s

• slaveConnectTimeout: 連接超時時間

• yaml: pod 定義文件，jnlp 容器的配置必須有配置無需改變，其余 containerd 根據(jù)自己情況指定

• workspaceVolume：持久化 jenkins 的工作目錄。

• persistentVolumeClaimWorkspaceVolume：掛載已有 pvc。

• nfsWorkspaceVolume：掛載 nfs 服務器目錄

• dynamicPVC：動態(tài)申請 pvc，任務執(zhí)行結束后刪除

  
  

• emptyDirWorkspaceVolume：臨時目錄，任務執(zhí)行結束后會隨著 pod 刪除被刪除，主要功能多個任務 container 共享 jenkins 工作目錄。

• hostPathWorkspaceVolume：掛載 node 節(jié)點本機目錄，注意掛載本機目錄注意權限問題，可以先創(chuàng)建設置 777 權限，否則默認 kubelet 創(chuàng)建的目錄權限為 755 默認其他用戶沒有寫權限，執(zhí)行流水線會報錯。

示例

2.agent 的配置示例

kubernetes 示例

docker 的示例

3.Post

Post 一般用于流水線結束后的進一步處理，比如錯誤通知等。Post 可以針對流水線不同的結果做出不同的處理，就像開發(fā)程序的錯誤處理，比如 Python 語言的 try catch。

Post 可以定義在 Pipeline 或 stage 中，目前支持以下條件

• always：無論 Pipeline 或 stage 的完成狀態(tài)如何，都允許運行該 post 中定義的指令；

• changed：只有當前 Pipeline 或 stage 的完成狀態(tài)與它之前的運行不同時，才允許在該 post 部分運行該步驟；

• fixed：當本次 Pipeline 或 stage 成功，且上一次構建是失敗或不穩(wěn)定時，允許運行該 post 中定義的指令；

• regression：當本次 Pipeline 或 stage 的狀態(tài)為失敗、不穩(wěn)定或終止，且上一次構建的 狀態(tài)為成功時，允許運行該 post 中定義的指令；

• failure：只有當前 Pipeline 或 stage 的完成狀態(tài)為失敗（failure），才允許在 post 部分運行該步驟，通常這時在 Web 界面中顯示為紅色

• success：當前狀態(tài)為成功（success），執(zhí)行 post 步驟，通常在 Web 界面中顯示為藍色 或綠色

• unstable：當前狀態(tài)為不穩(wěn)定（unstable），執(zhí)行 post 步驟，通常由于測試失敗或代碼 違規(guī)等造成，在 Web 界面中顯示為黃色

• aborted：當前狀態(tài)為終止（aborted），執(zhí)行該 post 步驟，通常由于流水線被手動終止觸發(fā)，這時在 Web 界面中顯示為灰色；

• unsuccessful：當前狀態(tài)不是 success 時，執(zhí)行該 post 步驟；

• cleanup：無論 pipeline 或 stage 的完成狀態(tài)如何，都允許運行該 post 中定義的指令。和 always 的區(qū)別在于，cleanup 會在其它執(zhí)行之后執(zhí)行。

示例

一般情況下 post 部分放在流水線的底部，比如本實例，無論 stage 的完成狀態(tài)如何，都會輸出一條 I will always say Hello again!信息

也可以將 post 寫在 stage，下面示例表示 Example1 執(zhí)行失敗執(zhí)行 post。

4.sepes

Steps 部分在給定的 stage 指令中執(zhí)行的一個或多個步驟，比如在 steps 定義執(zhí)行一條 shell 命令

或者是使用 sh 字段執(zhí)行多條指令

Directives

Directives 可用于一些執(zhí)行 stage 時的條件判斷或預處理一些數(shù)據(jù)，和 Sections 一致，Directives 不是一個關鍵字或指令，而是包含了 environment、options、parameters、triggers、stage、tools、 input、when 等配置。

1.Environment

Environment 主要用于在流水線中配置的一些環(huán)境變量，根據(jù)配置的位置決定環(huán)境變量的作用域?？梢远x在 pipeline 中作為全局變量，也可以配置在 stage 中作為該 stage 的環(huán)境變量。該指令支持一個特殊的方法 credentials()，該方法可用于在 Jenkins 環(huán)境中通過標識符訪問預定義的憑證。對于類型為 Secret Text 的憑證，credentials()可以將該 Secret 中的文本內(nèi)容賦值給環(huán)境變量。對于類型為標準的賬號密碼型的憑證，指定的環(huán)境變量為 username 和 password，并且也會定義兩個額外的環(huán)境變量，分別為MYVARNAME_USR和MYVARNAME_PSW。

基本變量使用

使用變量引用 secret 的憑證

使用變量引用類型為標準的賬號密碼型的憑證

這里使用 HARBOR 變量進行演示，默認情況下賬號密碼型的憑證會自動創(chuàng)建 3 個變量

• HARBOR_USR:會把憑證中 username 值賦值給這個變量

• HARBOR_PSW:會把憑證中 password 值賦值給這個變量

• HARBOR:默認情況下賦值的值為usernamme:password

2.Options

Jenkins 流水線支持很多內(nèi)置指令，比如 retry 可以對失敗的步驟進行重復執(zhí)行 n 次，可以根據(jù)不同的指令實現(xiàn)不同的效果。比較常用的指令如下:

• buildDiscarder：保留多少個流水線的構建記錄

• disableConcurrentBuilds：禁止流水線并行執(zhí)行，防止并行流水線同時訪問共享資源導致流水線失敗。

• disableResume：如果控制器重啟，禁止流水線自動恢復。

• newContainerPerStage：agent 為 docker 或 dockerfile 時，每個階段將在同一個節(jié)點的新容器中運行，而不是所有的階段都在同一個容器中運行。

• quietPeriod：流水線靜默期，也就是觸發(fā)流水線后等待一會在執(zhí)行。

• retry：流水線失敗后重試次數(shù)。

• timeout：設置流水線的超時時間，超過流水線時間，job 會自動終止。如果不加 unit 參數(shù)默認為 1 分。

• timestamps：為控制臺輸出時間戳。

定義在 pipeline 中

定義在 stage 中

Option 除了寫在 Pipeline 頂層，還可以寫在 stage 中，但是寫在 stage 中的 option 僅支持 retry、 timeout、timestamps，或者是和 stage 相關的聲明式選項，比如 skipDefaultCheckout。處于 stage 級別的 options 寫法如下

3.Parameters

Parameters 提供了一個用戶在觸發(fā)流水線時應該提供的參數(shù)列表，這些用戶指定參數(shù)的值可以通過 params 對象提供給流水線的 step（步驟）。只能定義在 pipeline 頂層。

目前支持的參數(shù)類型如下

• string：字符串類型的參數(shù)。

• text：文本型參數(shù)，一般用于定義多行文本內(nèi)容的變量。

• booleanParam：布爾型參數(shù)。

• choice：選擇型參數(shù)，一般用于給定幾個可選的值，然后選擇其中一個進行賦值。

• password：密碼型變量，一般用于定義敏感型變量，在 Jenkins 控制臺會輸出為*。

插件 Parameters

• imageTag：鏡像 tag，需要安裝 Image Tag Parameter 插件后使用

• gitParameter：獲取 git 倉庫分支，需要 Git Parameter 插件后使用

示例

4.Triggers

在 Pipeline 中可以用 triggers 實現(xiàn)自動觸發(fā)流水線執(zhí)行任務，可以通過 Webhook、Cron、 pollSCM 和 upstream 等方式觸發(fā)流水線。

Cron

定時構建假如某個流水線構建的時間比較長，或者某個流水線需要定期在某個時間段執(zhí)行構建，可以 使用 cron 配置觸發(fā)器，比如周一到周五每隔四個小時執(zhí)行一次

注意：H 的意思不是 HOURS 的意思，而是 Hash 的縮寫。主要為了解決多個流水線在同一時間同時運行帶來的系統(tǒng)負載壓力。

Upstream

Upstream 可以根據(jù)上游 job 的執(zhí)行結果決定是否觸發(fā)該流水線。比如當 job1 或 job2 執(zhí)行成功時觸發(fā)該流水線

目前支持的狀態(tài)有SUCCESS、UNSTABLE、FAILURE、NOT_BUILT、ABORTED等。

5.Input

Input 字段可以實現(xiàn)在流水線中進行交互式操作，比如選擇要部署的環(huán)境、是否繼續(xù)執(zhí)行某個階段等。

配置 Input 支持以下選項

• message：必選，需要用戶進行 input 的提示信息，比如：“是否發(fā)布到生產(chǎn)環(huán)境？”；

• id：可選，input 的標識符，默認為 stage 的名稱；

• ok：可選，確認按鈕的顯示信息，比如：“確定”、“允許”；

• submitter：可選，允許提交 input 操作的用戶或組的名稱，如果為空，任何登錄用戶均可提交 input；

• parameters：提供一個參數(shù)列表供 input 使用。

假如需要配置一個提示消息為“還繼續(xù)么”、確認按鈕為“繼續(xù)”、提供一個 PERSON 的變量的參數(shù)，并且只能由登錄用戶為 alice 和 bob 提交的 input 流水線

6.when

When 指令允許流水線根據(jù)給定的條件決定是否應該執(zhí)行該 stage，when 指令必須包含至少 一個條件。如果 when 包含多個條件，所有的子條件必須都返回 True，stage 才能執(zhí)行。

When 也可以結合 not、allOf、anyOf 語法達到更靈活的條件匹配。

目前比較常用的內(nèi)置條件如下

• branch：當正在構建的分支與給定的分支匹配時，執(zhí)行這個 stage。注意，branch 只適用于多分支流水線

• changelog：匹配提交的 changeLog 決定是否構建，例如:when { changelog '.*^\\[DEPENDENCY\\] .+$' }

• environment：當指定的環(huán)境變量和給定的變量匹配時，執(zhí)行這個 stage，例如：when { environment name: 'DEPLOY_TO', value: 'production' }

• equals：當期望值和實際值相同時，執(zhí)行這個 stage，例如：when { equals expected: 2, actual: currentBuild.number }；

• expression：當指定的 Groovy 表達式評估為 True，執(zhí)行這個 stage，例如：when { expression { return params.DEBUG_BUILD } }；

• tag：如果 TAG_NAME 的值和給定的條件匹配，執(zhí)行這個 stage，例如：when { tag "release-" }；

• not：當嵌套條件出現(xiàn)錯誤時，執(zhí)行這個 stage，必須包含一個條件，例如：when { not { branch 'master' } }；

• allOf：當所有的嵌套條件都正確時，執(zhí)行這個 stage，必須包含至少一個條件，例如：when { allOf { branch 'master'; environment name: 'DEPLOY_TO', value: 'production' } }；

• anyOf：當至少有一個嵌套條件為 True 時，執(zhí)行這個 stage，例如：when { anyOf { branch 'master'; branch 'staging' } }。

示例：當分支為 main 時執(zhí)行 Example Deploy 步驟

也可以同時配置多個條件，比如分支是 production，而且 DEPLOY_TO 變量的值為 main 時，才執(zhí)行 Example Deploy

也可以使用 anyOf 進行匹配其中一個條件即可，比如分支為 main 或 DEPLOY_TO 為 main 或 master 時執(zhí)行 Deploy

也可以使用 expression 進行正則匹配，比如當 BRANCH_NAME 為 main 或 master，并且 DEPLOY_TO 為 master 或 main 時才會執(zhí)行 Example Deploy

默認情況下，如果定義了某個 stage 的 agent，在進入該 stage 的 agent 后，該 stage 的 when 條件才會被評估，但是可以通過一些選項更改此選項。比如在進入 stage 的 agent 前評估 when， 可以使用 beforeAgent，當 when 為 true 時才進行該 stage

目前支持的前置條件如下

• beforeAgent：如果 beforeAgent 為 true，則會先評估 when 條件。在 when 條件為 true 時，才會進入該 stage

• beforeInput：如果 beforeInput 為 true，則會先評估 when 條件。在 when 條件為 true 時，才會進入到 input 階段；

• beforeOptions：如果 beforeInput 為 true，則會先評估 when 條件。在 when 條件為 true 時，才會進入到 options 階段；

• beforeOptions 優(yōu)先級大于beforeInput大于beforeAgent

Parallel

在聲明式流水線中可以使用 Parallel 字段，即可很方便的實現(xiàn)并發(fā)構建，比如對分支 A、B、 C 進行并行處理

三、jenkinsfile的使用

上面講過流水線支持兩種語法，即聲明式和腳本式，這兩種語法都支持構建持續(xù)交付流水線。并且都可以用來在 Web UI 或 Jenkinsfile 中定義流水線，不過通常將 Jenkinsfile 放置于代碼倉庫中（當然也可以放在單獨的代碼倉庫中進行管理）。

創(chuàng)建一個 Jenkinsfile 并將其放置于代碼倉庫中，有以下好處

• 方便對流水線上的代碼進行復查/迭代

• 對管道進行審計跟蹤

• 流水線真正的源代碼能夠被項目的多個成員查看和編輯

環(huán)境變量

1.靜態(tài)變量

Jenkins 有許多內(nèi)置變量可以直接在 Jenkinsfile 中使用，可以通過JENKINS_URL/pipeline/syntax/globals#env獲取完整列表。目前比較常用的環(huán)境變量如下

• BUILD_ID：當前構建的 ID，與 Jenkins 版本 1.597+中的 BUILD_NUMBER 完全相同

• BUILD_NUMBER：當前構建的 ID，和 BUILD_ID 一致

• BUILD_TAG：用來標識構建的版本號，格式為：jenkins-{BUILD_NUMBER}， 可以對產(chǎn)物進行命名，比如生產(chǎn)的 jar 包名字、鏡像的 TAG 等；

• BUILD_URL：本次構建的完整 URL，比如：http://buildserver/jenkins/job/MyJobName/17/%EF%BC%9B

• JOB_NAME：本次構建的項目名稱

• NODE_NAME：當前構建節(jié)點的名稱；

• JENKINS_URL：Jenkins 完整的 URL，需要在 SystemConfiguration 設置；

• WORKSPACE：執(zhí)行構建的工作目錄。

示例如果一個流水線名稱為print_env，第 2 次構建，各個變量的值。

上述變量會保存在一個 Map 中，可以使用 env.BUILD_ID 或 env.JENKINS_URL 引用某個內(nèi)置變量

2.動態(tài)變量

動態(tài)變量是根據(jù)某個指令的結果進行動態(tài)賦值，變量的值根據(jù)指令的執(zhí)行結果而不同。如下所示

• returnStdout：將命令的執(zhí)行結果賦值給變量，比如下述的命令返回的是 clang，此時 CC 的值為“clang”。

• returnStatus：將命令的執(zhí)行狀態(tài)賦值給變量，比如下述命令的執(zhí)行狀態(tài)為 1，此時 EXIT_STATUS 的值為 1。

憑證管理

Jenkins 的聲明式流水線語法有一個 credentials()函數(shù)，它支持 secret text（加密文本）、username 和 password（用戶名和密碼）以及 secret file（加密文件）等。接下來看一下一些常用的憑證處理方法。

1.加密文本

本實例演示將兩個 Secret 文本憑證分配給單獨的環(huán)境變量來訪問 Amazon Web 服務，需要 提前創(chuàng)建這兩個文件的 credentials（實踐的章節(jié)會有演示），Jenkinsfile 文件的內(nèi)容如下

2.用戶名密碼

本示例用來演示 credentials 賬號密碼的使用，比如使用一個公用賬戶訪問 Bitbucket、GitLab、 Harbor 等。假設已經(jīng)配置完成了用戶名密碼形式的 credentials，憑證 ID 為 harbor-account

上述的配置會自動生成 3 個環(huán)境變量

• BITBUCKET_COMMON_CREDS：包含一個以冒號分隔的用戶名和密碼，格式為 username:password

• BITBUCKET_COMMON_CREDS_USR：僅包含用戶名的附加變量

• BITBUCKET_COMMON_CREDS_PSW：僅包含密碼的附加變量。

3.加密文件

需要加密保存的文件，也可以使用 credential，比如鏈接到 Kubernetes 集群的 kubeconfig 文件等。

假如已經(jīng)配置好了一個 kubeconfig 文件，此時可以在 Pipeline 中引用該文件