教學課程：部署至 Service Fabric 叢集

  • 發行項

本教學課程涵蓋數種設定 Jenkins 環境的可能方式，以及建置應用程式之後將應用程式部署至 Service Fabric 叢集的不同方式。 請遵循下列一般步驟，成功設定 Jenkins、從 GitHub 提取變更、建置應用程式，並將其部署至叢集：

  1. 請確定您安裝 必要條件。
  2. 然後遵循下列其中一節中的步驟來設定 Jenkins：
  3. 設定 Jenkins 之後，請遵循建立和設定 Jenkins 作業中的步驟，在對應用程式進行變更時設定 GitHub 以觸發 Jenkins，並透過建置步驟設定 Jenkins 作業管線，以從 GitHub 提取變更並建置您的應用程式。
  4. 最後，設定 Jenkins 作業建置後步驟，將您的應用程式部署至 Service Fabric 叢集。 有兩種方式可將 Jenkins 設定為將應用程式部署至叢集：
    • 針對開發和測試環境，請使用使用 叢集管理端點設定部署。 此方法是設定最簡單的部署方法。
    • 針對生產環境，請使用使用 Azure 認證設定部署。 Microsoft 建議在生產環境中使用此方法，因為使用 Azure 認證，您可以限制 Jenkins 作業對 Azure 資源的存取。

必要條件

  • 請確定 Git 已在本機安裝。 您可以根據您的作業系統，從 Git 下載頁面 安裝適當的 Git 版本。 如果您不熟悉 Git，請從 Git 檔深入瞭解。
  • 本文使用 GitHub 上的 Service Fabric 使用者入門範例 ： https://github.com/Azure-Samples/service-fabric-java-getting-started 讓應用程式建置和部署。 您可以分支此存放庫，以遵循或透過對指示進行一些修改，使用您自己的 GitHub 專案。

在現有的 Jenkins 環境中安裝 Service Fabric 外掛程式

如果您要將 Service Fabric 外掛程式新增至現有的 Jenkins 環境，您需要執行下列步驟：

安裝環境所需的必要條件之後，您可以搜尋 Jenkins Marketplace 中的 Azure Service Fabric 外掛程式並加以安裝。

安裝外掛程式之後，請直接跳到 建立及設定 Jenkins 作業。

在 Service Fabric 叢集內設定 Jenkins

您可以在 Service Fabric 叢集內部或外部設定 Jenkins。 下列各節說明如何在使用 Azure 記憶體帳戶來儲存容器實例的狀態時，在叢集內設定它。

  1. 請確定您已安裝已安裝 Docker 的 Service Fabric Linux 叢集。 在 Azure 中執行的 Service Fabric 叢集已安裝 Docker。 如果您要在本機執行叢集 （OneBox 開發環境），請使用 命令檢查電腦上 docker info 是否已安裝 Docker。 如果未安裝，請使用下列命令加以安裝：

    sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh

    注意

    請確定 8081 埠已指定為叢集上的自定義端點。 如果您使用本機叢集，請確定主機計算機上已開啟埠 8081，且該埠具有公用 IP 位址。

  2. 使用下列命令複製應用程式：

    git clone https://github.com/suhuruli/jenkins-container-application.git
cd jenkins-container-application

  3. 將 Jenkins 容器的狀態保存在檔案共享中：

    1. 在 與叢集相同的區域中 建立 Azure 記憶體帳戶，其名稱如下 sfjenkinsstorage1。

    2. 在記憶體帳戶底下建立 檔案共用 ，其名稱如下 sfjenkins。

    3. 單擊檔案共享的 連線，並記下它從 Linux 連線 顯示的值，此值看起來應該類似下列值：

      sudo mount -t cifs //sfjenkinsstorage1.file.core.windows.net/sfjenkins [mount point] -o vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777

    注意

    若要掛接 cifs 共用，您必須在叢集節點中安裝 cifs-utils 套件。

  4. 使用步驟 2 中的 azure 記憶體詳細數據更新文稿中的 setupentrypoint.sh 佔位元值。

    vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
    • 將取代 [REMOTE_FILE_SHARE_LOCATION] 為上述步驟 2 中連線輸出的值 //sfjenkinsstorage1.file.core.windows.net/sfjenkins 。
    • 將取代 [FILE_SHARE_CONNECT_OPTIONS_STRING] 為上述步驟 2 的值 vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777 。

  5. 僅限安全叢集：

    若要從 Jenkins 設定在安全叢集上部署應用程式，必須在 Jenkins 容器中存取叢集憑證。 在 ApplicationManifest.xml 檔案的 ContainerHostPolicies 標籤下，新增此憑證參考，並使用叢集憑證的參考更新指紋值。

    <CertificateRef Name="MyCert" X509FindValue="[Thumbprint]"/>

    此外，在 ApplicationManifest.xml 檔案的 ApplicationManifest （root） 卷標下新增下列幾行，並使用叢集憑證的卷標更新指紋值。

    <Certificates>
  <SecretsCertificate X509FindType="FindByThumbprint" X509FindValue="[Thumbprint]" />
