セルフホステッド Linux エージェント

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

ジョブを実行するには、少なくとも 1 つのエージェントが必要です。 Linux エージェントは、Java や Android アプリなど、さまざまな種類のアプリをビルドして配置できます。 サポートされている Linux ディストリビューションの一覧については、「前提条件を確認する」を参照してください。

エージェントの詳細

エージェントの概要としくみが既にわかっている場合は、次のセクションに進んでください。 ただし、その機能としくみの背景について詳しく知りたい場合は、「Azure Pipelines エージェント」を参照してください。

前提条件を確認する

エージェントのセットアップは、最初に手動で実行する必要があります。 エージェントの動作を確認した後、または多数のエージェントの設定を自動化する場合は、無人構成の使用を検討してください。

アクセス許可を準備する

セルフホステッド エージェントの情報セキュリティ

エージェントを構成するユーザーにはプール管理者のアクセス許可が必要ですが、エージェントを実行するユーザーには必要ありません。

エージェントによって制御されるフォルダーは、含まれている機密情報の解読または漏洩を回避するために、できる限り少数のユーザーにアクセスを制限する必要があります。

Azure Pipelines エージェントは、外部ソースからダウンロードしたコードを実行するように設計されたソフトウェア製品です。 本質的には、リモート コード実行 (RCE) 攻撃のターゲットになる可能性があります。

したがって、作業を実行するパイプライン エージェントの個々の使用法に関する脅威モデルを考慮することが重要です。また、エージェントを実行しているユーザー、エージェントが実行されているマシン、パイプライン定義への書き込みアクセス権を持つユーザー、yaml が保存される git リポジトリ、または新しいパイプラインのプールへのアクセスを制御するユーザー グループに、付与できる最小限のアクセス許可を決定することも重要です。

エージェントを実行している ID は、エージェントをプールに接続するためのアクセス許可を持つ ID とは別にすることをお勧めします。 資格情報 (およびその他のエージェント関連ファイル) を生成するユーザーは、資格情報を読み取る必要があるユーザーとは異なります。 そのため、エージェント マシン自体と、ログや成果物などの機密性の高いファイルを含むエージェント フォルダーに付与されるアクセスを慎重に検討する方が安全です。

DevOps 管理者とエージェント プロセスを実行しているユーザー ID に対してのみ、エージェント フォルダーへのアクセス権を付与することが理にかなっています。 管理者は、ビルド エラーを理解するためにファイル システムを調査するか、Azure DevOps のエラーを報告できるようにログ ファイルを取得する必要がある場合があります。

使うユーザーを決定する

1 回限りの手順として、エージェントを登録する必要があります。 エージェント キューを管理するアクセス許可を持つユーザーは、これらの手順を完了する必要があります。 エージェントは、日常的な操作ではこのユーザーの資格情報を使いませんが、登録を完了するために必要です。 エージェントの通信方法の詳細を確認します。

ユーザーにアクセス許可があることを確認する

使うユーザー アカウントに、エージェントを登録するためのアクセス許可があることを確認します。

ユーザーは Azure DevOps 組織所有者、TFS または Azure DevOps Server 管理者ですか? その場合はこれで終了です。既にアクセス許可を持っています。

それ以外の場合:

1. ブラウザーを開き、Azure Pipelines 組織、Azure DevOps Server、または TFS サーバーの [エージェント プール] タブに移動します。

   1. 組織にサインインします (https://dev.azure.com/{yourorganization})。

   2. [Azure DevOps]、[組織の設定] の順に選びます。

      

   3. [エージェント プール] を選択します。

      

   1. プロジェクト コレクション (http://your-server/DefaultCollection) にサインインします。

   2. [Azure DevOps]、 [コレクションの設定]の順に選択します。

      

   3. [エージェント プール] を選択します。

      

   1. [Azure DevOps]、 [コレクションの設定]の順に選択します。

      

   2. [エージェント プール] を選択します。

      

2. ページの右側にあるプールを選び、[セキュリティ] をクリックします。

3. 使うユーザー アカウントが表示されない場合は、管理者に追加を依頼します。 管理者は、エージェント プール管理者、Azure DevOps 組織所有者、または TFS または Azure DevOps Server 管理者の場合があります。

   配置グループ エージェントの場合、管理者は、配置グループ管理者、Azure DevOps 組織所有者、または TFS または Azure DevOps Server 管理者の場合があります。

   Azure Pipelinesの [配置グループ] ページの [セキュリティ] タブで、配置グループ管理者ロールにユーザーを追加できます。

エージェントのダウンロードと構成

サーバー URL

認証の種類

エージェントを登録するときに次の認証の種類から選択すると、エージェントのセットアップから、各認証の種類に必要な特定の追加情報の入力を求められます。 詳細については、「セルフホステッド エージェントの認証オプション」を参照してください。

対話形式で実行する

エージェントを対話型モードで実行するか、サービスとして実行するかのガイダンスについては、「エージェント: 対話型とサービス」を参照してください。

エージェントを対話的に実行するには、次のようにします。

1. エージェントをサービスとして実行している場合は、サービスをアンインストールします。

2. エージェントを実行します。

   ./run.sh
   

エージェントを再起動するには、Ctrl キーを押しながら C キーを押し、run.sh を実行して再起動します。

エージェントを使うには、エージェントのプールを使ってジョブを実行します。 別のプールを選ばなかった場合、エージェントは既定のプールに配置されます。

1 回実行する

対話形式で実行するように構成されたエージェントの場合は、エージェントに 1 つのジョブのみを受け入れるように選択できます。 この構成で実行するには、次のようにします。

./run.sh --once

このモードのエージェントは、1 つのジョブのみを受け入れてから、正常にスピン ダウンします (Azure Container Instances などのサービスで Docker で実行する場合に便利です)。

systemd サービスとして実行する

エージェントがこれらのオペレーティング システムで実行されている場合は、systemd サービスとしてエージェントを実行できます。

• Ubuntu 16 LTS 以降
• Red Hat 7.1 以降

systemd サービスとしてエージェントを実行および管理するためのサンプルの ./svc.sh スクリプトが用意されています。 このスクリプトは、エージェントを構成した後に生成されます。 スクリプトを実行する前に、確認し、必要に応じてスクリプトを更新することをお勧めします。

いくつかの重要な注意事項:

• エージェントをサービスとして実行する場合、エージェント サービスを root ユーザーとして実行することはできません。
• SELinux を実行しているユーザーから、提供された svc.sh スクリプトに関する問題が報告されています。 まず初めに、このエージェントの問題を確認してください。 SELinux は公式にサポートされている構成ではありません。

コマンド

エージェント ディレクトリに変更する

たとえば、ホーム ディレクトリの myagent サブフォルダーにインストールした場合、次のようにします。

cd ~/myagent$

インストール

コマンド:

sudo ./svc.sh install [username]

このコマンドは、./runsvc.sh を指すサービス ファイルを作成します。 このスクリプトは、環境を設定し (詳細については以下を参照)、エージェント ホストを起動します。 username パラメーターが指定されていない場合、ユーザー名は sudo コマンドによって設定される $SUDO_USER 環境変数から取得されます。 この変数は、sudo コマンドを呼び出したユーザーの名前と常に等しくなります。

[開始]

sudo ./svc.sh start

Status

sudo ./svc.sh status

Stop

sudo ./svc.sh stop

[アンインストール]

アンインストールする前に停止する必要があります。

sudo ./svc.sh uninstall

環境変数を更新する

サービスを構成すると、PATH、LANG、JAVA_HOME、ANT_HOME、MYSQL_PATH など、現在のログオン ユーザーに役立つ環境変数のスナップショットが取得されます。 変数を更新する必要がある場合 (たとえば、新しいソフトウェアをインストールした後)、次のようにします。

./env.sh
sudo ./svc.sh stop
sudo ./svc.sh start

環境変数のスナップショットは、エージェント ルート ディレクトリの下の .env ファイルに格納されます (PATH は .pathに格納されます)。また、これらのファイルを直接変更して環境変数の変更を適用することもできます。

サービスの開始前に手順を実行する

独自の手順やコマンドを、サービスの開始時に実行するように実行することもできます。 たとえば、環境を設定したり、スクリプトを呼び出したりできます。

1. runsvc.sh を編集します。

2. 次の行を手順に置き換えます。

   # insert anything to setup env when running as a service
   

サービス ファイル

サービスをインストールすると、一部のサービス ファイルが配置されます。

systemd サービス ファイル

systemd サービス ファイルが作成されます。

/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service

たとえば、our-linux-agent という名前のエージェント (上記を参照) を構成したとします。 サービス ファイルは次のいずれかになります。

• Azure Pipelines: 組織の名前。 たとえば、https://dev.azure.com/fabrikam に接続すると、サービス名は /etc/systemd/system/vsts.agent.fabrikam.our-linux-agent.service になります

• TFS または Azure DevOps Server: オンプレミス サーバーの名前。 たとえば、http://our-server:8080/tfs に接続すると、サービス名は /etc/systemd/system/vsts.agent.our-server.our-linux-agent.service になります

sudo ./svc.sh install は、テンプレート ./bin/vsts.agent.service.template からこのファイルを生成します。

.service ファイル

sudo ./svc.sh start は、上記の systemd サービス ファイルの名前を含む .service ファイルを読み取ってサービスを検索します。

代替サービス メカニズム

./svc.sh スクリプトは、エージェントを systemd サービスとして実行および管理するための便利な方法として提供されます。 ただし、任意の種類のサービス メカニズム (initd や upstart など) を使用できます。

先ほど説明したテンプレートを使うと、他の種類のサービス ファイルを簡単に生成できます。

cgroup を使用してエージェントの障害を回避する

エージェントが失敗したり使用できなくなったりする状況を回避することが重要です。そうしないと、エージェントがパイプライン ログをストリーミングしたり、パイプラインの状態をサーバーに報告したりできないためです。 cgroups と下位の oom_score_adj を使用すると、メモリ負荷が原因でこの種の問題が発生するリスクを軽減できます。 これを行った後、Linux は、エージェント プロセスからメモリを再利用する前に、パイプライン ジョブ プロセスからシステム メモリを再利用します。 cgroups と OOM スコアを構成する方法について説明します。

エージェントを置き換える

エージェントを置き換えるには、「エージェントのダウンロードと構成」の手順をもう一度実行します。

既に存在するエージェントと同じ名前を使用してエージェントを構成すると、既存のエージェントを置き換えるかどうかを確認するメッセージが表示されます。 Y と答えた場合、置き換えるエージェント (下記参照) を必ず削除してください。 そうしないと、数分間の競合の後、エージェントの 1 つがシャットダウンされます。

エージェントの削除と再構成

エージェントを削除するには:

1. 前のセクションで説明したように、サービスを停止してアンインストールします。

2. エージェントを削除します。

   ./config.sh remove
   

3. 資格情報を入力します。

エージェントを削除したら、もう一度構成できます。

無人構成

エージェントは、人間の介入なしでスクリプトから設定できます。 --unattended と、すべての質問への回答を渡す必要があります。

./config.sh --help 常に、最新の必須応答と省略可能な応答を一覧表示します。

診断

セルフホステッド エージェントで問題が発生した場合は、診断の実行を試すことができます。 エージェントの構成後:

./run.sh --diagnostics

これは、問題のトラブルシューティングに役立つ可能性のある診断スイートを介して実行されます。 診断機能は、エージェント バージョン 2.165.0 以降で使用できます。

その他のオプションに関するヘルプ

その他のオプションについては、次の手順を実行します。

./config.sh --help

ヘルプには、認証の代替方法と無人構成に関する情報が記載されています。

機能

エージェントの機能は、プール内でカタログ化およびアドバタイズされるため、それが処理できるビルドとリリースのみが割り当てられます。 ビルド エージェントとリリース エージェントの機能に関する記事を参照してください。

多くの場合、エージェントの配置後には、ソフトウェアまたはユーティリティのインストールが必要になります。 通常、開発用マシンで使用するソフトウェアやツールは、エージェントにインストールする必要があります。

たとえば、ビルドに npm タスクが含まれている場合、そのビルドは、プール内に npm がインストールされているビルド エージェントが存在していないと実行されません。

よく寄せられる質問

新しい v3 エージェント ソフトウェアに関する詳細情報はどこで参照できますか?

v3 エージェント ソフトウェアに関する情報と FAQ については、「エージェント ソフトウェア バージョン 3」を参照してください。

最新のエージェント バージョンを使用していることを確認するにはどうすればよいですか?

1. [エージェント プール] タブに移動します。

   1. 組織にサインインします (https://dev.azure.com/{yourorganization})。

   2. [Azure DevOps]、[組織の設定] の順に選びます。

      

   3. [エージェント プール] を選択します。

      

   1. プロジェクト コレクション (http://your-server/DefaultCollection) にサインインします。

   2. [Azure DevOps]、 [コレクションの設定]の順に選択します。

      

   3. [エージェント プール] を選択します。

      

   1. [Azure DevOps]、 [コレクションの設定]の順に選択します。

      

   2. [エージェント プール] を選択します。

      

2. エージェントを含むプールをクリックします。

3. エージェントが有効になっていることを確認します。

4. [機能] タブに移動します。

   1. [エージェント プール] タブから、目的のエージェント プールを選びます。

      

   2. [エージェント] を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

      注意

      Microsoft ホステッド エージェントでは、システム機能は表示されません。 Microsoft ホステッド エージェントにインストールされるソフトウェアの一覧については、「Microsoft ホステッド エージェントを使用する」をご覧ください。

   1. [エージェント プール] タブから、目的のプールを選択します。

      

   2. [エージェント] を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

   1. [エージェント プール] タブから、目的のプールを選択します。

      

   2. [エージェント] を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

5. Agent.Version 機能を探します。 この値は、公開されている最新のエージェント バージョンに対してチェックできます。 一覧表示されている最も高いバージョン番号については、Azure Pipelines エージェントに関するページを参照し、確認します。

6. 各エージェントは、新しいバージョンのエージェントを必要とするタスクを実行すると、自動的に更新されます。 一部のエージェントを手動で更新する場合は、プールを右クリックし、[すべてのエージェントの更新] を選びます。

サービス コマンドを実行するために sudo が必要なのはなぜですか?

./svc.sh は systemctl を使用します。これには sudo が必要です。

ソース コード: GitHub の systemd.svc.sh.template

自己署名証明書を使用してエージェントを実行するにはどうすればよいですか?

自己署名証明書を使用してエージェントを実行する

Web プロキシの背後でエージェントを実行するにはどうすればよいですか?

Web プロキシの背後でエージェントを実行する

エージェントを再起動する方法

エージェントを対話形式で実行している場合は、「対話形式で実行する」の再起動手順を参照してください。 エージェントを systemd サービスとして実行している場合は、次の手順に従ってエージェントを 停止 してから 開始 します。

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com

TFVC の前提条件

TFVC を使用する場合は、Oracle Java JDK 1.6 以降も必要です。 (Oracle JRE と OpenJDK は、この目的に十分ではありません。)

TFVC 機能には TEE プラグインが使用されます。 これには EULA があり、TFVC を使用する予定の場合は、構成中に受け入れる必要があります。

TEE プラグインは管理されなくなり、古い Java 依存関係がいくつか含まれているため、エージェント 2.198.0 以降ではエージェント ディストリビューションに含まれません。 ただし、TFVC リポジトリをチェックアウトしている場合、チェックアウト タスクの実行中に TEE プラグインがダウンロードされます。 TEE プラグインはジョブの実行後に削除されます。

エージェントがプロキシまたはファイアウォールの背後で稼働している場合は、サイト (https://vstsagenttools.blob.core.windows.net/) へのアクセスを確認する必要があります。 TEE プラグインはこのアドレスからダウンロードされます。

セルフホステッド エージェントを使用していて、TEE のダウンロードに関する問題が発生している場合は、TEE を手動でインストールできます。

1. DISABLE_TEE_PLUGIN_REMOVAL 環境変数またはパイプライン変数を true に設定します。 この変数を使用すると、TFVC リポジトリのチェックアウト後にエージェントが TEE プラグインを削除できなくなります。
2. Team Explorer Everywhere GitHub リリースから TEE-CLC バージョン 14.135.0 を手動でダウンロードします。
3. TEE-CLC-14.135.0 フォルダーの内容を <agent_directory>/externals/tee に抽出します。