Ćwiczenie — tworzenie agenta kompilacji uruchomionego na platformie Azure

  • 20 min

W tej lekcji, aby skonfigurować agenta kompilacji, którego można użyć w usłudze Microsoft Azure Pipelines, użyjesz maszyny wirtualnej działającej na platformie Microsoft Azure. Udostępniamy maszynę wirtualną, której można użyć przez czas trwania tego modułu.

W trakcie tej lekcji wykonasz następujące czynności:

  • Na platformie Azure utwórz maszynę wirtualną z systemem Ubuntu, która będzie służyć jako agent kompilacji.
  • Tworzenie puli agentów w usłudze Microsoft Azure DevOps.
  • Utwórz token dostępu umożliwiający uwierzytelnianie agenta w usłudze Azure DevOps.
  • Skonfiguruj agenta przy użyciu oprogramowania wymaganego do utworzenia witryny internetowej Space Game .
  • Skonfiguruj połączenie agenta z usługą Azure DevOps, aby umożliwić przekazywanie zadań kompilacji do niego.
  • Sprawdź, czy agent jest połączony z usługą Azure DevOps i jest gotowy do odbierania zadań kompilacji.

Maszynę wirtualną na platformie Azure można utworzyć na wiele sposobów. W tej lekcji utworzysz maszynę wirtualną z systemem Ubuntu przy użyciu interaktywnego terminalu o nazwie Cloud Shell.

Aby skonfigurować maszynę wirtualną, możesz wybrać kilka opcji:

  • W przypadku maszyny wirtualnej z systemem Linux możesz połączyć się bezpośrednio za pomocą protokołu SSH i interaktywnie skonfigurować system.
  • Wdrożenie można zautomatyzować przy użyciu szablonu usługi ARM, Bicep lub innego zautomatyzowanego narzędzia do aprowizacji.
  • W przypadku potrzeby wdrożenia wielu agentów kompilacji możesz utworzyć obraz maszyny wirtualnej z wstępnie zainstalowanym oprogramowaniem.

Interaktywne konfigurowanie systemu jest dobrym sposobem rozpoczęcie pracy, ponieważ ułatwia zapoznanie się z procesem i pomaga zrozumieć, jakie elementy są potrzebne. Aby uprościć ten proces, połącz się z maszyną wirtualną z systemem Ubuntu za pośrednictwem protokołu SSH i uruchom skrypty powłoki, aby skonfigurować agenta kompilacji.

Uwaga

Jeśli nie znasz nawiązywania połączenia z systemami Linux lub konfigurowania ich, po prostu postępuj zgodnie z instrukcjami. Te same pojęcia możesz zastosować do agentów kompilacji systemu Windows.

Tworzenie maszyny wirtualnej z systemem Linux

W tej sekcji utworzysz maszynę wirtualną z systemem Ubuntu 20.04, która będzie służyć jako agent kompilacji. Maszyna wirtualna nie jest jeszcze skonfigurowana jako agent kompilacji ani nie ma żadnych narzędzi wymaganych do utworzenia aplikacji internetowej Space Game . Wkrótce wykonamy te czynności.

Tworzenie usługi Cloud Shell za pośrednictwem witryny Azure Portal

Ważne

Do wykonania ćwiczeń w tym module potrzebna jest własna subskrypcja platformy Azure.

  1. Przejdź do witryny Azure Portal i zaloguj się.

  2. Z menu wybierz pozycję Cloud Shell. Po wyświetleniu monitu wybierz środowisko powłoki Bash .

    A screenshot of the Azure portal showing the location of the Cloud Shell menu item.

    Uwaga

    Usługa Cloud Shell wymaga, aby zasób usługi Azure Storage utrwalał wszystkie pliki utworzone w usłudze Cloud Shell. Po pierwszym otwarciu usługi Cloud Shell zostanie wyświetlony monit o utworzenie grupy zasobów, konta magazynu i udziału usługi Azure Files. Ta konfiguracja jest automatycznie używana dla wszystkich przyszłych sesji usługi Cloud Shell.

Wybieranie regionu platformy Azure

Region to co najmniej jedno centrum danych platformy Azure w lokalizacji geograficznej. Przykładami regionów są Wschodnie stany USA, Zachodnie stany USA i Europa Północna. Każdy zasób platformy Azure, w tym maszyna wirtualna platformy Azure, jest przypisany region.

