練習：建立在 Azure 上執行的組建代理程式

20 分鐘

在此單元中，若要設定可在 Microsoft Azure Pipelines 中使用的組建代理程式，您將使用在 Microsoft Azure 上執行的虛擬機。我們會提供可在此課程模組期間使用的虛擬機器。

在本單元中，您將會：

在 Azure 上建立 Ubuntu 虛擬機器，作為組建代理程式。
在 Microsoft Azure DevOps 中建立代理程式集區。
建立用來向 Azure DevOps 驗證您代理程式的存取權杖。
為您的代理程式設定組建 Space Game 網站所需的軟體。
設定代理程式以連線至 Azure DevOps，使其能夠接收組建作業。
確認代理程式已連線至 Azure DevOps，且已準備好要接收組建作業。

您可以使用許多方法，在 Azure 上建立虛擬機器。在本單元中，您將使用名為 Cloud Shell 的互動式終端機來建立 Ubuntu 虛擬機。

您有多種選擇可設定您的 VM：

針對 Linux VM，您可以透過 SSH 直接連線，並以互動方式設定您的系統。
您可以使用 ARM 範本、Bicep 或其他自動化佈建工具，將部署自動化。
如果您要部署多個組建代理程式，您可以建立已預先安裝所有軟體的 VM 映像。

首先，建議您以互動方式設定系統，因為這有助於您了解相關程序和所需的項目。為了簡化程序，請透過 SSH 連線至您的 Ubuntu VM，並執行殼層指令碼以設定組建代理程式。

注意

如果您不熟悉如何連線或設定 Linux 系統，請依照指示操作。您可以將相同的概念套用至 Windows 組建代理程式。

建立 Linux 虛擬機器

在此節中，您要建立執行 Ubuntu 20.04 的 VM，此 VM 將作為您的組建代理程式。此 VM 還未設定為組建代理程式，也尚無任何組建 Space Game Web 應用程式所需的工具。您將在稍後進行該設定。

透過 Azure 入口網站啟動 Cloud Shell

重要

若要完成本課程模組中的練習，您需要有自己的 Azure 訂用帳戶。

請前往 Azure 入口網站並登入。
從功能表中，選取 [Cloud Shell]。當出現提示時，請選取 Bash 體驗。

注意

Cloud Shell 需要有 Azure 儲存體資源，才能保存您在 Cloud Shell 中建立的任何檔案。當第一次開啟 Cloud Shell 時，系統會提示您建立資源群組、儲存體帳戶和 Azure 檔案儲存體共用。所有未來的 Cloud Shell 工作階段都會自動使用此設定。

選取 Azure 區域

「區域」是地理位置內的一或多個 Azure 資料中心。美國東部、美國西部和歐洲北部都是區域範例。每個 Azure 資源 (包括 Azure VM) 都會被指派一個區域。

若要讓命令更容易執行，請從選取預設區域開始。在您指定預設區域之後，除非您指定不同的區域，否則稍後的命令都會使用該區域。

從 Cloud Shell，若要列出 Azure 訂用帳戶中可用的區域，請執行下列 az account list-locations 命令：
```
az account list-locations \
  --query "[].{Name: name, DisplayName: displayName}" \
  --output table
```
從輸出中的 Name 資料行，選取接近您的區域。例如，選擇 eastasia 或 westus2。
執行 az configure 以設定您的預設區域。 <REGION>取代為您選擇的區域名稱：
```
az configure --defaults location=<REGION>
```
此範例會將 westus2 設定為預設區域：
```
az configure --defaults location=westus2
```

建立資源群組

建立一個資源群組，以包含本訓練課程模組中所用的資源。

若要建立名為 tailspin-space-game-rg 的資源群組，請執行下列 az group create 命令：
```
az group create --name tailspin-space-game-rg
```

建立 VM

若要建立 VM，請執行下列 az vm create 命令：

az vm create \
    --name MyLinuxAgent \
    --resource-group tailspin-space-game-rg \
    --image canonical:0001-com-ubuntu-server-focal:20_04-lts:latest \
    --size Standard_DS2_v2 \
    --admin-username azureuser \
    --generate-ssh-keys

您的 VM 需要幾分鐘的時間才會啟動。

Standard_DS2_v2 會指定 VM 的大小。 VM 的大小會定義其處理器速度、記憶體數量、初始的儲存體數量，以及預期的網路頻寬。此大小與 Microsoft 裝載的代理程式所提供的相同。在實務上，您可以選擇可提供更多計算能力或額外功能 (例如圖形處理) 的大小。

--resource-group 引數會指定「資源群組」，用以保存我們需要建立的所有項目。資源群組可讓您管理將我們解決方案建構為一個單元的所有 VM、磁碟、網路介面以及其他元素。