</Certificates>

  6. 連線 叢集並安裝容器應用程式。

    安全叢集

    sfctl cluster select --endpoint https://PublicIPorFQDN:19080  --pem [Pem] --no-verify # cluster connect command
bash Scripts/install.sh

    上述命令會採用 PEM 格式的憑證。 如果您的憑證採用 PFX 格式，您可以使用下列命令來轉換它。 如果您的 PFX 檔案未受到密碼保護，請將 passin 參數指定為 -passin pass:。

    openssl pkcs12 -in cert.pfx -out cert.pem -nodes -passin pass:<password>

    不安全的叢集

    sfctl cluster select --endpoint http://PublicIPorFQDN:19080 # cluster connect command
bash Scripts/install.sh

    這會在叢集上安裝 Jenkins 容器，而且可以使用 Service Fabric Explorer 來監視。

    注意

    在叢集上下載 Jenkins 映射可能需要幾分鐘的時間。

  7. 從瀏覽器移至 http://PublicIPorFQDN:8081。 它提供登入所需的初始系統管理員密碼路徑。

  8. 查看 Service Fabric Explorer，以判斷 Jenkins 容器正在執行哪個節點上。 安全殼層 （SSH） 登入此節點。

    ssh user@PublicIPorFQDN -p [port]

  9. 使用 docker ps -a取得容器實例標識碼。

  10. 安全殼層 （SSH） 登入容器，並貼上您在 Jenkins 入口網站上顯示的路徑。 例如，如果在入口網站中顯示路徑 PATH_TO_INITIAL_ADMIN_PASSWORD，請執行下列命令：

    docker exec -t -i [first-four-digits-of-container-ID] /bin/bash   # This takes you inside Docker shell

    cat PATH_TO_INITIAL_ADMIN_PASSWORD # This displays the password value

  11. 在 [Jenkins 用戶入門] 頁面上，選擇 [選取要安裝的外掛程式] 選項，選取 [ 無 ] 複選框，然後按兩下 [安裝]。

  12. 建立使用者或選取以系統管理員身分繼續。

設定 Jenkins 之後，請直接跳到 建立及設定 Jenkins 作業。

在 Service Fabric 叢集外設定 Jenkins

