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

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

配置グループを使用すると、デプロイ用にターゲット マシンの論理グループを定義し、各コンピューターに必要なエージェントをインストールするのが簡単になります。 この記事では、デプロイ グループを作成し、デプロイ グループ内の各仮想マシンまたは物理マシンにエージェントをインストールしてプロビジョニングする方法について説明します。

エージェントは、次のいずれかの方法でインストールできます。

• 配置グループの作成時に自動的に生成されるスクリプトを実行します。
• 各 VM に Azure Pipelines エージェント Azure VM 拡張機能をインストールします。
• リリース パイプラインで ARM テンプレート デプロイ タスクを使用します。

エージェントとパイプラインの詳細については、次を参照してください。

• Azure Pipelines での並列ジョブ
• Azure DevOps の料金

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

1. Azure Pipelines の [配置グループ] タブで、[+新規] を選択して、新しいグループを作成します。

2. グループの名前を入力し、必要に応じて説明を入力して、[作成] を選択します。

3. 次のページの [コマンド ラインを使用してマシンを登録する] セクションで、ターゲット コンピューターのオペレーティング システムを選択します。

4. [認証用にスクリプト内の個人用アクセス トークンを使用する] を選択します。 詳細については、こちらを参照してください。

5. [スクリプトをクリップボードにコピー] を選択します。

6. 適切なアクセス許可を持つアカウントを使用して、各ターゲット コンピューターに順番にサインインし、次の手順を実行します。

   • 管理者 PowerShell コマンド プロンプトを開き、コピーしたスクリプトを貼り付け、それを実行してマシンをこのグループに登録します。

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

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

   • エージェントのタグの構成を求められたら、Y を押し、グループ内のマシンのサブセットを識別するために使用するタグを入力して、部分的なデプロイを実行します。

     [コンピューター グループで実行] ジョブで配置グループが使用されている場合、割り当てるタグによって、デプロイを特定のサーバーに制限できます。

   • ユーザー アカウントの入力を求められたら、Enter キーを押して既定値を受け入れます。

   • メッセージ Service vstsagent.{organization-name}.{computer-name} started successfully でスクリプトが完了するまで待ちます。

7. Azure Pipelines の [配置グループ] ページで、[マシン] タブを開き、エージェントが実行されていることを確認します。 構成したタグが表示されない場合は、ページを更新します。

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

1. Azure Pipelines の [配置グループ] タブで、[+新規] を選択して、新しいグループを作成します。

2. グループの名前を入力し、必要に応じて説明を入力して、[作成] を選択します。

3. Azure portal で、配置グループに含まれる VM ごとに [拡張機能] ブレードを開き、[+ 追加] を選択して [新しいリソース] の一覧を開き、[Azure Pipelines エージェント] を選択します。

   

4. [拡張機能のインストール] ブレードで、使用する Azure Pipelines サブスクリプションの名前を指定します。 たとえば、URL が https://dev.azure.com/contoso の場合は、contoso を指定するだけです。

5. プロジェクト名と配置グループ名を指定します。

6. 必要に応じて、エージェントの名前を指定します。 指定しない場合は、-DG で追加された VM 名が使用されます。

7. Azure Pipelines に対する認証に使用する 個人用アクセス トークン (PAT) を入力します。

8. 必要に応じて、エージェントで構成されるタグのコンマ区切りの一覧を指定します。 タグでは大文字と小文字は区別されず、それぞれ 256 文字以内にする必要があります。

9. [OK] を選択して、この VM へのエージェントのインストールを開始します。

10. この配置グループに含める他の VM に拡張機能を追加します。

ARM テンプレート デプロイ タスクを使用する

重要

これらの手順は、タスクのバージョン 2 を参照しています。 タスクのバージョンを 3 から 2 に切り替えます。

ARM テンプレート デプロイ タスクを使用すると、仮想マシンの作成時に Azure Pipelines エージェント Azure VM 拡張機能をインストールする Azure Resource Manager (ARM) テンプレートをデプロイしたり、仮想マシンの作成後に拡張機能を適用するようにリソース グループを更新したりできます。 または、ARM テンプレート デプロイ タスクの高度なデプロイ オプションを使用して、エージェントを配置グループにデプロイすることもできます。

ARM テンプレートを使用して "Azure Pipelines エージェント" Azure VM 拡張機能をインストールする

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

Windows VM の場合は、次に示すように、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')]"
     }
   }
  }
]

ここで:

• VSTSAccountName は必須です。 使用する Azure Pipelines サブスクリプション。 例: URL が https://dev.azure.com/contoso の場合は、contoso を指定するだけです。
• TeamProject は必須です。 配置グループが定義されているプロジェクト
• DeploymentGroup は必須です。 配置エージェントが登録される配置グループ
• AgentName は省略可能です。 指定しない場合は、-DG が追加された VM 名が使用されます。
• Tags は省略可能です。 エージェントに設定されるタグのコンマ区切りの一覧。 タグでは大文字と小文字は区別されず、それぞれ 256 文字以内にする必要があります。
• PATToken は必須です。 エージェントをダウンロードして構成するために Azure Pipelines に対する認証に使用する個人用アクセス トークン

