TeamCity エージェントをインストールして開始する

ビルドエージェントの共通概念

• エージェントは、通常、ソースコードをチェックアウトし、他のビルドのアーティファクトをダウンロードし、ビルドプロセスを実行するソフトウェアです。TeamCity サーバーとは別にインストールおよび構成されます。

• エージェントは物理マシンとクラウドホスト型仮想マシンの両方にインストールできます。

• エージェントは、互換性のある任意のビルド構成のビルドを実行できます。各エージェントは、アーキテクチャ、オペレーティングシステム、インストールされているツールなど、固有の環境を持つことができます。これらのプロパティは、エージェントが実行できるビルドを定義します。

• エージェントは一度に 1 つのビルドを実行できます。基本的に、エージェントの数によって、並列ビルドの数とビルドプロセスが実行される環境の数が制限されます。

• エージェントのスムーズな動作を確保するには、実行可能ファイルまたはアーカイブからインストールされたエージェントのコアソフトウェアとツールを定期的に更新する必要があります。例: TeamCity サーバーを新しいバージョンにアップグレードした後、既存の VM イメージから起動されたすべてのクラウドエージェントの更新にはしばらく時間がかかります (これは自動的に行われますが、キューに入れられたビルドを開始できるタイミングが遅れます)。エージェントが常に最新のソフトウェアを実行するようにするには、代わりに Docker コンテナーとして実行します。

• ビルドは Docker または Podman コンテナー内で実行できるため、エージェントマシンの OS だけではエージェントとプロジェクトの互換性が制限されることはありません。つまり、Windows エージェントで Linux 固有のタスクを実行でき、その逆も可能です。

• TeamCity ビルドエージェントには、エージェントランチャー (エージェントプロセスを起動する Java プロセス) とエージェント (エージェントランチャーの子プロセスとして実行されるビルドエージェントのメインプロセス) の 2 つのプロセスが含まれます。

ビルドエージェントのステータス

TeamCity では、ビルドエージェントは以下のステータスを持つことができます。

サーバーに接続されているすべてのエージェントには、固有のエージェント名が必要です。

特定のロールを持つユーザーのみがエージェントを管理できます。詳細については、この記事を参照してください。

ビルドエージェントの構成については、このセクションを参照してください。

エージェント - サーバーデータ転送

TeamCity エージェントは、serverUrl エージェントプロパティとして構成された URL を介して TeamCity サーバーに接続します。これは、単方向のエージェント間接続と呼ばれます。

エージェントは、ポーリングプロトコルを介した単方向のエージェント間接続を使用します。エージェントは TeamCity サーバーへの HTTP(S) 接続を確立し、サーバーコマンドについてサーバーを定期的にポーリングします。

ローカルエージェントを TeamCity サーバーに接続する

ビルドエージェントをローカルにインストールしたら、それを構成して TeamCity サーバーまたはクラウドインスタンスに接続する必要があります。クイックガイドについては、次のビデオを参照してください。

クラウドエージェント

クラウドで TeamCity エージェントをホストすると、新しいエージェントがオンデマンドで起動し、処理するビルドがなくなったら終了する、高度にスケーラブルなソリューションを実装できます。クラウドでホストされる TeamCity エージェントの詳細については、クラウドのホストビルドエージェントセクションを参照してください。

エージェントのアップグレード

TeamCity エージェントは、必要に応じて自動的にアップグレードされます。通常、これは次の場合に発生します。

• サーバーがアップグレードされました

• エージェントプラグインがサーバーに追加または更新さ(英語)れます

• 新しいツールがインストールされている

サーバーのアップグレード後にエージェントのプラグインを更新し、新しいファイルを受信すると、変更を有効にするためにエージェントの再起動がトリガーされる場合があることに注意してください。エージェントが十分な権限を持つユーザーアカウントで実行されている場合、すべての再起動が自動的に行われるため、入力は必要ありません。

エージェントの優先順位

TeamCity は、CPU 数、過去のパフォーマンス、エージェントソース（ローカルセルフホストエージェントが最も優先度が高く、次にクラウドエージェント、Kubernetes エグゼキューター pods が最も優先度が低い）など、複数の基準に基づいてエージェントを選択します。このロジックは、整数 teamcity.agent.priority プロパティ（ – 10,000 から 10,000、デフォルト: 0）を設定することでオーバーライドできます。

• AWS がホストするクラウドエージェントの場合、クラウドイメージ設定ページでこのプロパティを設定できます。

  

• その他のエージェントタイプの場合は、<TeamCity_Agent_Home>/conf/buildAgent.properties ファイルに次の行を追加します。

  teamcity.agent.priority=54

TeamCity は、エージェントが完全に起動し、サーバーに接続された後にのみエージェントのプロパティを認識することに注意してください。そのため、EC2 以外のクラウドエージェントの優先順位は、アクティブ / 実行中のインスタンスにのみ適用されます。現在、インスタンスが起動する前に EC2 クラウドイメージのみがエージェントの優先順位を中継します。

エージェントをリモートでデバッグする

エージェントをインストールして接続した後、TeamCity UI からこのエージェントのマシンのターミナルを直接呼び出すことができます。この機能を使用すると、エージェントログをリモートで表示したり、インストールされているソフトウェアを確認したり、エージェント固有の問題をデバッグしたりできます。

ターミナルを呼び出すには、TeamCity ヘッダーのエージェントをクリックし、必要なエージェントを選択して、ターミナルを開くをクリックします。

このターミナルはビルド結果ページから開くこともできます。この場合、ターミナルは $HOME フォルダーではなくチェックアウトディレクトリで開きます。

ターミナルが開いたら、別のタブで開くリンクをクリックすると、より大きなクライアント領域が表示されます。

ターミナルを開くボタンは、すべてのタイプのエージェントマシン (Linux、Windows、macOS) で使用でき、TeamCity エージェントを起動するのと同じユーザー ID でターミナルを呼び出します。

メンテナンスの実行中にビルドエージェントがアイドル状態であることを確認するには、ターミナルセッションでは実行中のビルドエージェントが必要であるため、ビルドエージェントを停止せずに無効にします。ビルドエージェントの停止は、以前に開いていたターミナルタブをフリーズし、ユーザーが新しいコマンドを入力できないようにします。

一定時間アイドル状態になると自動的に終了するクラウドエージェントの場合は、ビルドの問題を調査している間にエージェントのマシンを実行したままにしてシャットダウンしないようにするために、「メンテナンスのため無効にします ...」ボタンをクリックすることをお勧めします。

ターミナルを開くリンクは、ロール権限に「対話型エージェントターミナルを呼び出す」権限が含まれているユーザーにのみ表示されます。この権限は、対応するエージェントのエージェントプールに関連付けられているすべてのプロジェクトに付与する必要があります。「プロジェクト管理者」および「システム管理者」ロールを持つユーザーには、デフォルトでこのような権限が付与されます。追加の予防策として、ターミナルを開く各要求は、監査ログに新しい「エージェントアクション | エージェントに接続」アクティビティとして書き込まれます。