Jenkins SSH 身份驗證與 CLI 遠端控制

– 13 分鐘閱讀

Jenkins CLI 和 REST API 提供了強大的遠端控制能力，讓開發者能更有效率地管理和操作 Jenkins 伺服器。透過 SSH 身份驗證機制，可以確保連線安全，而 CLI 提供了便捷的命令列操作方式，適合執行快速指令和指令碼化任務。此外，REST API 則提供了更豐富的功能和彈性，方便與其他系統整合，並能以程式化的方式控制 Jenkins。兩種方式各有優劣，可根據實際需求選擇合適的工具。例如，使用 SSH 搭配 CLI 適合執行簡單的建置任務，而使用 REST API 則更適合複雜的自動化流程和跨系統整合。瞭解並善用這些工具，能大幅提升 CI/CD 流程的效率和自動化程度。

使用SSH身份驗證構建Jenkins工作

本文將介紹如何使用Jenkins CLI命令構建Jenkins工作，同時使用SSH身份驗證。

Jenkins CLI命令選項

Jenkins CLI的build命令具有以下可選命令列選項：

  • -c：如果傳遞此選項，則build命令會檢查工作中組態的SCM是否有變化，並且只有在有變化的情況下才觸發構建。
  • -f：如果傳遞此選項，則build命令會根據構建結果傳回離開程式碼。如果構建成功，則傳回離開程式碼0。
  • -p：使用此選項，可以以Key=Value格式傳遞引數給構建。
  • -s：如果傳遞此選項，則build命令會等待構建完成或被中斷。如果未設定此選項，則build命令會觸發構建，但不會等待其完成。
  • -v：此選項會列印構建的控制檯輸出。
  • -w：此選項會等待命令開始。

使用SSH身份驗證

要使用Jenkins CLI與SSH身份驗證，需要使用以下兩種方法之一：

  1. 使用SSH客戶端，如OpenSSH或Putty。
  2. 使用Jenkins-cli.jar。

使用OpenSSH客戶端執行Jenkins CLI命令

以下示範如何使用OpenSSH客戶端觸發構建使用Jenkins CLI的build命令。

首先，開啟命令提示符並執行以下命令以構建ReleaseCalculatorAPI工作：

ssh ${JenkinsUserName}@${JenkinsServerIPAddress} -p ${JenkinsSSHPort} -i ${PrivateKeyFilePath} build ${JOB_NAME}

我用實際值替換了佔位符，並建立了以下命令：

ssh Pranodayd@192.168.43.10 -p 9090 -i D:\SSHKey\JenkinsCLI build ReleaseCalculatorAPI

內容解密：

上述命令使用SSH客戶端連線到Jenkins伺服器，並使用私鑰檔案進行身份驗證。然後，它執行build命令以構建指定的工作。

圖表翻譯：

@startuml
note
  無法自動轉換的 Mermaid 圖表
  請手動檢查和調整
end note
@enduml

圖表翻譯：

上述圖表顯示了客戶端、Jenkins伺服器和工作之間的互動過程。客戶端連線到Jenkins伺服器，然後執行build命令以構建指定的工作。工作完成構建後，傳回結果給客戶端。

Jenkins CLI 介紹

Jenkins CLI 是一種強大的工具，允許使用者從命令列介面遠端控制 Jenkins 伺服器。它提供了多種功能，包括建立、執行和管理 Jenkins 工作。

SSH 連線模式

要使用 SSH 連線模式，需要在 Jenkins 伺服器上設定 SSH 伺服器。然後，可以使用 SSH 使用者端工具連線到 Jenkins 伺服器，並執行 Jenkins CLI 命令。

以下是使用 SSH 連線模式的範例：

ssh Pranodayd@192.168.43.10 -p 9090 -i D:\SSHKey\JenkinsCLI
build ReleaseCalculatorAPI

這個命令會連線到 Jenkins 伺服器，並執行 build 命令來建立 ReleaseCalculatorAPI 工作。

Jenkins-cli.jar 客戶端

Jenkins-cli.jar 是一種 Java 客戶端，允許使用者從命令列介面遠端控制 Jenkins 伺服器。它提供了多種功能，包括建立、執行和管理 Jenkins 工作。