建立代理程式集區

回想一下，代理程式集區會組織組建代理程式。在本節中，您將在 Azure DevOps 中建立代理程式集區。稍後，您將在設定代理程式時指定代理程式集區的名稱，使其能夠將本身註冊到正確的集區。

在 Azure DevOps 中，前往 Space Game - web - Agent 專案。
選取 [專案設定]。
在 [管線] 下方，選取 [代理程式集區]。
選取 [新增集區]。
在 [新增集區] 視窗中：
1. 在 [要連結的集區] 下，選取 [新增]。
2. 在 [集區類型] 下，選取 [自我裝載]。
3. 在 [名稱] 下，輸入 MyAgentPool。
實際上，您會為集區選擇更具描述性的名稱。
選取建立。新的代理程式集區隨即會出現在清單中。

建立個人存取權杖

為了讓組建代理程式註冊至 Azure DevOps，您必須以某種方式讓其進行自我驗證。

若要這樣做，您可以建立個人存取令牌。個人存取令牌或 PAT 是密碼的替代方案。您可以使用 PAT 來向服務 (例如 Azure DevOps) 進行驗證。

重要

與密碼的處理方式相同，請務必將您的存取權杖置於安全之處。在本節中，您會將存取令牌儲存為環境變數，使其不會出現在殼層腳本中。

在 Azure DevOps 中，開啟配置檔設定，然後選取 [ 個人存取令牌]。
選取 [新增權杖]。
輸入權杖的名稱，例如組建代理程式。
在 [ 範圍] 下，選取底部的 [顯示所有範圍 ] 連結。
尋找 代理程式集區，然後選取 [讀取及管理]。
選取建立。
將權杖複製到安全之處。

稍後，您將使用權杖讓組建代理程式驗證對 Azure Pipelines 的存取。

連接到您的 VM

在本節中，您將透過 SSH 連線到 Linux VM，以便進行設定。

別忘了，您無法以互動方式登入 Microsoft 裝載的代理程式。由於私人組建代理程式屬於您自己，因此您可以登入並任意設定。

線上到組建代理程式的功能可讓您使用建置軟體所需的工具進行設定。它也可讓您在建置管線組態時針對問題進行疑難解答。

若要取得 VM 的 IP 位址，請在 Cloud Shell 中執行 az vm show ：

IPADDRESS=$(az vm show \
  --name MyLinuxAgent \
  --resource-group tailspin-space-game-rg \
  --show-details \
  --query [publicIps] \
  --output tsv)

此命令會將 IP 位址儲存在名為 IPADDRESS 的 Bash 變數中。

將 VM 的 IP 位址列印至主控台：
```
echo $IPADDRESS
```
建立針對您 VM 的 SSH 連線。在 $IPADDRESS 所在位置，輸入您在上一個步驟中收到的 IP 位址。出現提示時，輸入 yes 以繼續連線。
```
ssh azureuser@$IPADDRESS
```
您現在已透過 SSH 連線至 VM。

此命令可有效運作，因為您在先前執行 az vm create 時提供了 --generate-ssh-keys 選項。此選項會建立 SSH 金鑰組，讓您可以登入 VM。

在 VM 上安裝建置工具

在本節中，您將使用建 置 Space Game 網站所需的工具來設定 VM。

回想一下，您現有的建置程序使用了下列工具：

用來建立應用程式的 .NET SDK
Node.js，用以執行組建工作
npm，適用於 Node.js 的套件管理員
gulp，此為用來縮製 JavaScript 和 CSS 檔案的 Node.js 套件

這些是建置流程所需的主要工具。若要安裝它們，您將從 GitHub 下載並執行殼層腳本。

注意

建置程序也會使用其他工具，例如使用 node-sass 將 Sass (.scss) 檔案轉換成 CSS (.css) 檔案。不過，Node.js 會組建執行時安裝這些工具。

首先我們要更新名為 apt 的 Ubuntu 套件管理員。此動作會從套件存放庫中擷取最新資訊，而這通常是您設定新的 Ubuntu 系統時會執行的第一個動作。

在您的 SSH 連線中，更新 apt 套件管理員快取：
```
sudo apt-get update
```
sudo 會以系統管理員或根權限執行命令。

執行下列 curl 命令，從 GitHub 下載名為 build-tools.sh 的殼層指令碼：

curl https://raw.githubusercontent.com/MicrosoftDocs/mslearn-tailspin-spacegame-web/main/.agent-tools/build-tools.sh > build-tools.sh

將文稿印至終端機，以便檢查其內容：

cat build-tools.sh

顯示的結果如下：

#!/bin/bash
set -e

# Select a default .NET version if one is not specified
if [ -z "$DOTNET_VERSION" ]; then
  DOTNET_VERSION=6.0.300
