配置グループのエージェントをプロビジョニングする

[アーティクル]
11/21/2024

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

デプロイグループは、Azure Pipelines のクラシックリリースパイプラインのデプロイターゲットマシンの論理グループです。展開グループ内のすべてのターゲットサーバーには、デプロイエージェントがインストールされている必要があります。この記事では、デプロイグループ内の各物理マシンまたは仮想マシン (VM) にデプロイエージェントをインストールしてプロビジョニングする方法について説明します。

次のいずれかの方法で、ターゲットコンピューターにエージェントをインストールできます。

デプロイグループの作成時に生成されるスクリプトを実行します。
Azure Pipelines Agent Azure VM 拡張機能を VM にインストールします。
リリースパイプラインの AzureResourceGroupDeploymentV2 タスク を使用して、デプロイグループを作成し、エージェントを動的にプロビジョニングします。

次のセクションでは、各メソッドを実装する手順について説明します。

前提条件

Azure DevOps 組織とプロジェクト。組織またはプロジェクトを作成するには、「新しい組織を作成する」または「Azure DevOps でプロジェクトを作成する」を参照してください。
割り当てアクセス許可を持つ少なくとも 1 つの Windows または Linux デプロイターゲットマシンへのアクセス。
Azure Pipelines エージェントのインストール方法の場合、Azure VM を作成および管理するためのアクセス許可を持つ Azure アカウントとサブスクリプション。 Azure アカウントを持っていない場合は、無料アカウントにサインアップできます。

ターゲットサーバーでインストールスクリプトを実行する

デプロイグループを作成すると、各ターゲットコンピューターで実行してサーバーを登録し、エージェントをインストールできるスクリプトが生成されます。生成された登録スクリプトを使用してエージェントをインストールするには:

Azure DevOps プロジェクトから、 Pipelines>Deployment グループを選択します。
展開グループ画面で、New を選択するか、展開グループの追加を選択しますこのデプロイグループがプロジェクトの最初のグループである場合は選択します。
Deployment グループ名オプションの Description を入力し、Create を選択します。
次の画面で、 Windows または Linux を選択して、登録するターゲットの Type。登録スクリプトが生成されます。
[認証用にスクリプト内の個人用アクセストークンを使用する] を選択します。詳細については、「個人用アクセストークンの使用」を参照してください。
[スクリプトをクリップボードにコピー] を選びます。
各ターゲットコンピューターで、管理アクセス許可を持つアカウントを使用してサインインします。
コピーしたスクリプトを実行してマシンを登録し、エージェントをインストールします。 Windows マシンの場合は、管理者特権の PowerShell コマンドプロンプトを使用します。

スクリプトが実行されると、次のようになります。
- 展開グループジョブ内の特定のサーバーにデプロイを制限できるタグを割り当てるにはタグの入力を求められたら「Y」と入力し、この VM のタグまたはタグを入力します。
  
  タグはそれぞれ 256 文字に制限され、大文字と小文字は区別されず、使用できるタグの数に制限はありません。
- ユーザーアカウントの入力を求められたら、既定値をそのまま使用します。
Note

セキュリティで保護されたチャネルを作成できなかったスクリプトの実行時にエラーが発生した場合は、管理者 PowerShell プロンプトで次のコマンドを実行します。

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

各ターゲットサーバーを設定した後、スクリプトはメッセージ Service vstsagent.{organization-name}.{computer-name} started successfullyを返します。

