Azure Pipelines Agent Poolsは、ビルドやリリースを実行するエージェントを「どのチーム・どの用途・どの権限で使うか」を決める管理単位です。今回まず押さえるべき結論は、すぐに全パイプラインを書き換えるような一律の移行対応ではなく、プールの権限、YAMLでの指定、セルフホステッドエージェントのメンテナンス、Microsoft-hosted agentsのイメージ選択を点検することです。
特に管理者は「誰がプールを使えるか」「どのYAMLパイプラインに許可しているか」「古い作業ディレクトリのクリーンアップが動くか」を確認してください。開発者は、pool と vmImage の指定、セルフホステッド環境での demands、ホステッドイメージの変更リスクを見直すと、ビルド待ち・権限エラー・環境差分による失敗を減らせます。
Azure Pipelines Agent Poolsとは
Azure Pipelines Agent Poolsは、Azure PipelinesやAzure DevOps Serverでビルド・テスト・デプロイジョブを実行するエージェントをまとめる仕組みです。公式ドキュメントでは、エージェントプールは「エージェントのコレクション」と説明されており、パイプライン実行時には、そのプール内でパイプラインの要求を満たすエージェントが選ばれます。Azure Pipelinesではプールのスコープは組織全体、Azure DevOps Serverではサーバー全体です。(Microsoft Learn)
エージェントは、ジョブを実行するためのコンピューティング環境です。Azure Pipelinesでコードをビルドしたりソフトウェアをデプロイしたりするには、少なくとも1つのエージェントが必要です。各エージェントは基本的に1度に1つのジョブを実行します。(Microsoft Learn)
実務では、エージェントプールを次のように使い分けます。
| 用途 | 代表的なプール | 向いているケース |
|---|---|---|
| すぐにCI/CDを始めたい | Azure Pipelines | Microsoftが管理するWindows、Linux、macOSイメージで標準的なビルドを行う |
| 社内ツールや独自SDKが必要 | Defaultなどのセルフホステッドプール | 専用ソフト、社内ネットワーク、ライセンスサーバー、キャッシュを使う |
| カスタムプールを管理負荷少なく使いたい | Managed DevOps Pools | Azure portal側で管理し、スケーリング・ネットワーク・セキュリティをまとめて設計したい |
既定では、セルフホステッドエージェント登録用のDefaultプールと、Microsoft-hosted agentsを使うAzure Pipelinesプールが用意されています。(Microsoft Learn)
2026年5月更新の位置づけ
公式リポジトリの履歴では、対象ファイルを含む一括更新が2026年5月7日に行われています。コミット内容は「非推奨のms.assetidメタデータを全記事から削除する」というもので、655ファイルに対するメタデータ整理です。(GitHub) (GitHub)
そのため、今回の更新は「エージェントプールの機能仕様が大きく変わった」と見るより、公式情報に沿って既存のエージェントプール運用を棚卸しするタイミングと捉えるのが現実的です。公開ページ本文で重要なのは、プールのスコープ、作成手順、YAMLでの指定、CLIでの確認、権限、メンテナンスジョブの扱いです。(Microsoft Learn)
影響を受けやすい利用者と管理者
今回確認すべき対象は、Azure Pipelinesを使っているすべてのチームですが、特に影響を受けやすいのは次のケースです。
| 対象 | 確認すべきこと | 放置した場合に起きやすい問題 |
|---|---|---|
| Azure DevOps組織管理者 | 組織レベルのエージェントプール権限 | 不要なユーザーがプールを管理できる、または必要なユーザーが実行できない |
| プロジェクト管理者 | プロジェクトレベルのUser/Admin権限 | パイプライン作成者がプールを使えない |
| YAMLパイプライン作成者 | pool、vmImage、demandsの指定 | ジョブが想定外の環境で動く、またはキューに残る |
| セルフホステッドエージェント運用者 | ディスク容量、メンテナンスジョブ、エージェント状態 | 古い作業ディレクトリが残り、ディスク不足やメンテナンス停止が起きる |
| Azure DevOps Server利用者 | Microsoft-hosted agentsやCLI対応範囲 | Azure DevOps Services向けの前提を誤って適用する |
Microsoft-hosted agentsはAzure DevOps Servicesでのみ利用できます。オンプレミスのAzure DevOps ServerではMicrosoft-hosted agentsやAzure Pipelinesプールは使えず、セルフホステッドエージェントを使う必要があります。(Microsoft Learn)
エージェントプールの選び方
まずはMicrosoft-hosted agentsで十分か判断する
標準的なWebアプリ、.NET、Node.js、Python、Java、コンテナビルドなどであれば、多くの場合はMicrosoft-hosted agentsから始めるのが安全です。Microsoft-hosted agentsでは、メンテナンスやアップグレードが自動で行われ、ジョブごとに新しい仮想マシンが割り当てられます。ジョブ完了後に仮想マシンは破棄されるため、前回ジョブのファイルや設定は残りません。(Microsoft Learn)
ただし、再現性を重視する本番リリースでは、ubuntu-latestやwindows-latestのような「latest」指定だけに頼りすぎない方が安全です。ホステッドイメージは更新・廃止されることがあるため、重要なパイプラインでは具体的なイメージを指定し、更新前に検証用パイプラインで動作確認する運用が向いています。Windows Server 2019 hosted agent imageの廃止や、Windows Server 2025 with Visual Studio 2026のプレビュー提供など、ホステッドイメージにはライフサイクルがあります。(Microsoft Learn)
pool:
vmImage: ubuntu-24.04短期の検証や一般的なCIではubuntu-latestでも始められますが、長期間安定稼働させるパイプラインでは、利用するOSイメージを明示しておくとトラブル調査がしやすくなります。
セルフホステッドエージェントを選ぶべきケース
次の条件に当てはまる場合は、セルフホステッドエージェントを検討してください。
- 社内ネットワーク上のサーバーやデータベースへ直接接続する必要がある
- 有償SDK、専用ビルドツール、特殊なランタイムを事前インストールしたい
- ビルドキャッシュや大容量依存ファイルをジョブ間で残したい
- Microsoft-hosted agentsのイメージ更新に影響されたくない
- セキュリティ要件上、実行環境を自社管理したい
セルフホステッドエージェントは依存ソフトを自由に入れられ、マシンレベルのキャッシュや設定がジョブ間で維持されます。一方で、Microsoftは1台のマシンに複数エージェントを入れることについて、パフォーマンスやパイプライン結果に悪影響が出る可能性があるとして、原則1台1エージェントを強く推奨しています。(Microsoft Learn)
Managed DevOps Poolsを検討すべきケース
Managed DevOps Poolsは、カスタムエージェントプールをより管理しやすくする選択肢です。公式ドキュメントでは、Managed DevOps PoolsのエージェントプールはAzure portalで管理されると説明されています。プール作成時には、Azure DevOps組織、プール名、リージョン、最大エージェント数、VMサイズ、OSディスク、イメージ、スケーリング、ネットワーク、ストレージ、セキュリティなどを指定できます。(Microsoft Learn)
特に、セルフホステッド相当の柔軟性が必要だが、スケーリングやカスタムプール管理の負担を減らしたいチームに向いています。作成時は、リージョン、VM SKUのクォータ、対象プロジェクト、プール管理者権限を事前に確認してください。クォータ不足の場合、指定したVMサイズや最大エージェント数でプール作成に失敗する可能性があります。(Microsoft Learn)
管理者が最初に確認すべき権限設定
組織レベルのロール
エージェントプールの権限は、組織レベルとプロジェクトレベルで分かれます。組織レベルでは、Reader、Service Account、Administratorのロールが定義されています。Administratorは、エージェントの登録・登録解除、組織エージェントプールの参照、ロールメンバーシップ管理まで実行できます。(Microsoft Learn)
| ロール | 主な用途 | 管理上の注意 |
|---|---|---|
| Reader | プールとエージェントの閲覧 | 監視担当者向け。編集権限を与えたくない場合に使う |
| Service Account | 組織プールからプロジェクトプールを作成 | 通常はむやみに追加しない |
| Administrator | 登録、登録解除、権限管理 | 最小限の管理者に限定する |
特に注意したいのは、All agent poolsに対する権限です。個別プールの権限は上位設定から継承されるため、全体に強い権限を与えすぎると、後から作成したプールにも広く権限が及ぶ可能性があります。
プロジェクトレベルのロール
プロジェクトレベルでは、Reader、User、Administratorのロールが使われます。Userは、パイプライン作成時にプロジェクトエージェントプールを使用できるロールです。開発者が「プールを選べない」「ビルドをキューに入れられない」と言っている場合、まずUser権限の有無を確認してください。(Microsoft Learn)
| ロール | 主な用途 | 設定の目安 |
|---|---|---|
| Reader | ジョブやプールの閲覧 | 運用監視担当者 |
| User | パイプラインからプールを利用 | 開発者、CI/CD作成者 |
| Administrator | プロジェクトプールの権限管理 | プロジェクト管理者、DevOps担当 |
Microsoft-hosted poolを選択できず、ビルドをキューに入れられない場合は、Azure DevOps組織の所有者にプール使用権限を付与してもらう必要があります。(Microsoft Learn)
パイプライン権限はYAMLとクラシックで効き方が違う
エージェントプールの「Pipeline permissions」は、どのYAMLパイプラインがプールを使えるかを制御する機能です。ただし、クラシックパイプラインからのアクセスはこの設定では制限されません。(Microsoft Learn)
設定方針は大きく2つです。
| 方針 | 向いているケース | 注意点 |
|---|---|---|
| すべてのパイプラインに開放 | 小規模チーム、検証環境、標準CI | 意図しないパイプラインからセルフホステッド環境を使われる可能性がある |
| 選択したYAMLパイプラインだけ許可 | 本番デプロイ、社内ネットワーク接続、秘密情報を扱うプール | 新しいパイプライン作成時に承認作業が必要 |
セルフホステッドエージェントが社内ネットワーク、データベース、署名証明書、デプロイ先環境に到達できる場合は、原則としてロックダウンし、承認済みのYAMLパイプラインだけに許可するのが安全です。
一方、Azure Pipelinesエージェントプールは既定ですべてのパイプラインからアクセスできるため、パイプライン権限を構成できません。(Microsoft Learn)
YAMLでのプール指定を見直す
Microsoft-hosted agentsを使う場合
Microsoft-hosted agentsでは、poolにvmImageを指定します。ubuntu-latestは、プールやVMイメージを指定しない場合の既定として扱われる説明があります。(Microsoft Learn)
pool:
vmImage: ubuntu-latest本番リリースや長期運用では、次のように具体的なイメージを指定する方が変更影響を追いやすくなります。
pool:
vmImage: ubuntu-24.04セルフホステッドプールを使う場合
プライベートプールを使う場合は、プール名を指定します。プール名にスペースがある場合は、シングルクォートで囲みます。(Microsoft Learn)
pool: MyPoolpool:
name: 'My Pool'複数のセルフホステッドエージェントがあり、特定のOSやソフトウェアを持つエージェントだけにジョブを流したい場合は、demandsを使います。demandsでサポートされる主な判定は、Capabilityの存在確認と値の一致確認です。(Microsoft Learn)
pool:
name: MyPool
demands:
- Agent.OS -equals Linux
- SpecialSoftware注意点は、demandsが一致するエージェントがないとジョブが実行されないことです。たとえば、SpecialSoftwareというCapabilityを要求しているのに、どのエージェントにも登録されていなければ、そのジョブは実行対象を見つけられません。新しいソフトウェアをセルフホステッドエージェントにインストールした後は、Capabilityに反映させるためエージェント再起動が必要になる場合があります。(Microsoft Learn)
Azure DevOps CLIで棚卸しする
Azure DevOps CLIでは、エージェントプールやキューの情報を表示できます。ただし、公式ドキュメントでは、CLIで表示はできるものの編集はできないとされています。また、Azure DevOps CLIコマンドはAzure DevOps Serverではサポートされていません。(Microsoft Learn)
まず、組織とプロジェクトを既定値として設定します。
az devops configure --defaults organization=https://dev.azure.com/<organization> project=<project>プール一覧を確認します。
az pipelines pool list --output table特定プールの詳細を確認します。
az pipelines pool show --id <pool-id> --output tableプロジェクト側のキューを確認します。
az pipelines queue list --project <project> --output table棚卸しでは、次の観点で確認すると効率的です。
| 確認項目 | 見るべきポイント |
|---|---|
| プール名 | YAMLで指定している名前と一致しているか |
| Is hosted | Microsoft-hostedかセルフホステッドか |
| Pool type | automation用途か、deployment用途か |
| キュー | プロジェクト側から参照できる状態か |
| 権限 | 対象ユーザーがuseまたはmanageできるか |
CLIは編集用途ではなく、現状把握と監査に使うのが基本です。権限変更、パイプライン許可、メンテナンス設定はAzure DevOpsのUIで確認する運用にしておくと、チーム内で説明しやすくなります。
セルフホステッドエージェントのメンテナンス設定
セルフホステッドエージェントで見落としやすいのが、古い作業ディレクトリやリポジトリのクリーンアップです。公式ドキュメントでは、エージェントプールに対してメンテナンスジョブを構成でき、ディスク領域不足のリスクを軽減できると説明されています。(Microsoft Learn)
ただし、メンテナンス期間を設定していない場合、そのプール内のエージェントはメンテナンスジョブを実行しません。さらに、メンテナンスはマシン単位ではなくエージェントプール単位で行われます。1台のマシンに複数プールのエージェントを置いている場合、片方のプールだけをメンテナンスしてもディスク不足が残る可能性があります。(Microsoft Learn)
管理者は次の設定を確認してください。
| 確認項目 | 推奨アクション |
|---|---|
| メンテナンス期間 | 夜間や休日など、ビルドが少ない時間帯に設定する |
| メンテナンス履歴 | 実行ログを確認し、削除対象や失敗理由を把握する |
| オフラインエージェント | 長期間オフラインのエージェントをプールから整理する |
| ディスク容量 | エージェント作業ディレクトリ、依存キャッシュ、成果物の残存を定期確認する |
| 権限 | メンテナンス設定に必要なManage build queues権限を持つ管理者を明確にする |
メンテナンスジョブが停止しているように見える場合、プールから外れたエージェントや通信できないエージェントでの実行待ちになっていることがあります。キューに入ったメンテナンスジョブは最大7日待機し、その間に実行されなければ失敗状態になります。この制限は変更できません。(Microsoft Learn)
移行・展開時に失敗しやすいポイント
プール名だけ変更してYAMLを更新していない
エージェントプール名を変更したり、新しいプールに移行したりした場合は、既存YAMLのpool指定を必ず検索してください。プール指定は、パイプライン、ステージ、ジョブの各レベルで指定できます。最も下位レベルにある指定がそのジョブで使われます。(Microsoft Learn)
たとえば、パイプライン全体では新しいプールを指定していても、特定ジョブだけ古いプール名を指定していると、そのジョブだけ失敗することがあります。
pool:
name: NewPool
jobs:
- job: legacy_build
pool:
name: OldPool
steps:
- script: echo "This job still uses OldPool"移行時は、リポジトリ全体でpool:、vmImage:、古いプール名を検索し、ジョブ単位の上書きがないか確認してください。
vmImageとセルフホステッドプールを混同している
vmImageはMicrosoft-hosted poolで使う指定です。セルフホステッドプールでは、プール名と必要に応じてdemandsを指定します。公式YAMLスキーマでも、vmImageはMicrosoft-hosted poolで有効なプロパティとして説明されています。(Microsoft Learn)
悪い例は、セルフホステッドプール名を指定しながら、同時にvmImageでOSイメージを選ぼうとする書き方です。環境を固定したい場合は、セルフホステッドエージェント側にOSやツールを用意し、demandsで一致条件を指定します。
クラシックパイプラインのアクセス制御をYAMLと同じだと思っている
Pipeline permissionsはYAMLパイプラインのプール利用を制御しますが、クラシックパイプラインのアクセスは制限しません。(Microsoft Learn)
そのため、社内ネットワークへ到達できるセルフホステッドプールを運用している場合、YAML側だけをロックダウンしても不十分なことがあります。クラシックパイプラインが残っている組織では、次の対応を検討してください。
| 状況 | 対応 |
|---|---|
| クラシックパイプラインを継続利用 | 作成者・編集者・リリース管理者の権限を別途確認する |
| YAMLへ移行予定 | 移行対象、移行順、プール権限をセットで整理する |
| 本番デプロイ用プールを保護したい | 専用プールを作り、許可済みパイプラインだけに使わせる |
並列ジョブ数とエージェント数を混同している
エージェントを増やしても、組織側の並列ジョブ数が不足していると、同時実行数は期待どおり増えません。Azure Pipelinesでは、同時に実行できるジョブ数を表す「parallel jobs」の概念があります。1つの並列ジョブしかなければ、他のジョブは先行ジョブが終わるまでキューに残ります。(Microsoft Learn)
「エージェントは空いているのにジョブが進まない」と見える場合は、エージェント状態だけでなく、並列ジョブの上限も確認してください。ホステッドビルドリソースが不足する場合は、セルフホステッドエージェントを用意するか、並列ジョブの追加購入を検討する選択肢があります。(Microsoft Learn)
管理者向けチェックリスト
| チェック項目 | 確認場所 | 判断基準 |
|---|---|---|
| 組織プールの管理者 | Organization settings > Agent pools > Security | Administratorが必要最小限か |
| プロジェクトプールのUser権限 | Project settings > Agent pools > Security | パイプライン作成者が使えるか |
| Pipeline permissions | Agent pool > Security | 本番・社内接続プールは承認済みYAMLのみに限定する |
| Microsoft-hosted image | YAMLのvmImage | latest依存を許容できるか |
| セルフホステッドCapability | Agent > Capabilities | demandsと実際のCapabilityが一致するか |
| メンテナンスジョブ | Agent pool > Settings / Maintenance History | 期間設定、履歴、失敗ログを確認する |
| CLI棚卸し | az pipelines pool listなど | プール・キュー・プロジェクト参照を一覧化する |
| Azure DevOps Server対応 | 利用環境 | Microsoft-hosted agentsやAzure DevOps CLI前提を誤適用していないか |
開発者向けチェックリスト
| チェック項目 | 具体的な確認方法 |
|---|---|
| YAMLのプール指定 | pool:がパイプライン、ステージ、ジョブのどこにあるか確認する |
| ホステッドイメージ | ubuntu-latest、windows-latestを使っている場合は固定化の必要性を判断する |
| セルフホステッド要求 | demandsで要求しているCapabilityが実エージェントに存在するか確認する |
| 権限エラー | プールのUser権限、Pipeline permissions、承認要求を確認する |
| 長時間キュー待ち | エージェントのオンライン状態、並列ジョブ数、Capability不一致を確認する |
| 環境差分 | Microsoft-hostedは毎回新しいVM、セルフホステッドは状態が残ることを前提にテストする |
まず取るべき次の行動
Azure Pipelines Agent Poolsの運用で最初にやるべきことは、新しい機能を探すことではなく、現在のプール構成を見える化することです。管理者はCLIでプールとキューを棚卸しし、UIで権限とPipeline permissionsを確認してください。開発者はYAMLのpool、vmImage、demandsを検索し、想定した環境でジョブが動いているか確認します。
小規模チームや標準的なCI/CDなら、まずMicrosoft-hosted agentsで十分です。社内ネットワーク、独自ツール、キャッシュ、厳格な実行環境が必要なら、セルフホステッドエージェントまたはManaged DevOps Poolsを検討します。いずれの場合も、プールは「ジョブを動かす場所」ではなく、権限・セキュリティ・再現性・コストをまとめて設計する単位として扱うことが、安定したAzure Pipelines運用につながります。
コメント