TeamCity オンプレミス 2025.11 ヘルプ

実行者モード: 外部 Kubernetes 統合

TeamCity は 2 種類の Kubernetes 統合を提供します。

  • 定期的な Kubernetes 統合。このアプローチでは、AWS、Microsoft、Azure、Google Cloud などの他のクラウドプロバイダーとの統合と同様に、TeamCity のクラウドプロファイルとイメージを使用します。ビルドエージェントは TeamCity で設定し、Kubernetes クラスターでホストします。この統合タイプは、外部の Kubernetes のサポート(英語)プラグインに依存します。

  • 外部エグゼキューターとしての Kubernetes クラスター。このモードでは、TeamCity は Kubernetes 側のビルドエージェントを認識しません。代わりに、クラスターのビルド実行機能を認識し、ビルドを実行するエンティティの割り当てとライフサイクル管理をクラスターに完全に委譲します。

この記事では、ネイティブ統合アプローチについて説明します。従来の統合について詳しくは、Kubernetes 用の TeamCity の設定トピックを参照してください。

使い方

  1. TeamCity が K8s クラスターにアクセスできるようにする Kubernetes 接続を作成します。

  2. プロジェクト設定で、クラウドプロファイルセクションに移動し、新規プロファイルの作成をクリックします。

  3. 「タスクを外部エージェントにオフロードする」セクションの Kubernetes タイルをクリックします。

  4. K8s 統合を次のように設定します。

    • 接続 — 手順 1 で作成した接続を選択します。

    • サーバー URL — TeamCity サーバーの URL を入力するか、空白のままにしてサーバーのグローバル設定ページで指定された URL を使用します。

    • Pod テンプレート — 必要な pod 構成を選択します。詳細については、Pod テンプレートセクションを参照してください。

    • ビルドの最大数 — クラスターの容量を入力します。この容量に達すると、現在進行中のビルドが終了しない限り、新しいビルドはキューに残ります。

  5. ビルド構成設定で、必要に応じてエージェント要件とステップコンテナーを指定します。

  6. 新しいビルドをトリガーします。

  7. TeamCity K8s エグゼキューターは、ビルドステップのリストとそのパラメーターを収集し、pod 定義を生成して、K8s クラスターに送信します。各ビルドステップは個別のコンテナーで実行されるため、個々のステップに異なるイメージを指定できます。

  8. K8s クラスターはビルドの実行に必要な pods を割り当てて、ビルドを開始します。

クラスター権限

TeamCity ユーザーが Kubernetes 名前空間で書き込み操作を実行できることを確認してください。Kubernetes ユーザーロールには、次の権限が設定されている必要があります。

  • Pods: get、create、list、delete .

  • Pod テンプレート: get , list

  • 名前空間: get、list — TeamCity がサーバーで使用可能な名前空間を提案できるようにします。

次のサンプルは、Kubernetes RBAC(英語) を介して構成されたすべての必要な権限を示しています。

apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: teamcity:executor rules: - apiGroups: [""] resources: [namespaces] verbs: ["get", "list"] - apiGroups: [""] resources: ["pods"] verbs: ["get", "list", "create", "delete"] - apiGroups: [""] resources: [podtemplates] verbs: ["get","list"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: teamcity:executor roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: teamcity:executor subjects: # proper RoleBinding subject depends on your Authentication strategy # use one of examples below # if you use OIDC/Certificate auth strategies - kind: User name: teamcity # if you use Service account - kind: ServiceAccount name: teamcity

Pod テンプレート

podtemplates list 権限により、TeamCity はクラスターに保存されている pod テンプレート(英語)のリスト (選択した Kubernetes 接続で指定されたものと同じ名前空間の下) にアクセスできるようになります。取得されたテンプレートは、Pod テンプレートドロップダウンメニューに表示されます。

以下のサンプルテンプレートは、2GB のメモリと 25GB のストレージを備えた pods を起動し、カスタムビルドエージェントイメージ（注意事項と制限事項セクションを参照）を使用します。YAML マークアップでビルドパラメーターを明示的に宣言することもできます。これらのパラメーターとその値は、明示的なエージェント要件と照合され、互換性のあるエグゼキュータとキューに登録されたビルドがマッチングされます。

apiVersion: v1 kind: PodTemplate metadata: name: my-template namespace: default template: spec: containers: - name: template-container # see the limitations section image: johndoe/custom_agent_image:latest resources: limits: ephemeral-storage: 25Gi memory: 2Gi requests: ephemeral-storage: 25Gi env: - name: JDK_1_8 value: /usr/local/openjdk-8 nodeSelector: linux: arm64

エージェントの優先順位

ビルド構成にさまざまなエージェントオプションが混在している場合、TeamCity は次のロジックを使用して、キューに入れられたビルドを委譲します。

  • セルフホストエージェントは最優先です

  • ビルドと互換性のある無料のセルフホストエージェントがない場合、TeamCity は適切なクラウドエージェントを探します。

  • これらのオプションがどちらも利用できない場合、ビルドは外部実行プログラムにオフロードされます。

エージェントの優先順位の詳細については、次の記事を参照してください: エージェントの優先順位。

ライセンス

Kubernetes ベースのビルドはネイティブ TeamCity エージェントを占有しませんが、その数はエージェントライセンスによって制限されます。「ネイティブ」ビルドとエグゼキュータービルドの合計数は、このライセンス制限を超えることはできません。制限に達すると、新しいビルドは「同時ビルドの最大数に達しました」というメッセージとともにキューに残り、空きエージェントスロットを待機します。

分離ビルドおよび複合ビルド構成によって生成されたものはエージェントスロットを占有せず、制限なしで実行できます。

注意事項と制限事項

  • 現在、プロジェクトでは 1 つの Kubernetes 統合のみを使用できます。将来のリリースサイクルでは、プロジェクトごとに複数のエグゼキュータ (および優先順位付けするメカニズム) をサポートする予定です。

  • Kubernetes クラスターは、TeamCity サーバーに接続された「従来の」ビルドエージェントを使用せずにビルドを処理する外部オーケストレーターとして機能します。そのため、エグゼキューターによって処理されるビルドの実行中に「ビルドエージェントがビルド実行中に切断されました」という警告が表示されます。ビルドが正常に完了する限り、この警告は設定ミスや接続の問題を示すものではないため、無視して構いません。今後のバグ修正リリースでこの動作を修正する予定です。

  • カスタムコンテナープロパティを指定する Pod テンプレートには、「template-container」コンテナー名が必要です。

    # ... template: spec: containers: - name: template-container image: johndoe/custom_agent_image:latest # ...

    それ以外の場合、コンテナーはデフォルト設定を使用します。例: 標準の「jetbrains/teamcity-agent:latest」イメージを優先して、image プロパティをオーバーライドします。

  • 現在、Kubernetes Executor は Windows ノードをサポートしていません。これらのノードによって処理されるビルドは、「リソースの設定」フェーズで停止し、pods に MountVolume.SetUp failed for volume "kube-api-access-sfhbc" エラーが表示されます。そのため、Windows で実行するように設計されたビルドは、Kubernetes Executor に委譲できません。

    混合クラスター (Windows ノードと Linux ノードの両方) でこの問題を回避するには、pod テンプレートで必要なノードを指定します。

    spec: containers: # ... nodeSelector: kubernetes.io/os: linux

  • Docker ビルドステップはサポートされていません。

  • Docker 内の Docker(DinD) セットアップはサポートされていません。

  • 「/agent/temp/.old」ディレクトリのクリーンアップ中に、Pod の初期化が停止することがあります。

  • 構成の親プロジェクトに Kubernetes Executor が構成されている場合、高度なコンテナーラッパーはビルドステップでは使用できません。

2025 年 7 月 09 日
VMware vSphere および vCenter 用の TeamCity のセットアップ 外部データベースを設定する

関連ページ：

Kubernetes 用の TeamCity の設定

TeamCity は 2 種類の Kubernetes 統合を提供します。定期的な Kubernetes 統合。このアプローチでは、AWS、Microsoft、Azure、Google Cloud などの他のクラウドプロバイダーとの統合と同様に、TeamCity のクラウドプロファイルとイメージを使用します。ビルドエージェントは TeamCity で設定し、Kubernetes クラスターでホストします。この統合タイプは、外部の Kubernetes のサポートプラグインに依存します。外部エグゼキ...

接続を構成

TeamCity 接続は、外部サービスへのアクセスに必要な資格情報を保存します。このサードパーティサービスの種類に基づいて、2 つの主要な接続カテゴリがあります。VCS 接続これらの接続は、GitHub、GitLab、Bitbucket クラウドなどの VCS プロバイダーへのアクセスに必要な情報を保存します。これらの接続は、プロジェクト、ビルド構成、パイプラインを最も速く作成する方法を提供します。認証は自動的に処理されるため、リポジトリを選択するだけでビルドステップの設定を開始できます。接続が...

エージェント要件の設定

エージェントの要件は、ビルド構成を実行できるエージェントを指定する条件です。現在存在するすべての要件を表示して新しい要件を作成し、特定の構成を実行できるエージェントを確認するには、ビルド設定 | エージェント要件にアクセスしてください。エージェント要件ビデオガイド：要件構文：エージェント要件は式です。ここは、定義済みまたはカスタム (ユーザー定義) のビルドパラメーターです。例: エージェントにインストールされているオペレーティングシステムを報告するパラメーター。要件では、エージェントがこの特...

ビルドパラメーターの設定

パラメーターは、TeamCity 設定およびビルドスクリプトの構文を介して参照するペアです。パラメーター部分は、生の値 () にすることも、別のパラメーターへの参照 () を含めることもできます。パラメーター型：TeamCity は次の 3 種類のパラメーターをサポートします。構成パラメーター — ビルド構成内で設定を共有することを主な目的とするパラメーター。これらのパラメーターを使用して、テンプレートから作成された構成やレシピを使用する構成をカスタマイズすることもできます。TeamCity は...

クラウドのホストビルドエージェント

TeamCity とクラウド (IaaS) ソリューションの統合により、TeamCity は TeamCity エージェントをオンデマンドで実行する仮想マシンを提供できるようになります。これにより、TeamCity は現在のワークロードに応じてアクティブなビルドエージェントの数を自動的に調整できます。クラウドエージェントとエグゼキューター：TeamCity は次の 2 種類の統合をサポートしています。通常のクラウドエージェント。この統合タイプでは、ビルドエージェントをホストする環境として、クラ...

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

TeamCity ビルドエージェントは、TeamCity サーバーからのコマンドをリッスンし、実際のビルドプロセスを開始するソフトウェアです。実稼働の TeamCity セットアップでは、専用のマシンに追加のビルドエージェントをインストールする必要があります。その前に、エージェントとサーバー間の通信、システム要件、競合するソフトウェア、およびセキュリティに関する注意事項を必ず参照してください。Tomcat サーブレットコンテナーにバンドルされた TeamCity をインストールするか、Window...