セルフホステッド Linux エージェント (2.x)

  • [アーティクル]

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

重要

この記事では、Azure DevOps Server と TFS で 2.x バージョンのエージェント ソフトウェアを使用するためのガイダンスを提供します。 Azure DevOps Services を使っている場合は、「セルフホステッド Linux エージェント」を参照してください。

注意事項

この記事では、間もなくサポート終了 (EOL) 状態になる Linux ディストリビューションである CentOS について説明します。 適宜、使用と計画を検討してください。 詳細については、「CentOS のサポート終了に関するガイダンス」を参照してください。

ジョブを実行するには、少なくとも 1 つのエージェントが必要です。 Linux エージェントは、Java や Android のアプリなど、さまざまな種類のアプリをビルドして配置できます。 Ubuntu、Red Hat、CentOS がサポートされています。

作業を開始する前に、次のことを行います。

  • パイプラインが Azure Pipelines にあり、Microsoft ホステッド エージェントがニーズを満たしている場合は、プライベート Linux エージェントの設定をスキップできます。
  • それ以外の場合は、この記事を参考にして Linux にエージェントを設定してください。 次のセクションに進みます。

エージェントの詳細

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

前提条件を確認する

エージェントは .NET Core 3.1 に基づいています。 このエージェントは、複数の Linux ディストリビューションで実行できます。 .NET Core でサポートされているディストリビューションの、次のサブセットがサポートされています。

  • X64
    • CentOS 7、6 (注 1 を参照)
    • Debian 9
    • Fedora 30、29
    • Linux Mint 18、17
    • openSUSE 42.3 以降
    • Oracle Linux 8、7
    • Red Hat Enterprise Linux 8、7、6 (注 1 を参照)
    • SUSE Enterprise Linux 12 SP2 以降
    • Ubuntu 20.04、18.04、16.04
    • Azure Linux 1.0 (注 3 を参照)
  • ARM32 (注 2 を参照)
    • Debian 9
    • Ubuntu 18.04
  • ARM64
    • Debian 9
    • Ubuntu 21.04、20.04、18.04

注意

注 1: RHEL 6 と CentOS 6 では、エージェントの特殊な rhel.6-x64 バージョンをインストールする必要があります。

重要

2023 年 2 月時点で、RHEL 6 をサポートするエージェント リリースはこれ以上ありません。 詳しくは、「Customers using Red Hat Enterprise Linux (RHEL) 6 should upgrade the OS on Self-hosted agents (Red Hat Enterprise Linux (RHEL) 6 を使っているお客様はセルフホステッド エージェントで OS をアップグレードする必要がある)」を参照してください。

注意

注 2: ARM 命令セット ARMv7 以降が必要です。 お使いの Linux ディストリビューションの命令セットを確認するには、uname -a を実行してください。

注意

現在、Azure Linux OS ディストリビューションには、Azure DevOps エージェントからの部分的なサポートがあります。 installdependencies.sh スクリプトで、この OS ディストリビューションを検出するためのメカニズムを提供していますが、.Net Core 側からのサポートがないため、この OS ディストリビューションで実行しているときにはすべてのエージェント機能の完全な操作性を保証できません。

プラットフォームに関係なく、Git 2.9.0 以降をインストールする必要があります。 最新バージョンの Git をインストールすることを強くお勧めします。

注意

エージェント インストーラーは、他の依存関係をチェックする方法を認識します。 エージェントのディレクトリで ./bin/installdependencies.sh を実行することで、サポートされている Linux プラットフォームにそれらの依存関係をインストールできます。

.NET Core で必要なこれらの依存関係の一部は、packages.efficios.com などのサード パーティのサイトからフェッチされることに注意してください。 スクリプトを実行する前に、installdependencies.sh スクリプトを確認し、参照されているサード パーティのサイトに Linux マシンからアクセスできることを確認します。

