TeamCity エージェントのインストールと起動
TeamCity ビルドエージェントは、TeamCity サーバーからのコマンドをリッスンし、実際のビルドプロセスを開始するソフトウェアです。 本番環境の TeamCity セットアップでは、専用マシンに追加のビルドエージェントをインストールする必要があります。 その前に、 エージェントとサーバー間の通信、 システム要件、 競合するソフトウェア 、および セキュリティに関する注意事項を必ず参照してください。
Tomcat サーブレットコンテナーがバンドルされた TeamCity をインストールするか、Windows 用の TeamCity インストーラーを使用すると、サーバーと 1 つのビルドエージェントの両方が同じマシンにインストールされます。 セキュリティ上の懸念があるため、この設定は 実稼働目的には推奨されません。 さらに、ビルド手順によってウェブ UI の応答性と TeamCity サーバー全体の動作が遅くなる可能性があります。
共通のビルドエージェントの概念
エージェントは、通常、ソースコードをチェックアウトし、他のビルドのアーティファクトをダウンロードし、ビルドプロセスを実行するソフトウェアです。 TeamCity サーバーとは別にインストールおよび構成されます。
エージェントは物理マシンと クラウドホスト型仮想マシンの両方にインストールできます。
エージェントは、 互換性のある任意のビルド構成のビルドを実行できます。 各エージェントは、アーキテクチャ、オペレーティングシステム、インストールされているツールなど、固有の環境を持つことができます。 これらのプロパティは、エージェントが実行できるビルドを定義します。
エージェントは一度に 1 つのビルドを実行できます。 基本的に、エージェントの数によって、並列ビルドの数とビルドプロセスが実行される環境の数が制限されます。
エージェントのスムーズな動作を確保するには、実行可能ファイルまたはアーカイブからインストールされたエージェントのコアソフトウェアとツールを定期的に更新する必要があります。 たとえば、TeamCity サーバーを新しいバージョンにアップグレードした後、既存の VM イメージから起動されたすべてのクラウドエージェントは更新にしばらく時間がかかります (これは自動的に行われますが、キューに入っているビルドを開始できるタイミングが遅れます)。 エージェントが常に最新のソフトウェアを実行するようにするには、代わりに Docker コンテナーとして実行します。
ビルドは Docker または Podman コンテナー内で実行できるため、エージェントマシンの OS だけではエージェントとプロジェクトの互換性が制限されることはありません。 つまり、Windows エージェントで Linux 固有のタスクを実行でき、その逆も可能です。
TeamCity ビルドエージェントには 二つのプロセスが含まれます: エージェントランチャー (エージェントプロセスを起動する Java プロセス) とエージェント (エージェントランチャーの子プロセスとして実行されるビルドエージェントのメインプロセス)。
ビルドエージェントのステータス
ビルドエージェントの状態は、三つの独立したステータスのペアで表されます。 エージェントには各ペアから常にいずれかの値が設定されるため、これらのステータスは組み合わされます。新しくインストールされたエージェントは通常、 接続済み、 未承認、 有効化済みです。また、たとえば 接続済み、 承認済みだが、メンテナンスのためローテーションから外された 無効化済み エージェントもあります。
エージェントがビルドを実行するのは、接続済み、承認済み、有効化済みの状態が同時に満たされている場合のみです。
- 接続済み / 切断済み
TeamCity はこのステータスを自動的に設定します。 エージェントは、サーバーに登録され、サーバーコマンドに応答する場合は connected になり、それ以外の場合は 切断済み になります。
このステータスは UI から変更できません。切断されたエージェントは、エージェントプロセスが実行されていないか、サーバーに到達できないことを意味します。 まず、エージェント自身のログと
サーバー URLプロパティを 構成ファイル 内で確認してください。承認は、サーバーがこのマシンと連携してよいことを明示的に確認するものです。 新しいエージェントは、TeamCity サーバーと同じマシンにインストールされたエージェントも含め、 未承認 のままになり、 エージェント ページで承認するまで続きます。 クラウドエージェントの動作は異なります: エージェントライセンスが利用可能であれば、接続するとすぐに TeamCity が自動的に承認します。
未承認のエージェントはビルドを実行できません。 さらに、TeamCity は未承認エージェントのマシンとは一切通信しません: ログの表示、スレッドのダンプ、 インタラクティブターミナルを開くこと、再起動は利用できません。 これにより、確認していないマシンとサーバーが通信することを防げるため、どのマシンが接続したか分かっている場合にのみエージェントを承認してください。
承認はライセンス管理にも関係します: 承認済みエージェントの数は、サーバー上の エージェントライセンス数を超えることはできません。 エージェントの承認を解除すると、そのライセンスが別のエージェント用に解放されます。これは、限られたライセンスプールをマシン間でローテーションする方法です。 代わりに上限を引き上げるには、追加のライセンスを購入してください。
- 有効化済み / 無効化済み生き方さんに感謝しています。 =
エージェントの有効化と無効化により、引き続き信頼して管理しているマシンへのビルドの流れを制御します。 このステータスは UI で切り替えます。クラウドエージェントの場合、対応するアクションは メンテナンスのため無効化 です。
TeamCity はキュー内のビルドを 有効 エージェントにのみ配布します。 エージェントを無効化しても、そのエージェントで現在実行中のビルドは停止されません。そのため、マシンを無効化し、オフラインにする前に作業を完了させることができます。
無効 エージェントは、たとえば カスタムビルドを通じて明示的に割り当てられたビルドを引き続き実行します。 このため、無効化は、通常のビルドに邪魔されずにエージェントを ビルドグリッドから外し、そのエージェント固有の問題を再現するための一般的な方法になります。
サーバーに接続されているすべてのエージェントは、一意に命名されている必要があります。
エージェントの管理には特定の権限が必要です。 詳細については、 ロールと権限の管理 を参照してください。
エージェントステータスの確認
エージェント ページに加えて、 TeamCity CLI または REST API 経由でエージェントのステータスを読み取ることができます。 これはエージェント群を監査する実用的な方法です。たとえば、大量デプロイ後に、接続済みでありながらまだ承認待ちのエージェントを見つける場合に役立ちます。
CLI でエージェントを一覧表示するには、三つのステータスの任意の組み合わせでフィルターします：
ID または名前で単一のエージェントを調べるには：
REST API の同じクエリでは、 agents ロケーターを使用します：
単一のエージェントのレスポンスでは、三つのステータスが属性として Exposed されます：
エージェント-サーバー間のデータ転送
TeamCity エージェントは、 サーバー URL エージェントプロパティとして構成された URL 経由で TeamCity サーバーに接続します。 これは、単方向のエージェント間接続と呼ばれます。
エージェントはポーリングプロトコル経由で、エージェントからサーバーへの単方向接続を使用します: エージェントは TeamCity サーバーへの HTTP(S) 接続を確立し、サーバーコマンドがないかサーバーを定期的にポーリングします。
ローカルエージェントを TeamCity サーバーに接続する
ビルドエージェントをローカルにインストールした後、 構成し、TeamCity サーバーまたはクラウドインスタンスに接続する必要があります。 クイックガイドについては、次のビデオを参照してください。
クラウドエージェント
TeamCity エージェントをクラウドでホストすると、新しいエージェントがオンデマンドでスピンアップし、処理するビルドがない場合はスピンダウンする、高度にスケーラブルなソリューションを実装できます。 クラウドホスト型の TeamCity エージェントについて詳しくは、 クラウドでビルドエージェントをホストする セクションを参照してください。
エージェントのアップグレード
TeamCity エージェントは、必要に応じて自動的にアップグレードされます。 通常、これは次の場合に発生します。
サーバーが アップグレードされました
サーバーのアップグレード後にエージェントのプラグインを更新し、新しいファイルを受信すると、変更を有効にするためにエージェントの再起動がトリガーされる場合があることに注意してください。 エージェントが 十分な権限を持つユーザーアカウントで実行されている場合、すべての再起動が自動的に行われるため、入力は必要ありません。
エージェントの優先度
TeamCity は、CPU 数、過去のパフォーマンス、エージェントのソース (ローカルのセルフホストエージェントが最優先され、次に クラウドエージェント、 Kubernetes エグゼキューター Pod の優先度が最も低くなります) など、複数の基準を使用してエージェントを選択します。 このロジックは、整数 TeamCity エージェントの優先度 プロパティ（–10,000 から 10,000 、デフォルト: 0 ）を設定することでオーバーライドできます。
AWS がホストするクラウドエージェントの場合、クラウドイメージ設定ページでこのプロパティを設定できます。
その他のエージェントタイプの場合は、 <TeamCity_Agent_Home>/conf/buildAgent.properties ファイルに次の行を追加します：
teamcity.agent.priority=54
TeamCity は、エージェントが完全に起動してサーバーに接続された後でのみ、エージェントプロパティを認識することに注意してください。 そのため、EC2 以外のクラウドエージェントの優先順位は、アクティブ / 実行中のインスタンスにのみ適用されます。 現在、インスタンスが起動する前に EC2 クラウドイメージのみがエージェントの優先順位を中継します。
エージェントをリモートでデバッグする
エージェントをインストール、接続、 承認した後、TeamCity UI からこのエージェントのマシンのターミナルを直接呼び出すことができます。 この機能を使用すると、エージェントログをリモートで表示したり、インストールされているソフトウェアを確認したり、エージェント固有の問題をデバッグしたりできます。
未承認のエージェントではターミナルを使用できません: TeamCity は信頼するよう指示されていないマシンとは通信せず、そのようなエージェントでは ターミナルを開く ボタンを非表示にします。 承認に失敗するクラウドインスタンスをデバッグするには、代わりにクラウドプロバイダー独自のツールを使用してください。たとえば、AWS コンソールから EC2 インスタンスに接続します。
ターミナルを起動するには、TeamCity ヘッダーで エージェント をクリックし、必要なエージェントを選択して、 ターミナルを開く をクリックします。
このターミナルは ビルド結果ページ から開くこともできます。 この場合、ターミナルは $HOME フォルダーではなく チェックアウトディレクトリで開きます。
ターミナルが開いたら、 別のタブで開く リンクをクリックすると、より大きなクライアント領域が表示されます。
ターミナルを開く ボタンは、すべてのタイプのエージェントマシン (Linux、Windows、macOS) で使用でき、TeamCity エージェントを起動するユーザーと同じユーザー ID でターミナルを呼び出します。
メンテナンスの実行中にビルドエージェントがアイドル状態であることを確認するには、ターミナルセッションでは 実行中のビルドエージェントが必要であるため、ビルドエージェントを停止せずに無効にします。 ビルドエージェントの停止は、以前に開いていたターミナルタブをフリーズし、ユーザーが新しいコマンドを入力できないようにします。
一定時間アイドル状態になると自動的に終了するクラウドエージェントの場合は、ビルドの問題を調査している間にエージェントのマシンを実行したままにしてシャットダウンしないようにするために、 「メンテナンスのため無効にします ...」ボタンをクリックすることをお勧めします。
ターミナルを開く リンクは、 ロール権限に 「対話型エージェントターミナルを呼び出す」権限が含まれているユーザーにのみ表示されます。 この権限は、対応するエージェントのエージェントプールに関連付けられているすべてのプロジェクトに付与する必要があります。 「プロジェクト管理者」および「システム管理者」ロールを持つユーザーには、デフォルトでこのような権限が付与されます。 追加の予防策として、ターミナルを開く各要求は、 監査ログに新しい「エージェントアクション | エージェントに接続」アクティビティとして書き込まれます。