您可以在 Service Fabric 叢集內部或外部設定 Jenkins。 下列各節說明如何在叢集外部設定它。

  1. 在終端機中執行 docker info ，確定已在您的計算機上安裝 Docker。 輸出會指出 Docker 服務是否正在執行。

  2. 如果未安裝 Docker，請執行下列命令：

    sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh

  3. 提取 Service Fabric Jenkins 容器映像︰docker pull rapatchi/jenkins:latest。 此映像隨附 Service Fabric Jenkins 外掛程式預安裝。

  4. 執行容器映像： docker run -itd -p 8080:8080 rapatchi/jenkins:latest

  5. 取得容器映像執行個體的識別碼。 您可以使用命令 docker ps –a 列出所有 Docker 容器

  6. 使用下列步驟登入 Jenkins 入口網站：

    1. 從您的主機登入 Jenkins 殼層。 使用容器標識碼的前四位數。 例如，如果容器識別碼為 2d24a73b5964，請使用 2d24。

      docker exec -it [first-four-digits-of-container-ID] /bin/bash

    2. 從 Jenkins 殼層取得容器實例的管理員密碼：

      cat /var/jenkins_home/secrets/initialAdminPassword

    3. 若要登入 Jenkins 儀錶板，請在網頁瀏覽器中開啟下列 URL： http://<HOST-IP>:8080。 使用上一個步驟中的密碼來解除鎖定 Jenkins。

    4. （選擇性。）第一次登入之後，您可以建立自己的用戶帳戶，並針對下列步驟使用該帳戶，或者您可以繼續使用系統管理員帳戶。 如果您建立使用者，則必須繼續該使用者。

  7. 使用產生新的 SSH 金鑰並將它新增至 SSH 代理程式中的步驟，將 GitHub 設定為使用 Jenkins。

    • 使用 GitHub 所提供的指示來產生 SSH 金鑰，並將 SSH 金鑰新增至裝載存放庫的 GitHub 帳戶。

    • 在 Jenkins Docker 殼層 (而非在主機上) 執行上述連結內所提到的命令。

    • 若要從主機登入 Jenkins 殼層，請使用下列命令：

      docker exec -t -i [first-four-digits-of-container-ID] /bin/bash

請確定裝載 Jenkins 容器映像的叢集或電腦具有公開的 IP 位址。 這可讓 Jenkins 實例接收來自 GitHub 的通知。

設定 Jenkins 之後，請繼續下一節建立 及設定 Jenkins 作業。

建立及設定 Jenkins 作業