[Azure Pipelines Deployment groups] ページの [Targets タブで、エージェントが実行されていることを確認できます。必要に応じてページを更新します。

Azure Pipelines エージェント Azure VM 拡張機能をインストールする

デプロイマシンとして Azure VM を使用する場合は、各 VM に Azure Pipelines Agent 拡張機能をインストールできます。拡張機能は、Azure DevOps プロジェクト内の指定されたデプロイグループにエージェントを自動的に登録します。

拡張機能を使用してエージェントをインストールするには、まずデプロイグループを作成します。

Azure DevOps プロジェクトから、 Pipelines>Deployment グループを選択します。
展開グループ画面で、New を選択するか、展開グループの追加を選択しますこのデプロイグループがプロジェクトの最初のグループである場合は選択します。
Deployment グループ名オプションの Description を入力し、Create を選択します。

Azure ポータルで各ターゲット VM に Azure Pipelines Agent 拡張機能をインストールします。

VM ページで、左側のナビゲーションで Settings>Extensions + Applications を選択します。
[ Extension タブで、 Add を選択します。
拡張機能のインストール ページで、Azure Pipelines Agent を検索して選択し、Next を選択します。
Azure Pipelines Agent 拡張機能の構成画面で、次の情報を指定します。
- Azure DevOps 組織の URL: https://dev.azure.com/contosoなど、Azure DevOps 組織の URL を入力します。
- チームプロジェクト: プロジェクト名 ( myProject などを入力します。
- 展開グループ: 作成した展開グループの名前を入力します。
- エージェント名: 必要に応じて、エージェントの名前を入力します。何も入力しない場合、エージェントには VM 名に -DG が付加されます。
- 個人用アクセストークン: Azure Pipelines への認証に使用する個人用アクセストークン (PAT) を入力します。
- タグ: 必要に応じて、エージェントで構成するタグのコンマ区切りのリストを指定します。タグはそれぞれ 256 文字に制限され、大文字と小文字は区別されず、使用できるタグの数に制限はありません。
[確認および作成] を選択し、検証に成功したら [作成] を選択します。

AzureResourceGroupDeploymentV2 タスクを使用する

AzureResourceGroupDeploymentV2 タスクを使用して、Azure Resource Manager (ARM) テンプレートをデプロイできます。テンプレートは、Azure VM の作成時に Azure Pipelines Agent 拡張機能をインストールすることも、VM の作成後に拡張機能を適用するようにリソースグループを更新することもできます。

または、AzureResourceGroupDeployment タスクの高度なデプロイオプションを使用して、エージェントをデプロイすることもできます。

配置グループを作成する

まず、デプロイグループを作成します。

Azure DevOps プロジェクトから、 Pipelines>Deployment グループを選択します。
展開グループ画面で、New を選択するか、展開グループの追加を選択しますこのデプロイグループがプロジェクトの最初のグループである場合は選択します。
Deployment グループ名オプションの Description を入力し、Create を選択します。

ARM テンプレートを使用してエージェントをインストールする

ARM テンプレートは、Azure リソースのセットを宣言的に定義する JSON ファイルです。 Azure は自動的にテンプレートを読み取り、リソースをプロビジョニングします。複数のサービスとその依存関係を 1 つのテンプレートにデプロイできます。

ARM テンプレートを使用してデプロイエージェントを登録してインストールするには、次のコードに示すように、 Microsoft.Compute/virtualMachine リソースの下に resources 要素を追加します。

"resources": [
  {
    "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "[parameters('location')]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[resourceId('Microsoft.Compute/virtualMachines/',
                      concat(parameters('vmNamePrefix'),copyindex()))]"
    ],
    "properties": {
      "publisher": "Microsoft.VisualStudio.Services",
      "type": "TeamServicesAgent",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "VSTSAccountName": "[parameters('VSTSAccountName')]",
        "TeamProject": "[parameters('TeamProject')]",
        "DeploymentGroup": "[parameters('DeploymentGroup')]",
        "AgentName": "[parameters('AgentName')]",
        "AgentMajorVersion": "auto|2|3",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

Note

Linux VM の場合、コード内のpropertiesのtype パラメーターをTeamServicesAgentLinuxする必要があります。

Note

Azure DevOps Server 2022.1 以降では、AgentMajorVersion に使用できる値は auto|2|3 です。 Azure DevOps Server 2022.0 以前では、 AgentMajorVersion の許容値は auto|N。

"resources": [
  {
    "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "[parameters('location')]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[resourceId('Microsoft.Compute/virtualMachines/',
                      concat(parameters('vmNamePrefix'),copyindex()))]"
    ],
    "properties": {
      "publisher": "Microsoft.VisualStudio.Services",
      "type": "TeamServicesAgent",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "VSTSAccountName": "[parameters('VSTSAccountName')]",
        "TeamProject": "[parameters('TeamProject')]",
        "DeploymentGroup": "[parameters('DeploymentGroup')]",
        "AgentName": "[parameters('AgentName')]",
        "AgentMajorVersion": "auto|N",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

上のコードでは以下の操作が行われます。

VSTSAccountName は、使用するために必要な Azure Pipelines 組織です。たとえば、Azure DevOps URL が https://dev.azure.com/contosoされている場合は、次のように指定します。 contoso
TeamProject は、展開グループが定義されている必要なプロジェクトです。
DeploymentGroup は、エージェントの登録に必要なデプロイグループです。
AgentName はオプションのエージェント名です。指定しない場合、エージェントには VM 名 -DG 追加されます。
Tags は、エージェントに設定するタグの省略可能なコンマ区切りの一覧です。タグはそれぞれ 256 文字に制限され、大文字と小文字は区別されず、使用できるタグの数に制限はありません。
PATToken は、エージェントをダウンロードして構成するために Azure Pipelines に対して認証するために必要な PAT です。

ARM テンプレートの詳細については、Azure Resource Manager テンプレートでのリソース定義に関する記事を参照してください。

リリースパイプラインでテンプレートを使用する

リリースパイプラインを作成します。

左側のメニューから Pipelines>Releases を選択し、 New>New リリースパイプラインを選択します。
Azure Pipelines の Releases タブで、ARM テンプレートのデプロイ タスクを含むステージを含むリリースパイプラインを作成します。
このテンプレートではタスクのバージョン 2 が使用されるため、 Azure リソースグループのデプロイ 設定画面で、 Task のバージョン を 3.* から 2.* に変更します。
タスクに必要なパラメーター (Azure サブスクリプション、リソースグループ名、場所、テンプレート情報、実行するアクションなど) を指定します。
リリースパイプラインを保存し、パイプラインからリリースを作成してエージェントをインストールします。

高度なデプロイオプションを使用してエージェントをインストールする

または、高度なデプロイオプションを使用してエージェントをインストールすることもできます。上記の手順に従いますが、 Azure リソースグループのデプロイ 設定画面で、仮想マシンの Advanced デプロイオプション セクションを展開します。

可能な前提条件で、展開グループエージェントを使用した構成を選択します。
次の必須パラメーターと設定を指定します。
- Azure Pipelines サービス接続: ターゲットを指す既存のサービス接続を選択します。
  
  既存のサービス接続がない場合は、 New を選択して作成します。詳細については、「サービス接続の作成」を参照してください。スコープが Deployment Group に制限されたPATを使用するようにサービス接続を構成します。
- チームプロジェクト: 展開グループを含むプロジェクトを選択します。
- 展開グループ: エージェントを登録する展開グループを選択します。
- Copy Azure VM タグをエージェントにコピーします Azure VM に既に構成されているタグを、対応するデプロイグループエージェントにコピーします。
  
  既定では、Azure タグはすべて、Role: WebなどのKey: Value形式を使用してコピーされます。
パイプラインを保存し、エージェントをインストールするリリースを作成します。

拡張機能のトラブルシューティング

Azure Pipelines Agent 拡張機能には、いくつかの既知の問題があります。

状態ファイルが大きすぎます

この問題は、Windows VM で発生する可能性があります。状態ファイルには、拡張機能の現在の状態を記述する JSON オブジェクトが含まれています。オブジェクトは、これまでに実行された操作を一覧表示するためのプレースホルダーです。

Azure ではこの状態ファイルを読み取り、状態オブジェクトを API 要求への応答として渡します。このファイルには、最大許容サイズがあります。サイズが最大値を超えた場合、Azure はそれを完全に読み取ることができず、状態に関するエラーが発生します。

拡張機能が最初にインストールされる場合でも、マシンが再起動するたびに、状態ファイルに追加される操作が実行されます。マシンが何度も再起動すると、状態ファイルのサイズがしきい値を超える可能性があります。エラー Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes。拡張機能のインストールは成功する可能性がありますが、このエラーによって拡張機能の実際の状態が非表示になります。

このマシンの再起動の問題は、Windows 拡張機能のバージョン 1.27.0.2 と Linux 拡張機能の 1.21.0.1 以降で修正されています。再起動によってステータスファイルに何も追加されません。ただし、以前のバージョンの拡張機能でこの問題が発生し、拡張機能が固定バージョンに自動更新された場合、問題は解決しない可能性があります。新しいバージョンの拡張機能は、以前の状態ファイルでも動作します。

この問題は、フラグ付きの拡張機能の以前のバージョンを使用してマイナーバージョンの自動更新を無効にしている場合、または大きなステータスファイルが以前のバージョンから固定バージョンに転送された場合に発生する可能性があります。その場合は、拡張機能をアンインストールして再インストールすることで、問題を解決できます。拡張機能をアンインストールすると、拡張機能ディレクトリ全体がクリーンアップされ、最新バージョンの新しいインストール用の新しいステータスファイルが作成されます。

カスタムデータの問題

Python 2 は非推奨となり、Azure Pipelines Agent 拡張機能は Python 3 で動作します。 Python 3 が既定でインストールされていない OS バージョンを引き続き使用する場合は、拡張機能を実行するには、VM に Python 3 をインストールするか、既定で Python 3 がインストールされている OS バージョンに切り替える必要があります。そうしないと、OS のバージョンを切り替えるときに、VM 上のカスタムデータ場所に関する混乱が発生する可能性があります。

Linux VM では、以前のバージョンのエージェントの場合は /var/lib/waagent/ovf-env.xml に、新しいバージョンの場合は /var/lib/waagent/CustomData にカスタムデータがコピーされます。これら 2 つのパスのうちの 1 つだけをハードコーディングすると、OS バージョンを切り替えるときに問題が発生する可能性があります。これは、パスの 1 つが新しい OS バージョンには存在しませんが、もう 1 つのパスは存在するためです。 VM プロビジョニングの中断を回避するには、テンプレートで両方のパスを使用して、1 つが失敗した場合にもう一方が成功するようにすることを検討してください。

ヘルプとサポート

調べるトラブルシューティングのヒント
Stack Overflow に関するアドバイスを得るを提供します。
Azure DevOps 開発者コミュニティで質問を投稿したり、回答を検索したり、機能を提案したりできます。
Azure DevOps のサポートを取得

次の方法で共有

配置グループのエージェントをプロビジョニングする

前提条件

ターゲットサーバーでインストールスクリプトを実行する

Azure Pipelines エージェント Azure VM 拡張機能をインストールする

AzureResourceGroupDeploymentV2 タスクを使用する

配置グループを作成する

ARM テンプレートを使用してエージェントをインストールする

リリースパイプラインでテンプレートを使用する

高度なデプロイオプションを使用してエージェントをインストールする

拡張機能のトラブルシューティング

状態ファイルが大きすぎます

カスタムデータの問題

ヘルプとサポート

フィードバック

その他のリソース

次の方法で共有

配置グループのエージェントをプロビジョニングする

前提条件

ターゲット サーバーでインストール スクリプトを実行する

Azure Pipelines エージェント Azure VM 拡張機能をインストールする

AzureResourceGroupDeploymentV2 タスクを使用する

配置グループを作成する

ARM テンプレートを使用してエージェントをインストールする

リリース パイプラインでテンプレートを使用する

高度なデプロイ オプションを使用してエージェントをインストールする

拡張機能のトラブルシューティング

状態ファイルが大きすぎます

カスタム データの問題

ヘルプとサポート

関連するコンテンツ

フィードバック

その他のリソース

ターゲットサーバーでインストールスクリプトを実行する

リリースパイプラインでテンプレートを使用する

高度なデプロイオプションを使用してエージェントをインストールする

カスタムデータの問題