要使用 Jenkins-cli.jar 客戶端，需要下載 Jenkins-cli.jar 檔案，並將其新增到系統的 CLASSPATH 中。然後，可以使用以下命令來執行 Jenkins CLI 命令：

java -jar jenkins-cli.jar -s http://192.168.43.10:8080 build ReleaseCalculatorAPI

這個命令會連線到 Jenkins 伺服器，並執行 build 命令來建立 ReleaseCalculatorAPI 工作。

SSH 連線模式與 Jenkins-cli.jar 客戶端

SSH 連線模式和 Jenkins-cli.jar 客戶端都是用於遠端控制 Jenkins 伺服器的工具。但是，它們有不同的工作原理和優缺點。

SSH 連線模式需要在 Jenkins 伺服器上設定 SSH 伺服器，並使用 SSH 使用者端工具連線到 Jenkins 伺服器。這個模式提供了更高的安全性和靈活性，但需要更多的設定和維護。

Jenkins-cli.jar 客戶端是一種 Java 客戶端，允許使用者從命令列介面遠端控制 Jenkins 伺服器。這個客戶端提供了更簡單的設定和使用方式，但需要下載和安裝 Jenkins-cli.jar 檔案。

內容解密：
  • SSH 連線模式需要在 Jenkins 伺服器上設定 SSH 伺服器，並使用 SSH 使用者端工具連線到 Jenkins 伺服器。
  • Jenkins-cli.jar 客戶端是一種 Java 客戶端，允許使用者從命令列介面遠端控制 Jenkins 伺服器。
  • 選擇適合的工具取決於使用者的需求和環境。

圖表翻譯：

@startuml
:SSH 連線模式; --> [需要設定 SSH 伺服器] :需要設定;
:B; --> [連線到 Jenkins 伺服器] :連線到;
:Jenkins-cli.jar 客戶端; --> [下載和安裝] :下載和安裝;
:E; --> [連線到 Jenkins 伺服器] :連線到;
@enduml

這個圖表展示了 SSH 連線模式和 Jenkins-cli.jar 客戶端的工作原理和流程。

Jenkins CLI命令列工具使用

Jenkins CLI是一個強大的命令列工具，允許使用者遠端控制Jenkins伺服器，執行各種操作，如建立、刪除和組態作業。以下是使用Jenkins CLI的基本。

連線Jenkins伺服器

要使用Jenkins CLI，首先需要連線到Jenkins伺服器。可以使用以下命令：

java -jar ${PATH of Jenkins-cli.jar} -s ${JENKINSURL} -i ${PrivateKeyPATH} -ssh -user ${UserName} ${Jenkins CLI command}

其中，${PATH of Jenkins-cli.jar}是Jenkins CLI jar檔案的路徑，${JENKINSURL}是Jenkins伺服器的URL，${PrivateKeyPATH}是私鑰檔案的路徑，${UserName}是使用者名稱，${Jenkins CLI command}是要執行的Jenkins CLI命令。

建立作業

要建立一個新的作業，可以使用以下命令：

java -jar D:\JenkinsBookExamples\jenkins-cli.jar -s JenkinsCLI -p 9090 build Demo

這個命令會建立一個名為"Demo"的新作業。

匯出所有作業

如果要將Jenkins伺服器從一臺機器遷移到另一臺機器，需要先匯出所有作業。可以使用以下批次程式碼：

set JenkinsCLIJarLocation=D:\JenkinsBookExamples\jenkins-cli.jar
FOR /F "tokens=*" %%g IN ('java -jar %JenkinsCLIJarLocation% -s %JenkinsURL% -auth Pranodayd:Pranodayd@10 list-jobs') do (
  java -jar %JenkinsCLIJarLocation% -s %JenkinsURL% -auth Pranodayd:Pranodayd@10 get-job %%g > %%g.xml
)

這個批次程式碼會匯出所有作業的組態到.xml檔案中。

匯入所有作業

一旦匯出了所有作業，可以將.xml檔案複製到新的Jenkins伺服器機器上，並執行以下批次程式碼：