Aby ułatwić uruchamianie poleceń, zacznij od wybrania domyślnego regionu. Po określeniu regionu domyślnego późniejsze polecenia używają tego regionu, chyba że określisz inny region.

  1. W usłudze Cloud Shell, aby wyświetlić listę regionów dostępnych w ramach subskrypcji platformy Azure, uruchom następujące az account list-locations polecenie:

    az account list-locations \
  --query "[].{Name: name, DisplayName: displayName}" \
  --output table

  2. Z kolumny Name w danych wyjściowych wybierz region, który jest blisko Ciebie. Na przykład wybierz lub eastasia westus2.

  3. Uruchom polecenie az configure , aby ustawić domyślny region. Zastąp <REGION> ciąg nazwą wybranego regionu:

    az configure --defaults location=<REGION>

    W tym przykładzie ustawiono westus2 domyślny region:

    az configure --defaults location=westus2

Tworzenie grupy zasobów

Utwórz grupę zasobów zawierającą zasoby używane w tym module szkoleniowym.

  • Aby utworzyć grupę zasobów o nazwie tailspin-space-game-rg, uruchom następujące az group create polecenie:

    az group create --name tailspin-space-game-rg

Tworzenie maszyny wirtualnej

Aby utworzyć maszynę wirtualną, uruchom następujące az vm create polecenie:

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

Utworzenie maszyny wirtualnej potrwa kilka minut.

Wartość Standard_DS2_v2 określa rozmiar maszyny wirtualnej. Rozmiar maszyny wirtualnej definiuje szybkość jej procesora, ilość pamięci, początkową wielkość magazynu i oczekiwaną przepustowość sieci. Jest to ten sam rozmiar, który jest udostępniany przez agentów hostowanych przez firmę Microsoft. W praktyce można wybrać rozmiar zapewniający większą moc obliczeniową lub dodatkowe możliwości, takie jak przetwarzanie grafiki.

Argument --resource-group określa grupę zasobów, w której znajdują się wszystkie tworzone elementy. Grupa zasobów pozwala administrować wszystkimi maszynami wirtualnymi, dyskami, interfejsami sieciowymi i innymi elementami, które składają się na nasze rozwiązanie.

Tworzenie puli agentów

Warto pamiętać, że pula agentów umożliwia organizowanie agentów kompilacji. W tej sekcji utworzysz pulę agentów w usłudze Azure DevOps. Później podamy nazwę puli agentów podczas konfigurowania agenta — umożliwi to jego zarejestrowanie we właściwej puli.

  1. W usłudze Azure DevOps przejdź do projektu Space Game — web — Agent .

  2. Wybierz pozycję Ustawienia projektu.

  3. W obszarze Pipelines (Potoki) wybierz pozycję Agent pools (Pule agentów).

    A screenshot of the project settings in Azure DevOps showing the location of the Agent pools menu item.

  4. Wybierz pozycję Dodaj pulę.

  5. W oknie Dodawanie puli:

    1. W obszarze Pula do linku wybierz pozycję Nowy.
    2. W obszarze Typ puli wybierz pozycję Self-hosted.
    3. W obszarze Nazwa wprowadź wartość MyAgentPool.

    W praktyce należy wybrać bardziej opisową nazwę puli.

  6. Wybierz pozycję Utwórz. Nowa pula agentów zostanie wyświetlona na liście.

Tworzenie osobistego tokenu dostępu

Aby agent kompilacji zarejestrował się w usłudze Azure DevOps, potrzebny jest sposób na jego uwierzytelnienie.

W tym celu możesz utworzyć osobisty token dostępu. Osobisty token dostępu ( lub pat) jest alternatywą dla hasła. Możesz użyć tokenu pat do uwierzytelniania za pomocą usług, takich jak Azure DevOps.

Ważne