fi

# Add the Node.js PPA so that we can install the latest version
curl -sL https://deb.nodesource.com/setup_16.x | bash -

# Install Node.js and jq
apt-get install -y nodejs

apt-get install -y jq

# Install gulp
npm install -g gulp

# Change ownership of the .npm directory to the sudo (non-root) user
chown -R $SUDO_USER ~/.npm

# Install .NET as the sudo (non-root) user
sudo -i -u $SUDO_USER bash << EOF
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin -c LTS -v $DOTNET_VERSION
EOF

此指令碼會安裝 Node.js、npm、gulp 以及 .NET Core。

設定 DOTNET_VERSION 環境變數可讓您指定要安裝的 .NET 版本。如果您未設定此變數，則該指令碼會安裝您現有組建組態所使用的版本。若只是做為學習之用，無須設定此變數。只要允許指令碼使用預設版本即可。

將文稿設為可執行檔，然後執行文稿：
```
chmod u+x build-tools.sh
sudo ./build-tools.sh
```
指令碼需要幾分鐘的執行時間。

在實務上，此時您可以執行命令以確認每個軟體元件都已成功安裝。

在您的 VM 上安裝代理程式軟體

現在，您可以在 VM 上安裝代理程式軟體。此軟體可讓 VM 作為組建代理程式，並從 Azure Pipelines 接收組建作業。

註冊程序會先檢查已安裝的軟體，再向 Azure Pipelines 註冊代理程式。因此，請務必在安裝所有其他軟體後設定代理程式。在實務上，如果您需要安裝其他軟體，您可以再次註冊代理程式。

此文件說明如何手動設定自我裝載的 Linux 代理程式，以及 macOS 與 Windows 代理程式。您可以執行殼層腳本，以與上一節中設定建置工具的方式相同來設定代理程式。

重要

您在此處執行的指令碼是供學習之用。在實務上，應先了解在您所建置的指令碼之中，每個命令會對整體系統有何影響。在本課程模組的結尾，會為您提供整說明相關選項的文件。

執行下列 curl 命令，從 GitHub 下載名為 build-agent.sh 的殼層指令碼：

curl https://raw.githubusercontent.com/MicrosoftDocs/mslearn-tailspin-spacegame-web/main/.agent-tools/build-agent.sh > build-agent.sh

將文稿印至終端機，以便檢查其內容：

cat build-agent.sh

顯示的結果如下：

#!/bin/bash
set -e

# Select a default agent version if one is not specified
if [ -z "$AZP_AGENT_VERSION" ]; then
  AZP_AGENT_VERSION=2.187.2
fi

# Verify Azure Pipelines token is set
if [ -z "$AZP_TOKEN" ]; then
  echo 1>&2 "error: missing AZP_TOKEN environment variable"
  exit 1
fi

# Verify Azure DevOps URL is set
if [ -z "$AZP_URL" ]; then
  echo 1>&2 "error: missing AZP_URL environment variable"
  exit 1
fi

# If a working directory was specified, create that directory
if [ -n "$AZP_WORK" ]; then
  mkdir -p "$AZP_WORK"
fi

# Create the Downloads directory under the user's home directory
if [ -n "$HOME/Downloads" ]; then
  mkdir -p "$HOME/Downloads"
fi

# Download the agent package
curl https://vstsagentpackage.azureedge.net/agent/$AZP_AGENT_VERSION/vsts-agent-linux-x64-$AZP_AGENT_VERSION.tar.gz > $HOME/Downloads/vsts-agent-linux-x64-$AZP_AGENT_VERSION.tar.gz

# Create the working directory for the agent service to run jobs under
if [ -n "$AZP_WORK" ]; then
  mkdir -p "$AZP_WORK"
fi

# Create a working directory to extract the agent package to
mkdir -p $HOME/azp/agent

# Move to the working directory
cd $HOME/azp/agent

# Extract the agent package to the working directory
tar zxvf $HOME/Downloads/vsts-agent-linux-x64-$AZP_AGENT_VERSION.tar.gz

# Install the agent software
./bin/installdependencies.sh

# Configure the agent as the sudo (non-root) user
chown $SUDO_USER $HOME/azp/agent
sudo -u $SUDO_USER ./config.sh --unattended \
  --agent "${AZP_AGENT_NAME:-$(hostname)}" \
  --url "$AZP_URL" \
  --auth PAT \
  --token "$AZP_TOKEN" \
  --pool "${AZP_POOL:-Default}" \
  --work "${AZP_WORK:-_work}" \
  --replace \
  --acceptTeeEula

# Install and start the agent service
./svc.sh install
./svc.sh start

您不需要了解每一行的運作方式，但以下簡短摘錄了此指令碼所執行的作業：