set JenkinsCLIJarLocation=D:\JenkinsBookExamples\jenkins-cli.jar

然後，可以使用以下命令匯入所有作業：

FOR /F "tokens=*" %%g IN ('dir /b *.xml') do (
  java -jar %JenkinsCLIJarLocation% -s %JenkinsURL% -auth Pranodayd:Pranodayd@10 create-job %%g < %%g.xml
)

這個命令會匯入所有.xml檔案中的作業組態。

圖表翻譯：

@startuml
:連線Jenkins伺服器; --> :建立作業;
:B; --> :匯出所有作業;
:C; --> :匯入所有作業;
:D; --> :完成;
@enduml

內容解密：

以上命令和批次程式碼示範瞭如何使用Jenkins CLI建立、匯出和匯入作業。可以根據需要修改和擴充套件這些命令和程式碼。

Jenkins CLI 的應用與實踐

在 Jenkins 的世界中，命令列介面（CLI）是一個強大的工具，讓使用者可以更有效地與 Jenkins 伺服器進行互動。透過 Jenkins CLI，我們可以實作各種功能，從建立新的工作（Job）到管理現有的工作。

Jenkins CLI 的基本使用

要使用 Jenkins CLI，首先需要下載 jenkins-cli.jar 檔案，並設定相關的環境變數。例如，設定 JenkinsCLIJarLocation 變數來指定 jenkins-cli.jar 的位置，設定 JenkinsURL 變數來指定 Jenkins 伺服器的 URL。

set JobsExportLocation=D:\PD
FOR /F "delims=*" %%a IN ('dir /s /b %JobsExportLocation%\*.xml') do java -jar %JenkinsCLIJarLocation% -s %JenkinsURL% -auth Pranodayd:Pranodayd@10 create-job %%~na< %%a

這段批次程式碼定義了 JobsExportLocation 變數，指定了工作 XML 檔案的存放位置。然後，使用 FOR 命令迴圈遍歷該目錄下的所有 XML 檔案，並使用 Jenkins CLI 命令建立新的工作。

Jenkins CLI 的進階應用

除了基本的工作建立功能，Jenkins CLI 還提供了許多其他功能，例如工作的匯出和匯入、工作的啟動和停止等。以下是使用 Jenkins CLI 匯出工作的範例：

java -jar jenkins-cli.jar -s http://localhost:8080 get-job myjob > myjob.xml

這個命令會將名為 myjob 的工作匯出到 myjob.xml 檔案中。

內容解密：

上述批次程式碼使用了 FOR 命令來迴圈遍歷目錄下的 XML 檔案，並使用 Jenkins CLI 命令建立新的工作。其中，%%~na 用於提取檔名，而 %%a 用於指定 XML 檔案的路徑。

圖表翻譯：

@startuml
:開始; --> :設定環境變數;
:B; --> :下載 jenkins-cli.jar;
:C; --> :設定 JenkinsCLIJarLocation 和 JenkinsURL;
:D; --> :迴圈遍歷 XML 檔案;
:E; --> :建立新的工作;
:F; --> :結束;
@enduml

這個流程圖描述了使用 Jenkins CLI 的基本步驟，從設定環境變數到建立新的工作。

使用Jenkins的REST API進行程式化控制

在前一章中，我們討論瞭如何使用Jenkins的CLI與Jenkins伺服器進行互動。然而，有時候使用CLI並不足以滿足使用者的需求，特別是當需要更高程度的程式化控制時。Jenkins提供了REST API，允許使用者使用不同的程式語言（如Java或Python）與Jenkins伺服器進行互動。

本章將介紹如何使用Python語言透過Jenkins的REST API進行程式化控制。同時，我們也將探討如何建立可重用的函式庫，以便在多個pipeline中使用。

Jenkins遠端存取API

Jenkins提供了遠端存取API，允許使用者存取其功能。目前，Jenkins的遠端存取API有三種風格：

  • XML
  • JSON
  • Python

Jenkins的遠端存取API是REST-like風格的，REST API是一種輕量級的網路服務，可以透過HTTP協定進行呼叫。Jenkins API可在.../api/ URL下存取，其中...部分是要操作的資料。

REST API基礎