Podobnie jak w przypadku hasła, pamiętaj, aby zachować token dostępu w bezpiecznym miejscu. W tej sekcji zapiszesz token dostępu jako zmienną środowiskową, aby nie była wyświetlana w skrypcie powłoki.

  1. W usłudze Azure DevOps otwórz ustawienia profilu, a następnie wybierz pozycję Osobiste tokeny dostępu.

    A screenshot of Azure DevOps showing the location of the Personal access tokens menu item.

  2. Wybierz pozycję Nowy token.

  3. Wprowadź nazwę tokenu, taką jak Build agent.

  4. W obszarze Zakresy wybierz link Pokaż wszystkie zakresy u dołu.

  5. Wyszukaj pozycję Pule agentów, a następnie wybierz pozycję Odczyt i zarządzanie.

  6. Wybierz pozycję Utwórz.

  7. Skopiuj token do bezpiecznego miejsca.

    Wkrótce zostanie on użyty do umożliwienia agentowi kompilacji uwierzytelniania dostępu do usługi Azure Pipelines.

Łączenie z maszyną wirtualną

W tej sekcji połączysz się z maszyną wirtualną z systemem Linux za pośrednictwem protokołu SSH, aby można było ją skonfigurować.

Pamiętaj, że nie możesz interaktywnie zalogować się do agenta hostowanego przez firmę Microsoft. Ponieważ prywatny agent kompilacji jest twoim właścicielem, możesz zalogować się do niego i skonfigurować go tak, jak chcesz.

Możliwość nawiązywania połączenia z agentem kompilacji umożliwia skonfigurowanie go za pomocą narzędzi potrzebnych do kompilowania oprogramowania. Umożliwia również rozwiązywanie problemów podczas tworzenia konfiguracji potoku.

  1. Aby uzyskać adres IP maszyny wirtualnej, uruchom polecenie az vm show w usłudze Cloud Shell:

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

    To polecenie zapisuje adres IP w zmiennej powłoki Bash o nazwie IPADDRESS.

  2. Wydrukuj adres IP maszyny wirtualnej do konsoli:

    echo $IPADDRESS

  3. Utwórz połączenie SSH z maszyną wirtualną. Zamiast $IPADDRESS wprowadź adres IP otrzymany w poprzednim kroku. Po wyświetleniu monitu wprowadź tak , aby kontynuować nawiązywanie połączenia.

    ssh azureuser@$IPADDRESS

    Masz teraz połączenie z maszyną wirtualną za pośrednictwem protokołu SSH.

    To polecenie działa, ponieważ przy wcześniejszym uruchamianiu polecenia az vm create podano opcję --generate-ssh-keys. Ta opcja tworzy parę kluczy SSH, co umożliwia logowanie się do maszyny wirtualnej.

Instalowanie narzędzi kompilacji na maszynie wirtualnej

W tej sekcji skonfigurujesz maszynę wirtualną przy użyciu narzędzi wymaganych do utworzenia witryny internetowej Space Game .

Pamiętaj, że w istniejącym procesie kompilacji są używane te narzędzia:

  • Zestaw SDK platformy .NET, który służy do kompilowania aplikacji
  • Node.js — platforma używana do wykonywania zadań kompilacji
  • npm — menedżer pakietów dla platformy Node.js
  • gulp, pakiet Node.js używany do stosowania plików JavaScript i CSS

Są to podstawowe narzędzia wymagane przez proces kompilacji. Aby je zainstalować, pobierzesz i uruchomisz skrypt powłoki z usługi GitHub.

Uwaga

Proces kompilacji używa innych narzędzi, takich jak node-sass, do konwertowania plików Sass (scss) na pliki CSS (css). Jednak platforma Node.js instaluje je po uruchomieniu kompilacji.

Zacznijmy od zaktualizowania menedżera pakietów systemu Ubuntu o nazwie apt. Ta akcja pobiera najnowsze informacje z repozytoriów pakietów i zwykle jest pierwszą rzeczą wykonywaną podczas konfigurowania nowego systemu Ubuntu.

  1. W połączeniu SSH zaktualizuj pamięć podręczną menedżera pakietów apt:

    sudo apt-get update

    sudo uruchamia polecenie z uprawnieniami administratora lub głównego.

  2. Aby pobrać skrypt powłoki o nazwie build-tools.sh z usługi GitHub, uruchom następujące curl polecenie:

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

  3. Wydrukuj skrypt do terminalu, aby można było sprawdzić jego zawartość:

    cat build-tools.sh

    Zostanie wyświetlony następujący wynik:

    #!/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

    Skrypt instaluje środowisko Node.js, npm, gulp i .NET Core.

    Ustawiając zmienną DOTNET_VERSION środowiskową, można określić wersję platformy .NET do zainstalowania. Jeśli nie ustawisz tej zmiennej, skrypt zainstaluje wersję używaną przez istniejącą konfigurację kompilacji. Dla celów szkoleniowych nie ustawiasz tej zmiennej. Zezwalasz skryptowi na używanie wersji domyślnej.

  4. Utwórz plik wykonywalny skryptu, a następnie uruchom skrypt:

    chmod u+x build-tools.sh
