TeamCity On-Premises 2026.2 Help

エグゼキューターモード: 外部 Kubernetes 統合

TeamCity は二種類の Kubernetes 統合を提供します：

  • 通常の Kubernetes 統合。 このアプローチでは、AWS、Microsoft Azure、Google Cloud などの他のクラウドプロバイダーとの統合と同様に、TeamCity クラウドプロファイルとイメージを使用します。 TeamCity でビルドエージェントを構成し、Kubernetes クラスターを使用してそれらをホストします。 この統合タイプは、外部の Kubernetes Support プラグインに依存します。

  • 外部エグゼキューターとしての 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: 取得、 作成、 一覧表示、 削除.

  • Pod テンプレート: 取得, 一覧表示

  • 名前空間: 取得、 一覧表示 — 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 リスト 権限により、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: JAVA_HOME # defaults to "opt/java/openjdk" if not set value: /usr/local/openjdk-21 nodeSelector: linux: arm64

エージェントの優先度

ビルド構成に異なるエージェントオプションが混在している場合、TeamCity は次のロジックを使用してキュー内のビルドを割り当てます：

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

  • ビルドに対応する空きのセルフホストエージェントがない場合、TeamCity は適切な クラウドエージェントを探します

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

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

ライセンス

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

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

プロキシ設定

TeamCity サーバーが k8s クラスターにアクセスするためにプロキシサーバーを使用する必要がある場合は、送信接続を許可するために以下の追加設定を構成してください：

  • プロキシサーバーの URL を protocol://address:port 形式で指定してください。

  • プロキシサーバーの認証情報を入力してください。

  • プロキシサーバーを経由せずに直接利用できる必要があるホストを指定してください。 通常、これらはローカルネットワーク内の内部リソースです。 複数のエントリはコンマで区切ってください。例: http://localhost,*.mydomain.com。

特記事項と制限

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

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

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

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

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

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

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

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

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

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

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

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

  • Kubernetes エグゼキュータは、環境変数 JAVA_HOME で参照される Java を使用します。 この変数が空または存在しない場合は、代わりにデフォルトの opt/java/openjdk が使用されます。

2026 年 9 月 11 日
VMware vSphere および vCenter 向け TeamCity のセットアップ 外部データベースのセットアップ