セルフホスト型 Windows エージェント

Azure DevOps Services

Windows、Azure、およびその他の Visual Studio ソリューションをビルドしてデプロイするには、少なくとも 1 つの Windows エージェントが必要です。 Windows エージェントでは、Java アプリと Android アプリをビルドすることもできます。

エージェントの詳細

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

前提条件を確認する

コンピューターに次の前提条件があることを確認します。

• オペレーティング システムのバージョン
  • クライアント OS
    • Windows 7 SP1 ESU
    • Windows 8.1
    • Windows 10
    • Windows 11
  • サーバー OS
    • Windows Server 2012 以降
• エージェント ソフトウェアは独自のバージョンの .NET をインストールするため、.NET の前提条件はありません。
• PowerShell 3.0 以降
• Subversion - Subversion リポジトリからビルドする場合は、Subversion クライアントをマシンにインストールする必要があります。
• 推奨 - Visual Studio ビルド ツール (2015 以降)

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

ハードウェア 仕様

エージェントのハードウェア 仕様は、ニーズ、チーム サイズなどによって異なります。すべてのユーザーに適用される一般的な推奨事項を作成することはできません。 参照ポイントとして、Azure DevOps チームは、ホストされたエージェントを利用するパイプラインを使用して 、ホストされたエージェント コードをビルドします。 一方、Azure DevOps コードの大部分は、4 つのセルフホステッド エージェントを実行する 24 コア のサーバー クラス マシンによって構築されます。

アクセス許可を準備する

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

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

エージェントによって制御されるフォルダーには、復号化または流出できるシークレットが含まれているため、できるだけ少数のユーザーに制限する必要があります。

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