本節中的步驟說明如何設定 Jenkins 作業，以回應 GitHub 存放庫中的變更、擷取變更，以及建置變更。 在本節結束時，系統會將您導向至最後的步驟，以根據您要部署至開發/測試環境或生產環境，設定作業以部署應用程式。

  1. 在 Jenkins 儀錶板上，按兩下 [ 新增專案]。

  2. 輸入項目名稱 (例如，MyJob)。 選取 [自由樣式專案]，然後按一下 [確定]。

  3. [作業組態] 頁面隨即開啟。 （若要從 Jenkins 儀錶板取得設定，請按下作業，然後按兩下 設定）。

  4. 在 [ 一般] 索引標籤上，核取 GitHub 專案的方塊，然後指定您的 GitHub 專案 URL。 此 URL 會裝載您想要與 Jenkins 連續整合、連續部署 (CI/CD) 流程整合的 Service Fabric Java 應用程式 (例如，https://github.com/{your-github-account}/service-fabric-java-getting-started)。

  5. 在 [ 原始程式碼管理 ] 索引標籤上，選取 [Git]。 指定存放庫 URL，它會裝載您想要與 Jenkins CI/CD 流程整合的 Service Fabric Java 應用程式 (例如，https://github.com/{your-github-account}/service-fabric-java-getting-started)。 您也可以指定要建置的分支（例如 ， /master。

  6. 設定 GitHub 存放庫以與 Jenkins 交談：

    1. 在 GitHub 存放庫頁面上，移至 設定> Integrations and Services。

    2. 選取 [新增服務]，輸入 Jenkins，然後選取 Jenkins-GitHub 外掛程式。

    3. 輸入您的 Jenkins webhook URL (根據預設，它應該是 http://<PublicIPorFQDN>:8081/github-webhook/)。 按一下 [新增/更新服務]。

    4. 隨即會將測試事件傳送至您的 Jenkins 執行個體。 您應該會在 GitHub 中看到 Webhook 的綠色檢查，而您的專案將會建置。

  7. 在 Jenkins 的 [ 建置觸發程式 ] 索引標籤上，選取您想要的組建選項。 在此範例中，您想要在推送至存放庫時觸發組建，因此請選取 GITScm 輪詢的 GitHub 攔截觸發程式。 （先前已呼叫 此選項將變更推送至 GitHub 時建置。

  8. 在 [ 建置] 索引標籤上，根據您要建置 Java 應用程式或 .NET Core 應用程式，執行下列其中一項：

    • 針對 Java 應用程式： 從 [ 新增建置步驟 ] 下拉式清單中，選取 [ 叫用 Gradle 腳本]。 按一下進階。 在進階功能表中，指定應用程式的根建置腳本路徑。 它會從指定的路徑挑選 build.gradle，並據以運作。 針對 ActorCounter 應用程式，這是：${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter。

      Service Fabric Jenkins 建置動作

    • 針對 .NET Core 應用程式： 從 [ 新增建置步驟 ] 下拉式清單中，選取 [ 執行殼層]。 在出現的命令方塊中，必須先將目錄變更為檔案所在的 build.sh 路徑。 一旦目錄變更之後， build.sh 就可以執行腳本來建置應用程式。

      cd /var/jenkins_home/workspace/[Job Name]/[Path to build.sh]  
./build.sh

      下列螢幕快照顯示用來建置具有 Jenkins 作業名稱CounterServiceApplication之計數器服務範例的命令範例。

      用來建置服務的命令範例

  9. 若要將 Jenkins 設定為在建置後動作中將您的應用程式部署到 Service Fabric 叢集，您需要該叢集憑證在 Jenkins 容器中的位置。 根據您的 Jenkins 容器是否在叢集內部或外部執行，選擇下列其中一項，並記下叢集憑證的位置：

    • 對於在叢集內執行的 Jenkins：您可以從容器內回應Certificates_JenkinsOnSF_Code_MyCert_PEM環境變數的值，找到憑證的路徑。

      echo $Certificates_JenkinsOnSF_Code_MyCert_PEM

    • 針對在叢集外部執行的 Jenkins： 請遵循下列步驟，將叢集憑證複製到您的容器：

      1. 您的憑證必須是 PEM 格式。 如果您沒有 PEM 檔案，您可以從憑證 PFX 檔案建立一個檔案。 如果您的 PFX 檔案未受到密碼保護，請從主機執行下列命令：

        openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:

        如果 PFX 檔案受到密碼保護，請在 參數中包含 -passin 密碼。 例如：

        openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:<password>

      2. 若要取得 Jenkins 容器的容器識別碼，請從主機執行 docker ps 。

      3. 使用下列 Docker 命令將 PEM 檔案複製到您的容器：

        docker cp clustercert.pem [first-four-digits-of-container-ID]:/var/jenkins_home

你快完成了！ 讓 Jenkins 作業保持開啟。 唯一剩餘的工作是設定建置後步驟，以將應用程式部署至 Service Fabric 叢集：

  • 若要部署至開發或測試環境，請遵循使用叢集管理端點設定部署中的步驟。
  • 若要部署至生產環境，請遵循使用 Azure 認證設定部署中的步驟。

使用叢集管理端點設定部署

針對開發和測試環境，您可以使用叢集管理端點來部署應用程式。 使用叢集管理端點設定建置後動作以部署您的應用程式，需要最少的設定。 如果您要部署至生產環境，請跳到 使用 Azure 認證 設定部署，以設定部署期間要使用的 Microsoft Entra 服務主體。

  1. 在 Jenkins 作業中，按兩下 [建置後動作 ] 索引標籤。

  2. 從 [建置後動作] 下拉式清單，選取 [部署 Service Fabric 專案]。

  3. 在 [Service Fabric 叢集組態] 下，選取 [填入 Service Fabric 管理端點] 單選按鈕。

  4. 針對 [ 管理主機]，輸入叢集的連線端點，例如 {your-cluster}.eastus.cloudapp.azure.com。

  5. 針對 [用戶端金鑰 ] 和 [用戶端憑證]，輸入 Jenkins 容器中 PEM 檔案的位置，例如 /var/jenkins_home/clustercert.pem。 （您已將憑證的位置複製到最後一個步驟 建立及設定 Jenkins 作業。

  6. 在 [應用程式組態] 底下，設定 [應用程式名稱]、[應用程式類型] 和 [應用程式指令清單] 欄位的 [相對] 路徑。

    Service Fabric Jenkins 建置後動作設定管理端點

  7. 按兩下 [ 驗證組態]。 在成功驗證時，按兩下 [ 儲存]。 您的 Jenkins 作業管線現在已完全設定。 請跳到 後續步驟 以測試您的部署。

使用 Azure 認證設定部署

針對生產環境，強烈建議您將 Azure 認證設定為部署應用程式。 本節說明如何設定 Microsoft Entra 服務主體，以在建置後動作中用來部署您的應用程式。 您可以將服務主體指派給目錄中的角色，以限制 Jenkins 作業的許可權。

針對開發和測試環境，您可以設定 Azure 認證或叢集管理端點來部署應用程式。 如需如何設定叢集管理端點的詳細資訊，請參閱 使用叢集管理端點設定部署。

  1. 若要建立 Microsoft Entra 服務主體並在 Azure 訂用帳戶中指派許可權，請遵循使用入口網站建立 Microsoft Entra 應用程式和服務主體中的步驟。 請注意下列事項：

    • 遵循主題中的步驟時，請務必複製並儲存下列值：應用程式識別碼、應用程式密鑰、目錄識別碼（租使用者標識元）和訂用帳戶標識碼。 您需要這些認證才能在 Jenkins 中設定 Azure 認證。
    • 如果您沒有目錄的必要許可權，您必須要求系統管理員授與您許可權或為您建立服務主體，或者您必須在 Jenkins 中為您的作業的建置後動作中設定叢集的管理端點。
    • 在 [ 建立 Microsoft Entra] 應用程式 區段中，您可以輸入任何格式 正確的登入 URL。
    • 在 [ 將應用程式指派給角色 ] 區段中，您可以將應用程式 指派給叢集資源群組上的讀取者 角色。

  2. 回到 Jenkins 作業，按兩下 [建置後動作 ] 索引標籤。

  3. 從 [建置後動作] 下拉式清單，選取 [部署 Service Fabric 專案]。

  4. 在 [Service Fabric 叢集組態] 底下，按兩下 [選取 Service Fabric 叢集]。 按兩下 [Azure 認證] 旁的 [新增]。 按兩下 [Jenkins ] 以選取 Jenkins 認證提供者。

  5. 在 Jenkins 認證提供者中，從 [種類] 下拉式清單中選取 [Microsoft Azure 服務主體]。

  6. 使用您在步驟 1 中設定服務主體時儲存的值來設定下列欄位：

    • 用戶端識別碼： 應用程式識別碼
    • 用戶端密碼： 應用程式金鑰
    • 租用戶標識碼： 目錄標識碼
    • 訂用帳戶標識碼： 訂用帳戶標識碼

  7. 輸入您在 Jenkins 中用來選取認證的描述性 識別碼 和簡短 描述。 然後按兩下 [ 驗證服務主體]。 如果驗證成功，請按兩下 [ 新增]。

    Service Fabric Jenkins 輸入 Azure 認證

  8. 回到 Service Fabric 叢集組態底下，確定已針對 Azure 認證選取您的新認證。

  9. 從 [ 資源群組 ] 下拉式清單中，選取您要部署應用程式之叢集的資源群組。

  10. 從 [ Service Fabric] 下拉式清單中，選取您要部署應用程式的叢集。

  11. 針對 [用戶端金鑰 ] 和 [用戶端憑證]，輸入 Jenkins 容器中 PEM 檔案的位置。 例如 /var/jenkins_home/clustercert.pem 。

  12. 在 [應用程式組態] 底下，設定 [應用程式名稱]、[應用程式類型] 和 [應用程式指令清單] 欄位的 [相對] 路徑。 Service Fabric Jenkins 建置後動作 - 設定 Azure 認證

  13. 按兩下 [ 驗證組態]。 在成功驗證時，按兩下 [ 儲存]。 您的 Jenkins 作業管線現在已完全設定。 繼續執行 後續步驟 以測試您的部署。

針對 Jenkins 外掛程式進行疑難解答

如果您在 Jenkins 外掛程式遇到任何 Bug，請在 Jenkins JIRA 中針對特定元件提出問題。

嘗試的想法

現在已設定 GitHub 和 Jenkins。 請考慮在存放庫分支的項目reliable-services-actor-sample/Actors/ActorCounter中進行一些範例變更。 https://github.com/Azure-Samples/service-fabric-java-getting-started 將您的變更推送至遠端 master 分支（或您已設定為使用的任何分支）。 這會觸發您設定的 Jenkins 作業 MyJob。 它會從 GitHub 擷取變更、加以建置，並將應用程式部署到您在建置後動作中指定的叢集。

下一步

Azure 上的 Jenkins