また、必要なすべてのリポジトリが、installdependencies.sh で使用されている関連するパッケージ マネージャー (apt や zypper など) に接続されていることを確認してください。

依存関係のインストールに関する問題 ("依存関係がリポジトリに見つかりませんでした" や "リポジトリ インデックス ファイルの取得中の問題" など) については、ディストリビューション所有者に連絡してさらにサポートを受けることができます。

Subversion

Subversion リポジトリからビルドする場合は、マシンに Subversion クライアントをインストールする必要があります。

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

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 に抽出します。

アクセス許可を準備する

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

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

エージェントによって制御されるフォルダーは、できるだけ少ないユーザーに制限する必要があります。それらには、暗号化解除が行われ流出する可能性のあるシークレット含まれています。

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

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

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

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

使うユーザーを決定する

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

個人用アクセス トークン (PAT) を使って認証する

  1. Azure DevOps Server Web ポータル (https://{your-server}/DefaultCollection/) で使う予定のユーザー アカウントでサインインします。
  1. Azure DevOps 組織 (https://dev.azure.com/{your_organization}) で使用する予定のユーザー アカウントでサインインします。

  1. ホーム ページからプロファイルを開きます。 セキュリティの詳細に移動します。

    セキュリティの詳細に移動します。

  2. 個人用アクセス トークンを作成します。

    個人用アクセス トークンを作成します。

    注意

    配置グループ エージェントを構成している場合、または VM 環境リソースの登録時にエラーが発生した場合は、PAT スコープを [すべてのアクセス可能な組織] に設定する必要があります。 PAT スコープを [すべてのアクセス可能な組織] に設定するスクリーンショット。

  1. ホーム ページからユーザー設定を開き、[Personal access tokens] (個人用アクセス トークン) を選択します。

    セキュリティの詳細に移動します。

  2. 個人用アクセス トークンを作成します。

    個人用アクセス トークンを作成します。

  1. スコープで [エージェント プール (読み取り、管理)] を選び、他のすべてのボックスがオフになっていることを確認します。 配置グループ エージェントの場合は、スコープで [配置グループ (読み取り、管理)] を選び、他のすべてのボックスがオフになっていることを確認します。

    [新しい個人用アクセス トークンの作成] ウィンドウの下部にある [すべてのスコープを表示する] を選んで、スコープの完全な一覧を表示します。

  2. トークンをコピーします。 このトークンは、エージェントを構成するときに使います。

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

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

ユーザーは 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]、[コレクションの設定] の順に選択します。

      コレクションの設定 (2019)。

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

      [エージェント プール] を選びます (2019)。

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

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

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

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

注意

"申し訳ございません。ID を追加できませんでした。別の ID を試してください。" のようなメッセージが表示された場合、組織所有者、または TFS または Azure DevOps Server 管理者の場合は、上記の手順に従った可能性があります。 何もする必要はありません。エージェント キューを管理するアクセス許可が既にあります。

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

Azure Pipelines

  1. 上記で説明したように、アクセス許可を準備したアカウントを使ってマシンにログオンします。

  2. Web ブラウザーで Azure Pipelines にサインインし、[エージェント プール] タブに移動します。

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

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

      [組織の設定] を選びます。

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

      [エージェント プール] タブを選びます。

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

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

      [コレクションの設定] を選びます。

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

      [エージェント プール] を選びます。

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

      コレクションの設定 (2019)。

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

      [エージェント プール] を選びます (2019)。

  3. [既定] のプールを選び、[エージェント] タブを選び、[新しいエージェント] を選びます。

  4. [エージェントの取得] ダイアログ ボックスで、[Linux] をクリックします。

  5. 左側のウィンドウで、特定のフレーバーを選びます。 多くの Linux ディストリビューションに x64 または ARM を提供しています。

  6. 右側のウィンドウで、[ダウンロード] ボタンをクリックします。

  7. ページの指示に従います。

  8. 任意のディレクトリにエージェントを展開します。 cd でそのディレクトリに移動し、./config.sh を実行します。

Azure DevOps Server 2019 と Azure DevOps Server 2020

  1. 上記で説明したように、アクセス許可を準備したアカウントを使ってマシンにログオンします。

  2. Web ブラウザーで Azure DevOps Server 2019 にサインインし、[エージェント プール] タブに移動します。

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

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

      [組織の設定] を選びます。

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

      [エージェント プール] タブを選びます。

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

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

      [コレクションの設定] を選びます。

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

      [エージェント プール] を選びます。

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

      コレクションの設定 (2019)。

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

      [エージェント プール] を選びます (2019)。

  3. [エージェントのダウンロード] をクリックします。

  4. [エージェントの取得] ダイアログ ボックスで、[Linux] をクリックします。

  5. 左側のウィンドウで、特定のフレーバーを選びます。 多くの Linux ディストリビューションに x64 または ARM を提供しています。

  6. 右側のウィンドウで、[ダウンロード] ボタンをクリックします。

  7. ページの指示に従います。

  8. 任意のディレクトリにエージェントを展開します。 そのディレクトリに cd し、./config.sh を実行します 。

サーバー URL

Azure Pipelines: https://dev.azure.com/{your-organization}

Azure DevOps Server 2019: https://{your_server}/DefaultCollection

認証の種類

Azure Pipelines

[PAT] を選び、作成した PAT トークンをコマンド プロンプト ウィンドウに貼り付けます。

注意

認証方法として PAT を使う場合、PAT トークンはエージェントの初期構成にのみ使われます。 詳細については、Azure Pipelines または TFS との通信に関するページを参照してください。

TFS または Azure DevOps Server

重要

サーバーが、使用する認証方法をサポートするように構成されていることを確認します。

TFS に接続するようにエージェントを構成すると、次のオプションが得られます。

  • [代替]: 基本認証を使用して、TFS または Azure DevOps Server に接続します。 [代替] を選択すると、資格情報の入力を求められます。

  • [統合]: macOS または Linux ではサポートされていません。

  • [ネゴシエート] (既定値): NTLM や Kerberos などの Windows 認証スキームを使用して、サインインしているユーザー以外のユーザーとして、TFS または Azure DevOps Server に接続します。 [ネゴシエート] を選択すると、資格情報の入力を求められます。

  • [PAT]: Azure Pipelines および TFS 2017 以降でのみサポートされています。 [PAT] を選択してから、作成した PAT トークンをコマンド プロンプト ウィンドウに貼り付けます。 Azure DevOps Server または TFS インスタンスとエージェント マシンが信頼されたドメインにない場合は、個人用アクセス トークン (PAT) を使用します。 PAT 認証は、ドメイン コントローラーではなく、Azure DevOps Server または TFS インスタンスによって処理されます。

注意

認証方法として PAT を使用する場合、PAT トークンは、Azure DevOps Server および新しいバージョンの TFS でのエージェントの初期構成にのみ使用されます。 詳細については、Azure Pipelines または TFS との通信に関するページを参照してください。

対話形式で実行する

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

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

  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 を使用してエージェントの障害を回避する

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

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

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

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

エージェントを削除して再構成する

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

  1. 上記の説明に従って、サービスを停止してアンインストールします。

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

    ./config.sh remove

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

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

無人構成

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

エージェントを構成するには、組織への URL、またはエージェントの設定を承認されたユーザーのコレクションと資格情報を把握している必要があります。 その他の応答はすべて省略可能です。 任意のコマンドライン パラメーターは、代わりに環境変数を使用して指定できます。その名前を大文字にし、先頭に VSTS_AGENT_INPUT_ を付けます。 たとえば、--password を指定する代わりに、VSTS_AGENT_INPUT_PASSWORD とします。

必須オプション

  • --unattended - エージェントのセットアップでは情報の入力を求められるのではなく、すべての設定をコマンド ラインで指定する必要があります
  • --url <url> - サーバーの URL。 例: https://dev.azure.com/myorganization または http://my-azure-devops-server:8080/tfs
  • --auth <type> - 認証の種類。 次の値を指定できます。
    • pat (個人用アクセス トークン) - PAT は、Azure DevOps Services で動作する唯一のスキームです。
    • negotiate (Kerberos または NTLM)
    • alt (基本認証)
    • integrated (Windows の既定の資格情報)

認証オプション

  • --auth pat を選択した場合:
    • --token <token> - 個人用アクセス トークンを指定します
    • PAT は、Azure DevOps Services で動作する唯一のスキームです。
  • --auth negotiate または --auth alt を選択した場合:
    • --userName <userName> - Windows ユーザー名を domain\userName 形式または userName@domain.com 形式で指定します
    • --password <password> - パスワードを指定します

プール名とエージェント名

  • --pool <pool> - 参加するエージェントのプール名
  • --agent <agent> - エージェント名
  • --replace - プール内のエージェントを置き換えます。 別のエージェントが同じ名前でリッスンしている場合、競合で失敗し始めます

エージェントの設定

  • --work <workDirectory> - ジョブ データが格納されている作業ディレクトリ。 既定では、エージェント ディレクトリのルートの下の _work です。 作業ディレクトリは特定のエージェントによって所有されています。複数のエージェント間で共有しないでください。
  • --acceptTeeEula- Team Explorer Everywhere エンド ユーザー使用許諾契約書に同意します (macOS および Linux のみ)
  • --disableloguploads - コンソール ログ出力をサーバーにストリーミングしたり送信したりしないでください。 代わりに、ジョブの完了後にエージェント ホストのファイルシステムからそれらを取得できます。

Windows のみのスタートアップ

  • --runAsService - Windows サービスとして実行するようにエージェントを構成します (管理者権限が必要)
  • --runAsAutoLogon - 自動ログオンを構成し、起動時にエージェントを実行します (管理者権限が必要)
  • --windowsLogonAccount <account> - domain\userName または userName@domain.com の形式で --runAsService または --runAsAutoLogon と共に使用し、Windows ユーザー名を指定します
  • --windowsLogonPassword <password> - --runAsService または --runAsAutoLogon と共に使用し、Windows ログオン パスワードを指定します (グループ管理サービス アカウントと Windows 組み込みアカウント ('NT AUTHORITY\NETWORK SERVICE' など) には必要ありません)
  • --overwriteAutoLogon - --runAsAutoLogon と共に使用し、マシン上の既存の自動ログオンを上書きします
  • --noRestart - --runAsAutoLogon と共に使用し、エージェント構成の完了後にホストの再起動を停止します

runAsAutoLogon オプションを使用したエージェントの構成のトラブルシューティング

runAsAutoLogon オプションを使用してエージェントを構成すると、マシンを再起動するたびにエージェントが実行されます。 マシンの再起動後にエージェントが実行されない場合は、次の手順を実行します。

エージェントがマシンで既に構成されている場合

エージェントを再構成する前に、古いエージェント構成を削除する必要があるため、エージェント フォルダーから次のコマンドを実行してみてください:

.\config.cmd remove --auth 'PAT' --token '<token>'

コマンドの実行後にエージェントがエージェント プールから削除されたかどうかを確認します。

<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents

エージェントがコマンドを実行して削除されなかった場合は、エージェント プールから手動で削除します。

次に、エージェント フォルダーから次のコマンドを実行して、エージェントを再構成してみてください:

.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<domain\user-name>' --windowsLogonPassword '<windows-password>'

エージェント名 (特定の一意の名前) を指定し、再構成後、エージェント プールにこのエージェントが表示されたかどうかチェックします。

エージェント アーカイブ (ここでダウンロードできます) をアンパックし、新しいアンパックされたエージェント フォルダーからこのコマンドを実行することをお勧めします。

Windows レジストリ キーが記録され、正しく保存されているかどうかを確認する

whoami /user コマンドを実行して、<sid> を取得します。 Registry Editor を開き、パスに従います。

Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

VSTSAgent キーがあるかどうかを確認します。 このキーが存在する場合は削除し、Registry Editor を閉じ、エージェント フォルダーから .\config.cmd コマンド (引数なし) を実行してエージェント構成します。 Enter Restart the machine at a later time? の質問に答える前に、もう一度 Registry Editor を開き、VSTSAgent キーが表示されたかどうかをチェックします。 Enter を押して質問に答え、マシンの再起動後も VSTSAgent キーがその場所に残っているかどうかチェックします。

Windows レジストリ キーがコンピューターで正常に動作するかどうかを確認する

次の行が含まれている autorun.cmd ファイルを作成します: echo "Hello from AutoRun!" Registry Editor を開き、上記のパスにキー AutoRun と値を持つ新しいキーと値のペアを作成します

C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"

マシンを再起動します。 Hello from AutoRun! メッセージが表示されたコンソール ウィンドウが表示されない場合は、Windows レジストリ キーに問題があります。

配置グループのみ

  • --deploymentGroup - エージェントを配置グループ エージェントとして構成します
  • --deploymentGroupName <name> - --deploymentGroup と共に使用し、エージェントが参加する配置グループを指定します
  • --projectName <name> - --deploymentGroup と共に使用し、プロジェクト名を設定します
  • --addDeploymentGroupTags - --deploymentGroup と共に使用して、配置グループ タグを追加する必要があることを示します
  • --deploymentGroupTags <tags> - --addDeploymentGroupTags と共に使用し、配置グループ エージェントのタグのコンマ区切りリストを指定します (例: "web, db")

環境のみ

  • --addvirtualmachineresourcetags - 環境リソース タグを追加する必要があることを示すために使用されます
  • --virtualmachineresourcetags <tags> - --addvirtualmachineresourcetags と共に使用し、環境リソース エージェントのタグのコンマ区切りリストを指定します (例: "web, db")

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

診断

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

./run.sh --diagnostics

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

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

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

./config.sh --help

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

機能

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

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

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

重要

[機能] には、すべての環境変数と、エージェントの実行時に設定される値が含まれています。 これらの値のいずれかがエージェントの実行中に変更された場合は、エージェントを再起動して新しい値が採用されるようにする必要があります。 エージェントに新しいソフトウェアをインストールしたら、新しい機能がプールに表示されるようにエージェントを再起動して、ビルドを実行できるようにする必要があります。

機能としての環境変数を除外する場合は、無視する変数のコンマ区切りのリストによって環境変数 VSO_AGENT_IGNORE を設定すると、該当する環境変数を指定できます。

よく寄せられる質問

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

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

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

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

      [組織の設定] を選びます。

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

      [エージェント プール] タブを選びます。

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

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

      [コレクションの設定] を選びます。

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

      [エージェント プール] を選びます。

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

      コレクションの設定 (2019)。

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

      [エージェント プール] を選びます (2019)。

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

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

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

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

      [エージェント プール] で、目的のエージェント プールを選びます。

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

      [エージェント] を選んで、エージェントを選びます。

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

      [機能] タブを選びます。

      注意

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

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

      目的のプールを選びます。

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

      [エージェント] を選んで、目的のエージェントを選びます。

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

      エージェントの [機能] タブ。

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

      目的のタブを選びます (2019)。

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

      目的のエージェントを選びます (2019)。

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

      [機能] タブを選びます (2019)。

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

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

Azure DevOps Server プールの一部であるエージェントを更新できますか?

はい。 Azure DevOps Server 2019 以降では、ローカル ディスク上のエージェント パッケージ ファイルを検索するようにサーバーを構成できます。 この構成により、リリース時にサーバーに付属した既定のバージョンがオーバーライドされます。 このシナリオは、サーバーがインターネットにアクセスできない場合にも適用されます。

  1. インターネットにアクセスできるコンピューターから、Azure Pipelines Agent GitHub リリース ページの最新バージョンのエージェント パッケージ ファイル (.zip または .tar.gz 形式) をダウンロードします。

  2. 任意の方法 (USB ドライブ、ネットワーク転送など) を使って、ダウンロードしたパッケージ ファイルを各 Azure DevOps Server アプリケーション層に転送します。 エージェント ファイルを次のフォルダーの下に配置します。

  • Windows: %ProgramData%\Microsoft\Azure DevOps\Agents
  • Linux: usr/share/Microsoft/Azure DevOps/Agents
  • macOS: usr/share/Microsoft/Azure DevOps/Agents

Agents フォルダーが存在しない場合は作成します。

  1. すべての設定が完了しました。 Azure DevOps Server では、エージェントが更新されるたびにローカル ファイルが使われるようになります。 各エージェントは、新しいバージョンのエージェントを必要とするタスクを実行すると、自動的に更新されます。 ただし、一部のエージェントを手動で更新する場合は、プールを右クリックし、[すべてのエージェントを更新] を選択します。

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

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

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

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

      [組織の設定] を選びます。

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

      [エージェント プール] タブを選びます。

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

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

      [コレクションの設定] を選びます。

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

      [エージェント プール] を選びます。

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

      コレクションの設定 (2019)。

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

      [エージェント プール] を選びます (2019)。

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

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

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

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

      [エージェント プール] で、目的のエージェント プールを選びます。

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

      [エージェント] を選んで、エージェントを選びます。

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

      [機能] タブを選びます。

      注意

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

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

      目的のプールを選びます。

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

      [エージェント] を選んで、目的のエージェントを選びます。

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

      エージェントの [機能] タブ。

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

      目的のタブを選びます (2019)。

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

      目的のエージェントを選びます (2019)。

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

      [機能] タブを選びます (2019)。

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

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

Azure DevOps Server プールの一部である v2 エージェントを更新できますか?

はい。 Azure DevOps Server 2019 以降では、ローカル ディスク上のエージェント パッケージ ファイルを検索するようにサーバーを構成できます。 この構成により、リリース時にサーバーに付属した既定のバージョンがオーバーライドされます。 このシナリオは、サーバーがインターネットにアクセスできない場合にも適用されます。

  1. インターネットにアクセスできるコンピューターから、Azure Pipelines Agent GitHub リリース ページの最新バージョンのエージェント パッケージ ファイル (.zip または .tar.gz 形式) をダウンロードします。

  2. 任意の方法 (USB ドライブ、ネットワーク転送など) を使って、ダウンロードしたパッケージ ファイルを各 Azure DevOps Server アプリケーション層に転送します。 エージェント ファイルを %ProgramData%\Microsoft\Azure DevOps\Agents フォルダーの下に配置します。 Agents フォルダーが存在しない場合は作成します。

  3. すべての設定が完了しました。 Azure DevOps Server では、エージェントが更新されるたびにローカル ファイルが使われるようになります。 各エージェントは、新しいバージョンのエージェントを必要とするタスクを実行すると、自動的に更新されます。 ただし、一部のエージェントを手動で更新する場合は、プールを右クリックし、[すべてのエージェントを更新] を選択します。

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

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

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

ファイアウォールを実行し、自分のコードが Azure Repos。 エージェントは、どのような URL と通信する必要がありますか?

ファイアウォールの背後にある安全なネットワークでエージェントを実行している場合、次の URL と IP アドレスにエージェントが通信を開始できるようにしてください。

ドメイン URL 説明
https://{organization_name}.pkgs.visualstudio.com {organization_name}.visualstudio.com ドメインを使用している組織向けの Azure DevOps Packaging API
https://{organization_name}.visualstudio.com {organization_name}.visualstudio.com ドメインを使用している組織向け
https://{organization_name}.vsblob.visualstudio.com {organization_name}.visualstudio.com ドメインを使用している組織向けの Azure DevOps テレメトリ
https://{organization_name}.vsrm.visualstudio.com {organization_name}.visualstudio.com ドメインを使用している組織向けの Release Management サービス
https://{organization_name}.vssps.visualstudio.com {organization_name}.visualstudio.com ドメインを使用している組織向けの Azure DevOps プラットフォーム サービス
https://{organization_name}.vstmr.visualstudio.com {organization_name}.visualstudio.com ドメインを使用している組織向けの Azure DevOps テスト管理サービス
https://*.blob.core.windows.net Azure Artifacts
https://*.dev.azure.com dev.azure.com ドメインを使用している組織向け
https://*.vsassets.io CDN を使用した Azure Artifacts
https://*.vsblob.visualstudio.com dev.azure.com ドメインを使用している組織向けの Azure DevOps テレメトリ
https://*.vssps.visualstudio.com dev.azure.com ドメインを使用している組織向けの Azure DevOps プラットフォーム サービス
https://*.vstmr.visualstudio.com dev.azure.com ドメインを使用している組織向けの Azure DevOps テスト管理サービス
https://app.vssps.visualstudio.com {organization_name}.visualstudio.com ドメインを使用している組織向け
https://dev.azure.com dev.azure.com ドメインを使用している組織向け
https://login.microsoftonline.com Microsoft Entra サインイン
https://management.core.windows.net Azure Management API
https://vstsagentpackage.azureedge.net エージェント パッケージ

組織が既存のファイアウォールまたは IP 制限で動作することを確認するには、dev.azure.com と *dev.azure.com が開かれていることを確認し、許可リストの IP を更新して、IP バージョンに基づいて次の IP アドレスを含むようにします。 現在、13.107.6.183 と 13.107.9.183 の IP アドレスを許可している場合は、それらを削除する必要はないため、そのままにしておきます。

IPv4 の範囲

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6 の範囲

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

注意

許可されるアドレスの詳細については、「許可されたアドレス リストとネットワーク接続」を参照してください。

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

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

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

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

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

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

Web プロキシをバイパスして Azure Pipelines に接続するようにエージェントを構成するにはどうすればよいですか?

エージェントでプロキシをバイパスして Azure Pipelines に直接接続する場合は、エージェントが次の URL にアクセスできるように Web プロキシを構成する必要があります。

*.visualstudio.com ドメインを使用している組織の場合:

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

dev.azure.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

組織が既存のファイアウォールまたは IP 制限で動作することを確認するには、dev.azure.com と *dev.azure.com が開かれていることを確認し、許可リストの IP を更新して、IP バージョンに基づいて次の IP アドレスを含むようにします。 現在、13.107.6.183 と 13.107.9.183 の IP アドレスを許可している場合は、それらを削除する必要はないため、そのままにしておきます。

IPv4 の範囲

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6 の範囲

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

注意

この手順により、エージェントは Web プロキシをバイパスできるようになります。 ビルド パイプラインとスクリプトでは、ビルドで実行するタスクとツールごとに Web プロキシのバイパスを引き続き処理する必要があります。

たとえば、NuGet タスクを使用している場合は、使用している NuGet フィードをホストするサーバーの URL のバイパスをサポートするように Web プロキシを構成する必要があります。

TFS を使用しており、上記のセクションの URL は機能しません。 情報はどこで入手できますか?

Web サイトの設定とセキュリティ

TFS をオンプレミスで使用していますが、これらの機能の一部が表示されません。 なぜでしょうか。

これらの機能の一部は Azure Pipelines でのみ使用でき、オンプレミスではまだ使用できません。 TFS の最新バージョンにアップグレードした場合は、一部の機能をオンプレミスで使用できます。