そのため、パイプライン エージェントの個々の使用状況を取り巻く脅威モデルを考慮して作業を実行し、エージェントを実行しているユーザーに付与できる最小限のアクセス許可を、エージェントが実行されるマシンに対して、Pipeline 定義への書き込みアクセス権を持つユーザー (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. [エージェント プール] を選択します。

      

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

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

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

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

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

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. [エージェント プール] を選択します。

      

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

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

5. 左側のウィンドウで、コンピューターにインストールされている Windows OS バージョンのプロセッサ アーキテクチャを選択します。 x64 エージェント バージョンは 64 ビット Windows を対象としていますが、x86 バージョンは 32 ビット Windows を対象としています。 インストールされている Windows のバージョンがわからない場合は、 次の手順に従って確認してください。

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

7. ページの指示に従ってエージェントをダウンロードします。

8. 任意のディレクトリにエージェントを展開します。 ツールとスクリプトでスペースが常に正しくエスケープされるとは限らないので、ディレクトリへのパスにスペースが含まれていないことを確認してください。 推奨されるフォルダーは C:\agents。 ダウンロード フォルダーまたはその他のユーザー フォルダーで抽出すると、アクセス許可の問題が発生する可能性があります。

エージェントをインストールする

1. 管理者特権 (PowerShell) ウィンドウを起動し、エージェントをアンパックした場所に場所を設定します。

   cd C:\agents 
   
   

2. config.cmd を実行します。 これにより、エージェントを構成するための一連の質問が表示されます。

   .\config.cmd
   
   

サーバーのURL

エージェントセットアップ認証の種類

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

エージェントの登録に使用される認証方法は、エージェントの登録時にのみ使用されます。 登録後にエージェントが Azure Pipelines と通信する方法の詳細については、「 Azure Pipelines または TFS との通信」を参照してください。

対話型モードまたはサービス モードを選択する

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

サービスとして実行する場合 (推奨)、実行するユーザー名は 20 文字以下にする必要があります。

エージェントを実行する

インタラクティブに実行する

対話形式で実行するようにエージェントを構成した場合は、次のコマンドを実行してエージェントを起動します。

.\run.cmd

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

variables:
 AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL: "true"

1 回実行する

エージェントが 1 つのジョブのみを受け入れて終了するように選択することもできます。 この構成で実行するには、次のコマンドを使用します。

.\run.cmd --once

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

サービスとして実行する

サービスとして実行するようにエージェントを構成した場合、エージェントは自動的に開始されます。 サービス スナップインからエージェントの実行状態を表示および制御できます。 services.mscを実行し、次のいずれかを探します。

• "Azure Pipelines エージェント (エージェントの名前)"
• "VSTS エージェント (エージェントの名前)"
• "vstsagent。(組織名)。(エージェントの名前)"

エージェントを再起動するには、エントリを右クリックし、[再起動] を選択 します。

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

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

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

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

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

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

.\config remove

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

無人構成

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

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

必須オプション

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

認証オプション

• --auth pat を選択した場合:
  • --token <token> - 個人用アクセス トークンを指定します
  • --token パラメーターとして OAuth 2.0 トークンを渡すこともできます。
• --auth negotiate または --auth alt を選択した場合:
  • --userName <userName> - Windows ユーザー名を ___domain\userName 形式または userName@___domain.com 形式で指定します
  • --password <password> - パスワードを指定します
• --auth SP を選択した場合:
  • --clientID <clientID> - 登録エージェントへのアクセス権を持つサービス プリンシパルのクライアント ID を指定します
  • --tenantId <tenantID> - サービス プリンシパルが登録されているテナント ID を指定します。
  • --clientSecret <clientSecret> - サービス プリンシパルのクライアント シークレットを指定します
  • 詳細については、「 サービス プリンシパルを使用してエージェントを登録 する」を参照してください。

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

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

エージェントの設定

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

Windows のみのスタートアップ

• --runAsService - Windows サービスとして実行するようにエージェントを構成します (管理者権限が必要)
• --runAsAutoLogon - 自動ログオンを構成し、起動時にエージェントを実行します (管理者権限が必要)
• --windowsLogonAccount <account> - --runAsService または --runAsAutoLogon の形式で ___domain\userName または userName@___domain.com と共に使用し、Windows ユーザー名を指定します
• --windowsLogonPassword <password> - --runAsService または --runAsAutoLogon と共に使用し、Windows ログオン パスワードを指定します (グループ管理サービス アカウントと Windows 組み込みアカウント ('NT AUTHORITY\NETWORK SERVICE' など) には必要ありません)
• --enableservicesidtypeunrestricted - --runAsService とともに使用して、サービス SID タイプを SERVICE_SID_TYPE_UNRESTRICTED としてエージェントを構成します (管理者の許可が必要です)
• --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 --help 常に、最新の必須応答と省略可能な応答を一覧表示します。

診断

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

.\run --diagnostics

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

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

その他のオプションについて知るためには：

.\config --help

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

能力

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

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

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

よくあるご質問

エージェントはどのバージョンの Git を実行しますか?

既定では、エージェント ソフトウェアにバンドルされている Git のバージョンが Windows エージェントで使われます。 Microsoft は、エージェントにバンドルされている Git のバージョンを使うことをお勧めしますが、この既定の動作をオーバーライドし、エージェント コンピューターのパスにインストールされている Git のバージョンを使うためのオプションがいくつかあります。

• パイプラインで System.PreferGitFromPath という名前のパイプライン変数を true に設定します。
• セルフホステッド エージェントでは、エージェントのルート ディレクトリに .env という名前のファイルを作成し、そのファイルに System.PreferGitFromPath=true という行を追加できます。 詳しくは、「エージェントごとに異なる環境変数を設定するにはどうすればよいですか?」をご覧ください。

パイプラインで使われている Git のバージョンは、次の例で示すように、パイプラインのログの checkout ステップで確認できます。

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

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

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

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

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

      

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

      

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

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

      

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

      

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

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

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

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

      

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

      

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

      

      注

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

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

      

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

      

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

      

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

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

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

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

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

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

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

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

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

MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4

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://download.agent.dev.azure.com
https://vssps.dev.azure.com

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

エージェント サービスのSERVICE_SID_TYPE_UNRESTRICTEDを有効にする方法

Windows Server でエージェント ソフトウェアを構成する場合は、次のプロンプトからサービス セキュリティ識別子を指定できます。

Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N)

以前のバージョンのエージェント ソフトウェアでは、サービス セキュリティ識別子の種類が SERVICE_SID_TYPE_NONE に設定されています。これは、現在のエージェント バージョンの既定値です。 セキュリティ サービス識別子の種類を SERVICE_SID_TYPE_UNRESTRICTEDするように構成するには、 Yキーを押します。

詳細については、「 SERVICE_SID_INFO構造 と セキュリティ識別子」を参照してください。