教學課程:使用 Jenkins 外掛程式部署到 Azure App ServiceTutorial: Deploy to Azure App Service using the Jenkins plugin

若要將 Java Web 應用程式部署到 Azure,您可以在 Jenkins 管線中使用 Azure CLI,或者,也可以使用 Azure App Service Jenkins 外掛程式To deploy a Java web app to Azure, you can use the Azure CLI in Jenkins Pipeline or you can use the Azure App Service Jenkins plugin. Jenkins 外掛程式 1.0 版支援使用 Azure App Service 的 Web Apps 功能來進行連續部署:The Jenkins plugin version 1.0 supports continuous deployment by using the Web Apps feature of Azure App Service:

  • 檔案上傳。File upload.
  • 適用於 Linux 上 Web Apps 的 Docker。Docker for Web Apps on Linux.

在本教學課程中,您會了解如何:In this tutorial, you learn how to:

  • 設定 Jenkins 以透過檔案上傳來部署 Web 應用程式。Configure Jenkins to deploy Web Apps through file upload.
  • 設定 Jenkins 以部署適用於容器的 Web Apps。Configure Jenkins to deploy Web App for Containers.

先決條件Prerequisites

  • Azure 訂用帳戶:如果您沒有 Azure 訂用帳戶,請在開始前建立免費帳戶Azure subscription: If you don't have an Azure subscription, create a free account before you begin.

Jenkins - 在 Linux VM 上安裝 JenkinsJenkins - Install Jenkins on a Linux VM

建立及設定 Jenkins 執行個體Create and configure a Jenkins instance

在 Jenkins 安裝上,確定已安裝下列外掛程式:On your Jenkins installation, ensure that the following plugins are installed:

您可以使用 Jenkins 外掛程式來部署 Web Apps 所支援、以任何語言 (例如 C#、PHP、Python、Java 及 Node.js) 撰寫的 Web 應用程式。You can use the Jenkins plugin to deploy a web app in any language that is supported by Web Apps, such as C#, PHP, Python, Java, and Node.js. 在本教學課程中,我們會使用適用於 Azure 的簡單 Java Web 應用程式In this tutorial, we use a simple Java web app for Azure. 若要將儲存機制分支到您自己的 GitHub 帳戶,請選取 GitHub 介面右上角的 [Fork] (分支) 按鈕。To fork the repo to your own GitHub account, select the Fork button in the upper right corner of the GitHub interface.

必須要有 Java JDK 和 Maven,才能建置 Java 專案。The Java JDK and Maven are required to build the Java project. 如果您使用代理程式來進行持續整合,請將這些元件安裝在 Jenkins Master 上。Install these components on the Jenkins Master, or on the VM agent if you use the agent for continuous integration. 如果您要部署 Java SE 應用程式,組建伺服器上還需要有 ZIP。If you are deploying a Java SE application, ZIP is also needed on the build server.

若要安裝這些元件,請使用 SSH 登入 Jenkins 執行個體,然後執行下列命令:To install the components, sign in to the Jenkins instance with SSH and run the following commands:

sudo apt-get install -y openjdk-7-jdk
sudo apt-get install -y maven

若要部署到「適用於容器的 Web App」,請在 Jenkins Master 上或在用於組建的 VM 代理程式上安裝 Docker。To deploy to Web App for Containers, install Docker on the Jenkins Master or on the VM agent that is used for the build. 如需相關指示,請參閱在 Ubuntu 上安裝 Docker (英文)。For instructions, see Install Docker on Ubuntu.

將 Azure 服務主體新增到 Jenkins 認證Add an Azure service principal to the Jenkins credentials

您必須要有 Azure 服務主體,才能部署到 Azure。You need an Azure service principal to deploy to Azure.

  1. 若要建立 Azure 服務主體,請使用 Azure CLI 或 Azure 入口網站To create an Azure service principal, use the Azure CLI or the Azure portal.

  2. 在 Jenkins 儀表板上,選取 [Credentials] (認證) > [System] (系統) 。On the Jenkins dashboard, select Credentials > System. 然後,選取 [Global credentials(unrestricted)] (全域認證 (不受限)) 。Then, select Global credentials(unrestricted).

  3. 若要新增 Microsoft Azure 服務主體,請選取 [新增認證] 。To add a Microsoft Azure service principal, select Add Credentials. 為 [訂用帳戶 ID] 、[用戶端識別碼] 、[用戶端密碼] 及 [OAuth 2.0 權杖端點] 欄位輸入值。Supply values for the Subscription ID, Client ID, Client Secret, and OAuth 2.0 Token Endpoint fields. 將 [識別碼] 欄位設定為 mySpSet the ID field to mySp. 我們會在本文的後續步驟中用到此識別碼。We use this ID in subsequent steps in this article.

設定 Jenkins 以透過上傳檔案來部署應用程式Configure Jenkins to deploy Web Apps by uploading files

若要將專案部署到 Web Apps,您可以透過檔案上傳來上傳組建成品。To deploy your project to Web Apps, you can upload your build artifacts by file upload. Azure App Service 支援多個部署選項。Azure App Service supports multiple deployment options. Azure App Service Jenkins 外掛程式可讓您輕鬆使用根據檔案類型所衍生的部署選項。The Azure App Service Jenkins plugin makes it simple for you and derives the deployment option based on the file type.

在於 Jenkins 中設定作業之前,您必須要有 Azure App Service 方案和 Web 應用程式,才能執行 Java 應用程式。Before you set up the job in Jenkins, you need an Azure App Service plan and a web app to run the Java app.

  1. 使用 az appservice plan create Azure CLI 命令建立使用免費定價層的 Azure App Service 方案。Create an Azure App Service plan with the FREE pricing tier by using the az appservice plan create Azure CLI command. App Service 方案會定義用來裝載您應用程式的實體資源。The App Service plan defines the physical resources that are used to host your apps. 指派給 App Service 方案的所有應用程式會共用這些資源。All applications that are assigned to an App Service plan share these resources. 共用資源可協助您在裝載多個應用程式時節省成本。Shared resources help you to save on costs when hosting multiple apps.

  2. 建立 Web 應用程式。Create a web app. 您可以使用 Azure 入口網站 或下列 az Azure CLI 命令:You can use the Azure portal or the following az Azure CLI command:

    az webapp create --name <myAppName> --resource-group <myResourceGroup> --plan <myAppServicePlan>
    
  3. 設定您應用程式所需的 Java 執行階段組態。Set up the Java runtime configuration that your app needs. 下列 Azure CLI 命令會將 Web 應用程式設定為在最新的 JDK 8 和 Apache Tomcat 8.0 版上執行:The following Azure CLI command configures the web app to run on a recent JDK 8 and Apache Tomcat version 8.0:

    az webapp config set \
    --name <myAppName> \
    --resource-group <myResourceGroup> \
    --java-version 1.8 \
    --java-container Tomcat \
    --java-container-version 8.0
    

設定 Jenkins 作業Set up the Jenkins job

  1. 在 Jenkins 儀表板上建立新的自由樣式專案。Create a new freestyle project on the Jenkins Dashboard.

  2. 將 [Source Code Management] (原始程式碼管理) 欄位設定為使用您的適用於 Azure 的簡單 Java Web 應用程式本機分支。Configure the Source Code Management field to use your local fork of the simple Java web app for Azure. 提供 [Repository URL] (儲存機制 URL) 值。Provide the Repository URL value. 例如:http://github.com/<your_ID>/javawebappsample。For example: http://github.com/<your_ID>/javawebappsample.

  3. 使用 Maven 藉由新增執行 shell 命令來新增一個建置專案的步驟。Add a step to build the project by using Maven by adding the Execute shell command. 在此範例中,我們需要一個額外的命令來將目標資料夾中的 *.war 檔案重新命名為 ROOT.warFor this example, we need an additional command to rename the *.war file in the target folder to ROOT.war:

    mvn clean package
    mv target/*.war target/ROOT.war
    
  4. 選取 [發行 Azure Web 應用程式] 來新增建置後動作。Add a post-build action by selecting Publish an Azure Web App.

  5. 輸入 mySp 作為 Azure 服務主體。Supply mySp as the Azure service principal. 此主體在先前的步驟中已儲存為 Azure 認證This principal was stored as the Azure Credentials in a previous step.

  6. 在 [應用程式組態] 區段中,選擇您訂用帳戶中的資源群組和 Web 應用程式。In the App Configuration section, choose the resource group and web app in your subscription. Jenkins 外掛程式會自動偵測 Web 應用程式是採用 Windows 架構還是 Linux 架構。The Jenkins plugin automatically detects whether the web app is based on Windows or Linux. 若為 Windows Web 應用程式,就會顯示 [發行檔案] 選項。For a Windows web app, the Publish Files option is presented.

  7. 填入您要部署的檔案。Fill in the files that you want to deploy. 例如,如果您使用 Java,請指定 WAR 套件。For example, specify the WAR package if you're using Java. 使用選擇性的 [來源目錄] 和 [目標目錄] 參數來指定用於上傳檔案的來源和目標資料夾。Use the optional Source Directory and Target Directory parameters to specify the source and target folders to use for file upload. Azure 上的 Java Web 應用程式會在 Tomcat 伺服器中執行。The Java web app on Azure is run in a Tomcat server. 因此,就 Java 而言,您需將 WAR 套件上傳到 [webapps] 資料夾。So for Java, you upload your WAR package to the webapps folder. 在此範例中,請將 [來源目錄] 值設定為 target,將 [目標目錄] 值設定為 webappsFor this example, set the Source Directory value to target and the Target Directory value to webapps.

  8. 如果您想要部署到生產環境以外的位置,您也可以設定 [位置] 名稱。If you want to deploy to a slot other than production, you can also set the Slot name.

  9. 儲存專案並建置該專案。Save the project and build it. 建置完成時,您的 Web 應用程式就會部署到 Azure。Your web app is deployed to Azure when the build is complete.

透過使用 Jenkins 管線上傳檔案來部署 Web 應用程式Deploy Web Apps by uploading files using Jenkins Pipeline

Azure App Service Jenkins 外掛程式是符合管線需求的外掛程式。The Azure App Service Jenkins plugin is pipeline-ready. 您可以參考以下 GitHub 儲存機制中的範例。You can refer to the following sample in the GitHub repo.

  1. 在 GitHub 介面中,開啟 Jenkinsfile_ftp_plugin 檔案。In the GitHub interface, open the Jenkinsfile_ftp_plugin file. 若要編輯此檔案,請選取鉛筆圖示。To edit the file, select the pencil icon. 針對您的 Web 應用程式,分別更新第 11 行和第 12 行上的 resourceGroupwebAppName 定義:Update the resourceGroup and webAppName definitions for your web app on lines 11 and 12, respectively:

    def resourceGroup = '<myResourceGroup>'
    def webAppName = '<myAppName>'
    
  2. 將第 14 行上的 withCredentials 定義設定為您 Jenkins 執行個體中的認證識別碼:Set the withCredentials definition on line 14 to the credential ID in your Jenkins instance:

    withCredentials([azureServicePrincipal('<mySp>')]) {
    

建立 Jenkins 管線Create a Jenkins pipeline

  1. 在網頁瀏覽器中開啟 Jenkins。Open Jenkins in a web browser. 選取 [新增項目] 。Select New Item.

  2. 為作業提供一個名稱,然後選取 [Pipeline] (管線) 。Provide a name for the job and select Pipeline. 選取 [確定] 。Select OK.

  3. 選取 [Pipeline] (管線) 索引標籤。Select the Pipeline tab.

  4. 針對 [Definition] (定義) 值,選取 [Pipeline script from SCM] (來自 SCM 的管線指令碼) 。For the Definition value, select Pipeline script from SCM.

  5. 針對 [SCM] 值,選取 [Git] 。For the SCM value, select Git. 輸入您分支儲存機制的 GitHub URL。Enter the GitHub URL for your forked repo. 例如: https://<your_forked_repo>.git。For example: https://<your_forked_repo>.git.

  6. 將 [Script Path] (指令碼路徑) 值更新成 Jenkinsfile_ftp_pluginUpdate the Script Path value to Jenkinsfile_ftp_plugin.

  7. 按一下 [Save] (儲存) 並執行作業。Select Save and run the job.

設定 Jenkins 以部署適用於容器的 Web AppConfigure Jenkins to deploy Web App for Containers

Linux 上的 Web Apps 支援使用 Docker 來進行部署。Web Apps on Linux supports deployment by using Docker. 若要使用 Docker 來部署您的 Web 應用程式,您必須提供一個 Dockerfile,此檔案會將您的 Web 應用程式與服務執行階段封裝成 Docker 映像。To deploy your web app by using Docker, you need to provide a Dockerfile that packages your web app with a service runtime into a Docker image. 接著,Jenkins 外掛程式會建置該映像,將它推送到 Docker 登錄,然後將該映像部署到您的 Web 應用程式。The Jenkins plugin then builds the image, pushes it to a Docker registry, and deploys the image to your web app.

Linux 上的 Web Apps 也支援 Git 和檔案上傳等傳統部署方法,但僅適用於內建語言 (.NET Core、Node.js、PHP 和 Ruby)。Web Apps on Linux also supports traditional deployment methods, like Git and file upload, but only for built-in languages (.NET Core, Node.js, PHP, and Ruby). 若為其他語言,則需要將您的應用程式程式碼和服務執行階段一起封裝到 Docker 映像,然後使用 Docker 來部署。For other languages, you need to package your application code and service runtime together into a Docker image and use Docker to deploy.

在於 Jenkins 中設定作業之前,您必須在 Linux 上擁有一個 Web 應用程式。Before setting up the job in Jenkins, you need a web app on Linux. 您還需要有一個容器登錄,以便儲存和管理您的私人 Docker 容器映像。You also need a container registry to store and manage your private Docker container images. 您可以使用 DockerHub 來建立容器登錄。You can use DockerHub to create the container registry. 在此範例中,我們使用 Azure Container Registry。In this example, we use Azure Container Registry.

設定 Docker 的 Jenkins 作業Set up the Jenkins job for Docker

  1. 在 Jenkins 儀表板上建立新的自由樣式專案。Create a new freestyle project on the Jenkins Dashboard.

  2. 將 [Source Code Management] (原始程式碼管理) 欄位設定為使用您的適用於 Azure 的簡單 Java Web 應用程式本機分支。Configure the Source Code Management field to use your local fork of the simple Java web app for Azure. 提供 [Repository URL] (儲存機制 URL) 值。Provide the Repository URL value. 例如:http://github.com/<your_ID>/javawebappsample。For example: http://github.com/<your_ID>/javawebappsample.

  3. 使用 Maven 藉由新增執行 shell 命令來新增一個建置專案的步驟。Add a step to build the project by using Maven by adding an Execute shell command. 在命令中包含下列一行:Include the following line in the command:

    mvn clean package
    
  4. 選取 [發行 Azure Web 應用程式] 來新增建置後動作。Add a post-build action by selecting Publish an Azure Web App.

  5. 輸入 mySp 作為 Azure 服務主體。Supply mySp as the Azure service principal. 此主體在先前的步驟中已儲存為 Azure 認證This principal was stored as the Azure Credentials in a previous step.

  6. 在 [應用程式組態] 區段中,選擇您訂用帳戶中的資源群組和 Linux Web 應用程式。In the App Configuration section, choose the resource group and a Linux web app in your subscription.

  7. 選擇 [透過 Docker 發行] 。Choose Publish via Docker.

  8. 填寫 Dockerfile 路徑值。Fill in the Dockerfile path value. 您可以保留預設值 /Dockerfile。You can keep the default value /Dockerfile. 針對 [Docker 登錄 URL] 值,如果您使用 Azure Container Registry,請使用 https://<yourRegistry>.azurecr.io 格式來輸入 URL。For the Docker registry URL value, supply the URL by using the format https://<yourRegistry>.azurecr.io if you use Azure Container Registry. 如果您使用 DockerHub,請將值保留空白。If you use DockerHub, leave the value blank.

  9. 針對 [登錄認證] 值,新增容器登錄的認證。For the Registry credentials value, add the credential for the container registry. 您可以在 Azure CLI 中執行下列命令,以取得使用者識別碼和密碼。You can get the userid and password by running the following commands in the Azure CLI. 第一個命令會啟用系統管理員帳戶:The first command enables the administrator account:

    az acr update -n <yourRegistry> --admin-enabled true
    az acr credential show -n <yourRegistry>
    
  10. [進階] 索引標籤中的 Docker 映像名稱和標記值是選擇性的值。The Docker image name and tag value in the Advanced tab are optional. 預設會從您在 Azure 入口網站的 [Docker 容器] 設定中 中設定的映像名稱,取得映像名稱的值。By default, the value for the image name is obtained from the image name that you configured in the Azure portal in the Docker Container setting. 標記會從 $BUILD_NUMBER 產生。The tag is generated from $BUILD_NUMBER. 在 Azure 入口網站中指定映像名稱,或是在 [進階] 索引標籤中提供 [Docker 映像] 值。針對此範例,請將 [Docker 映像] 值設定為 <your_Registry>.azurecr.io/calculator,並將 [Docker 映像標記] 值保留空白。Specify the image name in the Azure portal or supply a Docker Image value in the Advanced tab. For this example, set the Docker image value to <your_Registry>.azurecr.io/calculator and leave the Docker Image Tag value blank.

  11. 如果您使用內建的 Docker 映像設定,部署將會失敗。The deploy fails if you use a built-in Docker image setting. 請在 Azure 入口網站的 [Docker 容器] 設定中,將 Docker 組態變更為使用自訂映像。Change the Docker configuration to use a custom image in the Docker Container setting in the Azure portal. 針對內建映像,請使用檔案上傳方法來進行部署。For a built-in image, use the file upload approach to deploy.

  12. 與檔案上傳方法類似,您也可以選擇生產環境以外的不同位置Similar to the file upload approach, you can choose a different Slot name other than production.

  13. 儲存並建置專案。Save and build the project. 系統會將您的容器映像推送到登錄中,並且部署 Web 應用程式。Your container image is pushed to your registry and the web app is deployed.

使用 Jenkins 管線來部署適用於容器的 Web AppDeploy Web App for Containers by using Jenkins Pipeline

  1. 在 GitHub 介面中,開啟 Jenkinsfile_container_plugin 檔案。In the GitHub interface, open the Jenkinsfile_container_plugin file. 若要編輯此檔案,請選取鉛筆圖示。To edit the file, select the pencil icon. 針對您的 Web 應用程式,分別更新第 11 行和第 12 行上的 resourceGroupwebAppName 定義:Update the resourceGroup and webAppName definitions for your web app on lines 11 and 12, respectively:

    def resourceGroup = '<myResourceGroup>'
    def webAppName = '<myAppName>'
    
  2. 將第 13 行變更為您的容器登錄伺服器:Change line 13 to your container registry server:

    def registryServer = '<registryURL>'
    
  3. 將第 16 行變更為使用您 Jenkins 執行個體中的認證識別碼:Change line 16 to use the credential ID in your Jenkins instance:

    azureWebAppPublish azureCredentialsId: '<mySp>', publishType: 'docker', resourceGroup: resourceGroup, appName: webAppName, dockerImageName: imageName, dockerImageTag: imageTag, dockerRegistryEndpoint: [credentialsId: 'acr', url: "http://$registryServer"]
    

建立 Jenkins 管線Create a Jenkins pipeline

  1. 在網頁瀏覽器中開啟 Jenkins。Open Jenkins in a web browser. 選取 [新增項目] 。Select New Item.

  2. 為作業提供一個名稱,然後選取 [Pipeline] (管線) 。Provide a name for the job and select Pipeline. 選取 [確定] 。Select OK.

  3. 選取 [Pipeline] (管線) 索引標籤。Select the Pipeline tab.

  4. 針對 [Definition] (定義) 值,選取 [Pipeline script from SCM] (來自 SCM 的管線指令碼) 。For the Definition value, select Pipeline script from SCM.

  5. 針對 [SCM] 值,選取 [Git] 。For the SCM value, select Git. 輸入您分支儲存機制的 GitHub URL。Enter the GitHub URL for your forked repo. 例如:https://&lt;your_forked_repo>.git.For example: https://&lt;your_forked_repo>.git.

  6. 將 [Script Path] (指令碼路徑) 值更新成 Jenkinsfile_container_pluginUpdate the Script Path value to Jenkinsfile_container_plugin.

  7. 按一下 [Save] (儲存) 並執行作業。Select Save and run the job.

確認您的 Web 應用程式Verify your web app

  1. 若要確認 WAR 檔案是否已順利部署到您的 Web 應用程式,請開啟網頁瀏覽器。To verify that the WAR file is deployed successfully to your web app, open a web browser. 前往 http://&lt;your_app_name>.azurewebsites.net/api/calculator/pingGo to http://&lt;your_app_name>.azurewebsites.net/api/calculator/ping. 以 Web 應用程式名稱取代 &lt;your_app_name>Replace &lt;your_app_name> with the name of your web app. 您會看到下列訊息:You see the following message:

    Welcome to Java Web App!!! This is updated!
    Sun Jun 17 16:39:10 UTC 2017
    
  2. 前往 http://&lt;your_app_name>.azurewebsites.net/api/calculator/add?x=&lt;x>&y=&lt;y>Go to http://&lt;your_app_name>.azurewebsites.net/api/calculator/add?x=&lt;x>&y=&lt;y>. 以任意數字取代 &lt;x> and &lt;y> 來得出 x + y 的總和。Replace &lt;x> and &lt;y> with any numbers to get the sum of x + y. 計算機會顯示總和:The calculator shows the sum:

    計算機:加法

針對 Linux 上的 Azure App ServiceFor Azure App Service on Linux

  1. 若要確認您的 Web 應用程式,請在 Azure CLI 中執行下列命令:To verify your web app, run the following command in the Azure CLI:

    az acr repository list -n <myRegistry> -o json
    

    隨即會顯示下列訊息:The following message is displayed:

    ["calculator"]
    
  2. 前往 http://&lt;your_app_name>.azurewebsites.net/api/calculator/pingGo to http://&lt;your_app_name>.azurewebsites.net/api/calculator/ping. 以 Web 應用程式名稱取代 &lt;your_app_name>Replace &lt;your_app_name> with the name of your web app. 您會看到下列訊息:You see the following message:

    Welcome to Java Web App!!! This is updated!
    Sun Jul 09 16:39:10 UTC 2017
    
  3. 前往 http://&lt;your_app_name>.azurewebsites.net/api/calculator/add?x=&lt;x>&y=&lt;y>Go to http://&lt;your_app_name>.azurewebsites.net/api/calculator/add?x=&lt;x>&y=&lt;y>. 以任意數字取代 &lt;x> and &lt;y> 來得出 x + y 的總和。Replace &lt;x> and &lt;y> with any numbers to get the sum of x + y.

對 Jenkins 外掛程式進行疑難排解Troubleshooting the Jenkins plugin

如果您遇到任何有關 Jenkins 外掛程式的錯誤,請在 Jenkins JIRA 的特定元件中提交問題。If you encounter any bugs with the Jenkins plugins, file an issue in the Jenkins JIRA for the specific component.

後續步驟Next steps