sudo ./build-tools.sh

    Wykonanie skryptu może potrwać kilka minut.

    Ze względów praktycznych możesz teraz uruchomić polecenia umożliwiające sprawdzenie, czy każdy składnik oprogramowania został pomyślnie zainstalowany.

Instalowanie oprogramowania agenta na maszynie wirtualnej

Teraz należy zainstalować oprogramowanie agenta na maszynie wirtualnej. Umożliwia ono maszynie wirtualnej pełnienie roli agenta kompilacji i odbieranie zadań kompilacji z usługi Azure Pipelines.

W procesie rejestracji — przed zarejestrowaniem agenta w usłudze Azure Pipelines — następuje sprawdzenie, jakie oprogramowanie jest zainstalowane. W związku z tym ważne jest skonfigurowanie agenta po zainstalowaniu wszystkich innych oprogramowania. Jeśli konieczne jest zainstalowanie dodatkowego oprogramowania, można ponownie zarejestrować agenta.

W dokumentacji wyjaśniono, jak ręcznie skonfigurować własnych agentów systemu Linux, a także agentów systemu macOS i Windows. Uruchamiasz skrypt powłoki, aby skonfigurować agenta w taki sam sposób, jak skonfigurować narzędzia kompilacji w poprzedniej sekcji.

Ważne

Skrypt, który uruchomisz tutaj, służy do celów szkoleniowych. W praktyce należy najpierw zrozumieć, jak każde polecenie w kompilnych skryptach wpływa na ogólny system. Na końcu modułu wskażemy dokumentację, która bardziej całkowicie opisuje Opcje.

  1. Aby pobrać skrypt powłoki o nazwie build-agent.sh z usługi GitHub, uruchom następujące curl polecenie:

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

  2. Wydrukuj skrypt do terminalu, aby można było sprawdzić jego zawartość:

    cat build-agent.sh

    Zostanie wyświetlony następujący wynik:

    #!/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

    Nie musisz rozumieć, jak działa każdy wiersz, ale oto krótkie podsumowanie działania tego skryptu:

    • Pobiera pakiet agenta jako plik tar.gz i wyodrębnia jego zawartość.
    • W wyodrębnionych plikach skrypt:
      • Uruchamia skrypt powłoki o nazwie installdependencies.sh w celu zainstalowania oprogramowania agenta.
      • Uruchamia skrypt powłoki o nazwie config.sh w celu skonfigurowania agenta i zarejestrowania agenta w usłudze Azure Pipelines.
      • Uruchamia skrypt powłoki o nazwie svc.sh , aby zainstalować i uruchomić usługę agenta.

    Skrypt używa zmiennych środowiskowych, aby umożliwić podanie szczegółowych informacji o organizacji usługi Azure DevOps. Oto podsumowanie:

    Zmienna powłoki Bash opis Wartość domyślna
    AZP_AGENT_VERSION Wersja oprogramowania agenta, która ma zostać zainstalowana Wersja użyta podczas ostatniego testu modułu
    AZP_URL Adres URL organizacji usługi Azure DevOps (Brak)
    AZP_TOKEN Osobisty token dostępu (Brak)
    AZP_AGENT_NAME Nazwa agenta wyświetlana w usłudze Azure DevOps Nazwa hosta systemu
    AZP_POOL Nazwa puli agentów Wartość domyślna
    AZP_WORK Katalog roboczy agenta, w którym są wykonywane zadania kompilacji _work

    Jeśli skrypt nie podaje wartości domyślnej dla zmiennej, która nie jest ustawiona, skrypt wyświetla komunikat o błędzie i natychmiast kończy działanie.

    W kolejnych krokach ustaw następujące zmienne środowiskowe:

    • AZP_AGENT_VERSION
    • AZP_URL
    • AZP_TOKEN
    • AZP_AGENT_NAME
    • AZP_POOL

    Zaleca się, aby na razie nie ustawiać wartości innych zmiennych.

  3. Zmiennej środowiskowej AZP_AGENT_NAME przypisz nazwę agenta. Zalecamy użycie nazwy MyLinuxAgent.

    export AZP_AGENT_NAME=MyLinuxAgent

  4. Ustaw zmienną AZP_URL środowiskową, aby określić adres URL organizacji usługi Azure DevOps.

    Element <organization> zastąp nazwą swojej organizacji. Nazwę można uzyskać na karcie przeglądarki, na której jest wyświetlana usługa Azure DevOps.

    export AZP_URL=https://dev.azure.com/organization

  5. Ustaw zmienną AZP_TOKEN środowiskową, aby określić osobisty token dostępu (wartość długiego tokenu skopiowaną wcześniej w tej lekcji).

    Element <token> zastąp wartością swojego tokenu.

    export AZP_TOKEN=token

  6. Zmiennej środowiskowej AZP_POOL przypisz nazwę puli agentów. Wcześniej utworzyliśmy pulę o nazwie MyAgentPool.

    export AZP_POOL=MyAgentPool

  7. Ustaw zmienną AZP_AGENT_VERSION środowiskową, aby określić najnowszą wersję agenta.

    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)

    Potok YAML na maszynie z systemem Linux musi używać najnowszej wersji agenta, nawet jeśli jest to wersja wstępna. Oprogramowanie agenta jest stale aktualizowane, więc informacje curl o wersji z repozytorium GitHub. Polecenie używa jq polecenia , aby odczytać najnowszą wersję z zwróconego ciągu JSON.

  8. Wydrukuj wersję agenta do konsoli programu . Opcjonalnie sprawdź, czy jest to najnowsza wersja.

    echo $AZP_AGENT_VERSION

  9. Utwórz plik wykonywalny skryptu, a następnie uruchom go:

    chmod u+x build-agent.sh