其會以 .tar.gz 檔案的格式下載代理程式套件，並將其內容解壓縮。
在解壓縮的檔案中，指令碼會進行以下動作：
- 執行名為 installdependencies.sh 的殼層指令碼，以安裝代理程式軟體。
- 執行名為 config.sh 的殼層指令碼，以設定代理程式，並向 Azure Pipelines 註冊代理程式。
- 執行名為 svc.sh 的殼層指令碼，以安裝並啟動代理程式服務。

此指令碼會使用環境變數，讓您能夠提供 Azure DevOps 組織的相關詳細資料。摘要如下：

Bash 變數	描述	預設
`AZP_AGENT_VERSION`	要安裝的代理程式軟體版本	我們最後用來測試此課程模組的版本
`AZP_URL`	您的 Azure DevOps 組織 URL	(無)
`AZP_TOKEN`	您的個人存取權杖	(無)
`AZP_AGENT_NAME`	您的代理程式顯示在 Azure DevOps 中的名稱	系統的主機名稱
`AZP_POOL`	您的代理程式集區名稱	Default
`AZP_WORK`	代理程式用來執行組建工作的工作目錄	_work

如果指令碼對於未設定的變數未提供預設值，則指令碼會列印錯誤訊息並立即結束。

在後續步驟中，設定下列環境變數：

AZP_AGENT_VERSION
AZP_URL
AZP_TOKEN
AZP_AGENT_NAME
AZP_POOL

目前，建議您將其他變數保留為未設定。

設定 AZP_AGENT_NAME 環境變數以指定您的代理程式名稱。建議您使用 MyLinuxAgent。
```
export AZP_AGENT_NAME=MyLinuxAgent
```
設定 AZP_URL 環境變數以指定您 Azure DevOps 組織的 URL。

請將 <organization> 取代為您的組織名稱。您可以從顯示 Azure DevOps 的瀏覽器索引標籤中取得名稱。
```
export AZP_URL=https://dev.azure.com/organization
```
AZP_TOKEN設定環境變數以指定您的個人存取令牌（您稍早在本單元中複製的長令牌值）。

請將 <token> 取代為您的權杖。
```
export AZP_TOKEN=token
```
設定 AZP_POOL 環境變數以指定您的代理程式集區名稱。先前，您已建立名為 MyAgentPool 的集區。
```
export AZP_POOL=MyAgentPool
```
設定 AZP_AGENT_VERSION 環境變數以指定代理程式的最新版本。
```
export AZP_AGENT_VERSION=$(curl -s https://api.github.com/repos/microsoft/azure-pipelines-agent/releases | jq -r '.[0].tag_name' | cut -d "v" -f 2)
```
Linux 機器上的 YAML 管線必須使用最新版的代理程式，即使其為發行前版本也一樣。代理程式軟體會持續更新，因此可以使用 curl 從 GitHub 存放庫取得版本資訊。此命令會使用 jq 從傳回的 JSON 字串讀取最新版本。
將代理程式版本列印到主控台。您可以選擇性執行檢查以確定這是最新版本。
```
echo $AZP_AGENT_VERSION
```
將文稿設為可執行檔，然後執行它：
```
chmod u+x build-agent.sh
sudo -E ./build-agent.sh
```
sudo 可讓指令碼以根使用者身分執行。 -E 参数保存当前环境变量，包括你设置的变量，方便脚本可以使用它们。

執行指令碼時，您會看到代理程式連線至 Azure DevOps、新增至代理程式集區，以及測試代理程式連線。

確認代理程式正在執行

您已經在 VM 上成功安裝組建工具與代理程式軟體。遵循下列驗證步驟，前往 Azure DevOps 並查看代理程式集區中的代理程式。

在 Azure DevOps 中，前往 Space Game - web - Agent 專案。
選取 [專案設定]。
在 [管線] 下方，選取 [代理程式集區]。
選取 [MyAgentPool]。
選取 [代理程式] 索引標籤。

您會看到您的代理程式處於線上狀態，並準備好要接受組建作業。

提示

如果您的組建代理程式顯示為 [離線]，請等候一段時間，然後重新整理頁面。
選取您的代理程式 MyLinuxAgent。
選取 [功能] 索引標籤。

在安裝期間，設定程序掃描了您組建代理程式中的工具功能。您會看到 npm 列為其中之一。您應該記得，原始組建組態指定必須在代理程式上安裝 npm。

當您指定所要使用的代理程式集區時，您可以將上述任何項目包含在 demands 區段中。將這些項目包含在內，可確保 Azure Pipelines 選擇的組建代理程式具有您在建置應用程式時所需的軟體。同時也能讓您以各種軟體設定來建立代理程式集區。 Azure Pipelines 會根據您的需求選取正確的設定。