Note

Linux VM にデプロイする場合は、コード内の type パラメーターが TeamServicesAgentLinux であることを確認します。

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

拡張機能に関する既知の問題をいくつか次に示します。

• 状態ファイルが大きすぎる: この問題は Windows VM で発生します。Linux 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) に関するこの問題を修正しましたため、再起動時に状態ファイルには何も追加されません。 修正が適用される前に拡張機能でこの問題が発生 (以前のバージョンの拡張機能でこの問題が発生) していて、修正プログラムが適用されたバージョンに拡張機能が自動アップグレードされた場合、問題は解決しません。 これは、拡張機能の更新時に、新しいバージョンの拡張機能が以前の状態ファイルで引き続き動作するためです。 現在、マイナー バージョンの自動更新を無効にするためにフラグを付けて以前のバージョンの拡張機能を使用している場合、または大きな状態ファイルが以前の拡張機能バージョンから修正プログラムを含む新しいバージョンに転送された場合、またはその他の理由で、この問題が引き続き発生する可能性があります。 その場合は、拡張機能をアンインストールして再インストールすると、この問題を解決できます。 拡張機能をアンインストールすると、拡張機能ディレクトリ全体がクリーンアップされるため、新しいインストール用に新しい状態ファイルが作成されます。 最新バージョンの拡張機能をインストールする必要があります。 この解決策は永続的な修正であり、その後は、問題が再び発生することはありません。

• カスタム データに関する問題: これは拡張機能に関する問題ではありませんが、一部のお客様から、OS バージョンの切り替え時の VM 上のカスタム データの場所に関する混乱が報告されています。 次の回避策をお勧めします。 Python 2 は非推奨になったため、Python 3 で動作するように拡張機能を作成しました。 Python 3 が既定でインストールされていない以前の OS バージョンを引き続き使用している場合は、拡張機能を実行するために、VM に Python 3 をインストールするか、Python 3 が既定でインストールされている OS バージョンに切り替える必要があります。 Linux VM では、以前のバージョンの Microsoft Azure Linux エージェントの場合は カスタム データ がファイル /var/lib/waagent/ovf-env.xml にコピーされ、新しいバージョンの Microsoft Azure Linux エージェントの場合は /var/lib/waagent/CustomData にコピーされます。 この 2 つのパスのうちの 1 つのみをハードコーディングしたお客様は、新しい OS バージョンにはファイルが存在せず、もう一方のファイルが存在するため、OS バージョンの切り替え中に問題が発生しているようです。 そのため、VM プロビジョニングの中断を回避するには、テンプレート内の両方のファイルを考慮して、一方が失敗した場合にもう一方が成功するようにする必要があります。

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

テンプレートを使用するには:

1. Azure Pipelines の [配置グループ] タブで、[+新規] を選択して、新しいグループを作成します。

2. グループの名前を入力し、必要に応じて説明を入力して、[作成] を選択します。

3. Azure Pipelines の [リリース] タブで、ARM テンプレート デプロイ タスクを含むステージでリリース パイプラインを作成します。

4. Azure サブスクリプション、リソース グループ名、場所、テンプレート情報など、タスクに必要なパラメーターを指定し、リリース パイプラインを保存します。

5. リリース パイプラインからリリースを作成して、エージェントをインストールします。

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

1. Azure Pipelines の [配置グループ] タブで、[+新規] を選択して、新しいグループを作成します。

2. グループの名前を入力し、必要に応じて説明を入力して、[作成] を選択します。

3. Azure Pipelines の [リリース] タブで、ARM テンプレート デプロイ タスクを含むステージでリリース パイプラインを作成します。

4. タスクを選択し、[仮想マシンの高度なデプロイ オプション] セクションを展開します。 このセクションのパラメーターを次のように構成します。

   • 前提条件を有効にする: [配置グループ エージェントを使用して構成する] を選択します。

   • Azure Pipelines/TFS エンドポイント: ターゲットを指す既存の Team Foundation Server/TFS サービス接続を選択します。 配置グループのエージェント登録には、Visual Studio プロジェクトへのアクセスが必要です。 既存のサービス接続がない場合は、[追加] を選択し、今すぐ作成します。 スコープが配置グループに制限された個人用アクセス トークン (PAT) を使用するように構成します。

   • プロジェクト: 配置グループを含むプロジェクトを指定します。

   • 配置グループ: エージェントが登録される配置グループの名前を指定します。

   • Azure VM タグをエージェントにコピーする: 設定 (ティック) すると、Azure VM で既に構成されているタグはすべて、対応する配置グループ エージェントにコピーされます。 既定では、すべての Azure タグは Key: Valueの形式を使用してコピーされます。 たとえば、「 Role: Web 」のように入力します。

5. Azure サブスクリプション、リソース グループ名、場所など、タスクに必要なその他のパラメーターを指定し、リリース パイプラインを保存します。

6. リリース パイプラインからリリースを作成して、エージェントをインストールします。

関連トピック

• マシン グループ ジョブで実行する
• エージェントを Windows にデプロイする
• エージェントを macOS にデプロイする
• エージェントを Linux にデプロイする

ヘルプとサポート

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