sudo -E ./build-agent.sh

    Program sudo umożliwia uruchomienie skryptu z uprawnieniami użytkownika głównego. -E Argument zachowuje bieżące zmienne środowiskowe, w tym ustawione przez Ciebie zmienne, aby były dostępne dla skryptu.

    W miarę uruchamiania skryptu można zobaczyć, jak agent nawiązuje połączenie z usługą Azure DevOps, zobacz, jak został dodany do puli agentów, i sprawdź, czy połączenie agenta zostanie przetestowane.

Sprawdź, czy agent jest uruchomiony

Pomyślnie zainstalowano narzędzia kompilacji i oprogramowanie agenta na maszynie wirtualnej. W ramach kroku weryfikacji przejdź do usługi Azure DevOps i zobacz agenta w puli agentów.

  1. W usłudze Azure DevOps przejdź do projektu Space Game — web — Agent .

  2. Wybierz pozycję Ustawienia projektu.

  3. W obszarze Pipelines (Potoki) wybierz pozycję Agent pools (Pule agentów).

  4. Wybierz pozycję MyAgentPool.

  5. Wybierz kartę Agents (Agenci).

    Widać, że agent jest w trybie online i jest gotowy do akceptowania zadań kompilacji.

    A screenshot of Azure DevOps showing the status of the private agent. The agent shows as online, idle, and enabled.

    Napiwek

    Jeśli agent kompilacji jest wyświetlany jako offline, spróbuj poczekać chwilę, a następnie odśwież stronę.

  6. Wybierz agenta MyLinuxAgent.

  7. Wybierz kartę Capabilities (Możliwości).

    W procesie konfiguracji agent kompilacji został przeskanowany pod kątem obsługi narzędzi. Na liście znajduje się m.in. narzędzie npm. Przypomnij sobie, że zgodnie z pierwotną konfiguracją kompilacji na agencie musi być zainstalowane narzędzie npm.

    A screenshot of Azure DevOps showing a few of the agent's capabilities. The npm capability is highlighted.

    Przy określaniu, która pula agentów ma być używana, można umieścić dowolny z tych wpisów w sekcji demands. Uwzględnienie ich gwarantuje, że usługa Azure Pipelines wybierze agenta kompilacji, który ma oprogramowanie potrzebne do skompilowania aplikacji. Umożliwia również tworzenie pul agentów z różnymi konfiguracjami oprogramowania. Usługa Azure Pipelines wybierze poprawną konfigurację na podstawie wymagań.