在深入探討Jenkins遠端API之前，讓我們先了解一些REST API的基礎知識。REST API提供了不同的方法，例如GET、POST、PUT和DELETE。如果您想要取得伺服器上某個資源的資訊，您可以使用GET方法。如果您想要在伺服器上建立新的資源，例如一個Jenkins工作，您可以使用POST方法。

您可以透過以下三種方式向REST API傳遞引數：

  • 查詢引數：作為URL的一部分，以Key-Value形式出現。
  • 路徑引數：作為URL端點的一部分，通常以{}包圍。
  • 專案引數：在請求標頭中傳遞，通常用於驗證資訊，如使用者名稱和密碼或API令牌。

使用Jenkins遠端存取API

本文將介紹如何使用Jenkins REST API進行不同的任務。開始使用Jenkins REST API之前，您需要一個REST使用者端來存取REST API。有一個流行的REST使用者端稱為Curl，允許您透過命令列程式存取REST API。

安裝Curl

您可以下載Curl並解壓縮到您想要的位置。然後，將bin目錄路徑新增到PATH環境變數中，以便您可以從命令提示符中的任何工作目錄存取Curl.exe。

使用Curl存取REST API

使用Curl，您可以存取REST API並執行不同的任務，例如取得工作列表、建立新的工作等。

@startuml
:開始; --> :安裝Curl;
:B; --> :設定PATH環境變數;
:C; --> :使用Curl存取REST API;
:D; --> :執行任務;
@enduml

圖表翻譯：

此圖表展示瞭如何使用Curl存取Jenkins REST API的流程。首先，您需要安裝Curl並設定PATH環境變數。然後，您可以使用Curl存取REST API並執行不同的任務。

內容解密：

在此範例中，我們使用Curl來存取Jenkins REST API。首先，我們需要安裝Curl並設定PATH環境變數。然後，我們可以使用Curl來存取REST API並執行不同的任務，例如取得工作列表、建立新的工作等。

import requests

# 設定Jenkins伺服器URL
jenkins_url = "http://localhost:8080"

# 設定REST API端點
api_endpoint = "/api/json"

# 傳送GET請求
response = requests.get(jenkins_url + api_endpoint)

# 列印回應內容
print(response.json())

內容解密：

此範例展示瞭如何使用Python語言透過Jenkins REST API取得工作列表。首先，我們需要設定Jenkins伺服器URL和REST API端點。然後，我們可以傳送GET請求並列印回應內容。

使用Jenkins遠端API取得現有Jenkins工作的組態

現在您已經設定了Curl，讓我們開始實際工作。首先，我們將使用Jenkins遠端API取得現有Jenkins工作的組態。下面是相關的API請求：

curl -X GET \
  http://localhost:8080/job/Demo/config.xml \
  -u Pranodayd:119737275fd132a08d5a3b457ed56649a2 \
  -o D:\PD\mylocalconfig.xml

這個API請求的詳情如下：

  • -X GET：定義了REST API的方法型別，這是一個GET請求，因為您正在取得已經存在於伺服器上的資源的詳細資訊。
  • http://localhost:8080/job/Demo/config.xml：這是您想要取得的工作（Demo）的config.xml檔案的URL。如前所述，每個工作的組態都儲存在${JENKINS_HOME}\Jobs\${JOB_NAME}目錄下的名為config.xml的檔案中。
  • -u Pranodayd:119737275fd132a08d5a3b457ed56649a2：在-u之後，您正在傳送使用者的身份驗證資訊。身份驗證資訊包含使用者名稱和API令牌，這與本章前面使用的API令牌相同。
  • -o D:\PD\mylocalconfig.xml：使用-o，您正在將從伺服器接收到的組態內容寫入指定的檔案路徑。

注意事項

使用REST API時，您需要提供執行任務的授權使用者的身份驗證資訊。

執行命令

執行以下命令：

curl -X GET \
  http://localhost:8080/job/Demo/config.xml \
  -u Pranodayd:119737275fd132a08d5a3b457ed56649a2 \
  -o D:\PD\mylocalconfig.xml

前往目錄D:\PD，您將看到mylocalconfig.xml檔案已經被建立。

使用Jenkins遠端API建立新Jenkins工作

本文使用Jenkins遠端API建立一個新Jenkins工作。要建立新工作，您需要一個工作名稱和一個作為範本的組態XML檔案。

curl -X POST \
  http://localhost:8080/createItem?name=RestAPIJob \
  -u Pranodayd:119737275fd132a08d5a3b457ed56649a2 \
  --data-binary @D:\PD\Demo.xml \
  -H "Content-Type:text/xml"

這個API請求的詳情如下：

  • -X POST：定義了REST API的方法型別，這是一個POST請求，因為您正在建立一個新資源於伺服器上。
  • http://localhost:8080/createItem?name=RestAPIJob：createItem是您想要存取以建立新工作的URL端點。name=RestAPIJob之後的是一個查詢字串引數，包含新工作的名稱。
  • -u Pranodayd:119737275fd132a08d5a3b457ed56649a2：在-u之後，您正在傳送使用者的身份驗證資訊。身份驗證資訊包含使用者名稱和API令牌，這與本章前面使用的API令牌相同。
  • --data-binary @D:\PD\Demo.xml：您正在傳送作為新工作範本的組態XML檔案。

圖表翻譯：

@startuml
:Client; --> [GET Request] :GET;
:B; --> [Return config.xml] :Return;
:A; --> [POST Request] :POST;
:B; --> [Create New Job] :Create;
@enduml

這個流程圖展示了客戶端如何透過GET請求取得現有工作的組態，並透過POST請求建立新的Jenkins工作。

Jenkins 遠端 API：觸發工作和傳送引數

Jenkins 提供了一個遠端 API，可以用來觸發工作和傳送引數給工作。這個 API 可以用來自動化工作的觸發和管理。

觸發引數化工作

要觸發一個引數化工作，需要使用 buildWithParameters 端點。這個端點需要傳送工作名稱和引數值。

例如，要觸發一個名為 BuildAndDeployCalculatorWebApplication 的工作，需要使用以下命令：

curl -X POST \
  https://jenkins-url/job/BuildAndDeployCalculatorWebApplication/buildWithParameters \
  -u username:api-token \
  -d "CalculatorWebApplicationDeploymentDirectory=D:\JenkinsBookExamples\DeployedCalculatorWebApp\&TypeOfTestsToRun=AllTests"

這個命令會觸發 BuildAndDeployCalculatorWebApplication 工作，並傳送兩個引數：CalculatorWebApplicationDeploymentDirectory 和 TypeOfTestsToRun。

觸發非引數化工作

要觸發一個非引數化工作，需要使用 build 端點。這個端點不需要傳送任何引數。

例如，要觸發一個名為 ReleaseCalculatorAPI 的工作，需要使用以下命令：

curl -X POST \
  https://jenkins-url/job/ReleaseCalculatorAPI/build \
  -u username:api-token

這個命令會觸發 ReleaseCalculatorAPI 工作。

Jenkins 遠端 API 的優點

Jenkins 遠端 API 提供了很多優點，包括：

  • 自動化工作的觸發和管理
  • 可以用來整合其他工具和系統
  • 提供了一個靈活和可擴充套件的方式來管理工作

從技術架構視角來看，使用 SSH 身份驗證和 Jenkins CLI 或 REST API 構建 Jenkins 工作，展現了高度的自動化和遠端控制能力。分析比較 SSH 與 Jenkins-cli.jar 兩種方式，前者安全性更高，但需要伺服器端額外設定 SSH 服務；後者則更易於佈署和使用。技術限制在於需要妥善保管私鑰或 API Token，避免安全風險。實務上，建議根據團隊規模和安全需求選擇合適的方案，小型團隊可使用 Jenkins-cli.jar 簡化佈署，大型企業則應優先考慮 SSH 的安全性。展望未來，Jenkins API 的持續發展將進一步提升其與其他系統的整合能力，預計將出現更多根據 API 的自動化工具和最佳實務，簡化 CI/CD 流程，同時強化安全管控。對於追求高度自動化和彈性佈署的團隊而言，掌握 Jenkins 遠端控制技巧至關重要。

玄貓

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。