Kubernetes 向け TeamCity のセットアップ

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

通常の Kubernetes 統合。このアプローチでは、AWS、Microsoft Azure、Google Cloud などの他のクラウドプロバイダーとの統合と同様に、TeamCity クラウドプロファイルとイメージを使用します。 TeamCity でビルドエージェントを構成し、Kubernetes クラスターを使用してそれらをホストします。この統合タイプは、外部の Kubernetes Support プラグインに依存します。
外部エグゼキューターとしての Kubernetes クラスター。このモードでは、TeamCity は Kubernetes 側のビルドエージェントを認識しません。代わりに、クラスターのビルド実行機能を認識し、ビルドを実行するエンティティの割り当てとライフサイクル管理をクラスターに完全に委譲します。

この記事では、最初の統合タイプについて説明します。実行モードについては、エグゼキューターモード: 外部 Kubernetes 統合のトピックを参照してください。

要件

TeamCity と Kubernetes の統合は、 kubectl ツールに依存しないため、クラスターにインストールする必要はありません。

TeamCity ユーザーが、TeamCity エージェントで使用される Kubernetes 名前空間で書き込み操作を実行できることを確認してください。

また、Kubernetes ユーザーロールに対して次の権限を設定する必要がある場合があります。

Pods: 取得、 作成、 一覧表示、 削除.
デプロイ: 一覧表示、 取得 — デプロイ構成を使用してエージェント pod を作成する場合。
名前空間: 取得、 一覧表示 — TeamCity がサーバーで利用可能な名前空間を提案できるようにします。

Kubernetes RBAC(英語) を介して必要なすべての権限を設定する例を次に示します。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: teamcity:manage-agents
rules:
- apiGroups: [""]
  resources: ["namespaces"]
  verbs: ["list", "get"]
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "create", "list", "delete"]
- apiGroups: ["extensions", "apps"]
  resources: ["deployments"]
  verbs: ["list", "get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: teamcity:manage-agents
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: teamcity:manage-agents
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

  

Kubernetes クラウドプロファイルの構成

Kubernetes との統合を確立するには、TeamCity で専用のクラウドプロファイルを作成する必要があります。必要なプロジェクトの設定を開き、クラウドプロファイルセクションで新規プロファイルを作成をクリックします。

以下の表に、Kubernetes クラウドプロファイルに固有のオプションを示します。

オプション	説明
Kubernetes API サーバーの URL	KubernetesAPI サーバー(英語)の URL を指定します。
証明する機関 (CA)	クラスターの CA 証明書(英語)のコンテンツを入力します。
Kubernetes 名前空間	必要な Kubernetes 名前空間(英語)を指定します。デフォルトの名前空間(英語)を使用するには、空のままにします。
認証戦略	必要な認証戦略を選択します。選択した戦略に応じて、追加オプションのセットは異なります。使用可能なオプションの詳細については、 Kubernetes のドキュメント(英語)を参照してください。 Token 戦略は、Kubernetes がサポートする任意のトークンタイプを受け入れます。

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

プロキシサーバーの URL を protocol://address:port 形式で指定してください。
プロキシサーバーの認証情報を入力してください。
プロキシサーバーを経由せずに直接利用できる必要があるホストを指定してください。通常、これらはローカルネットワーク内の内部リソースです。複数のエントリはコンマで区切ってください。例: http://localhost,*.mydomain.com。
特定のプロジェクトでこれらの設定を有効にするには、プロジェクト設定に teamcity.internal.kubernetes.enableProxySettings=true パラメーターを追加します。グローバルに有効にするには、代わりに内部サーバー設定に同じパラメーターを追加します。

Kubernetes クラウドイメージの追加

一般的な Kubernetes 設定を構成した後、新しいビルドエージェントイメージの追加に進むことができます。

クラウドプロファイルの設定で、イメージを追加をクリックしてオプションを設定します。

オプション	説明
Pod 仕様	以下に説明する 3 つのタイプのいずれかを選択します。
エージェントプール	起動されたインスタンスを特定のエージェントプールに割り当てます。
エージェント名接頭辞	(オプション) TeamCity で表示する際に、このイメージのすべてのインスタンスに同じ接頭辞を表示します。
インスタンスの最大数	（オプション）このイメージに基づいて起動されるインスタンスの数を制限する場合は、こ数を設定します。

デプロイから pod テンプレートを使用

Kubernetes クラスターで作成された特定のデプロイ構成(英語)に基づいて新しい pod を実行するには、このオプションを選択します。 Kubernetes ダッシュボードを使用している場合は、利用可能なデプロイのリストがワークロード | デプロイにあります。

次のように、最新の TeamCity エージェントイメージから単純なデプロイを作成できます:

create deployment simpledep --image="jetbrains/teamcity-agent:latest"
deployment.apps/simpledep created

単一コンテナーを実行

Docker Hub(英語) からの任意のエージェント Docker イメージに基づいて単一のコンテナー(英語)を実行するには、このオプションを選択します。以下を指定する必要があります。

オプション	説明
Docker イメージ名	`docker run` コマンドで使用されるものと同様の Docker イメージの名前（たとえば、 `jetbrains/teamcity-agent`）。
イメージプルポリシー	イメージの更新ポリシー。
コマンド	（オプション）コンテナーによって実行されるコマンド(英語)を設定します。
コマンド引数	（オプション）コマンド引数を設定します。

カスタム pod テンプレートを使用

独自の pod テンプレート(英語)を YAML 形式で入力します。起動した pod に対してリソースのリクエスト / 制限や資格情報などの追加の構成を指定する必要がある場合は、このオプションを使用します。このオプションはデプロイからのテンプレート仕様の代替であり、TeamCity UI/DSL で構成を直接編集できます。

単純なテンプレートの例:

apiVersion: v1
kind: Pod
metadata:
  labels:
    app: teamcity-agent
spec:
  restartPolicy: Never
  containers:
    - name: teamcity-agent
      image: jetbrains/teamcity-agent
      resources:
        limits:
          memory: "2Gi"

   

Kotlin DSL

k8s プロファイルとイメージを作成して設定するには、プロジェクトの 機能 グループに KubernetesCloudProfile および KubernetesCloudImage クラスのインスタンスを作成します。イメージの プロファイル ID プロパティをプロファイルの ID 値に設定して、このイメージをターゲットプロファイルに割り当てます。

project {
    // ...
    features {
        // ...
        kubernetesCloudProfile {
            id = "kube-1"
            name = "K8S Agents"
            description = "EKS"
            serverURL = "https://myteamcityserver.com"
            terminateIdleMinutes = 30
            apiServerURL = "https://123.gr7.eu-west-1.eks.amazonaws.com"
            caCertData = "abc"
            authStrategy = eks {
                accessId = "aws_access_id"
                secretKey = "aws_key"
                clusterName = "my-k8s-cluster"
            }
        }
        kubernetesCloudImage {
            id = "PROJECT_EXT_10"
            profileId = "kube-1"
            agentPoolId = "21"
            agentNamePrefix = "k8s-singlec"
            maxInstancesCount = 5
            podSpecification = runContainer {
                dockerImage = "jetbrains/teamcity-agent"
            }
        }
        kubernetesCloudImage {
            id = "PROJECT_EXT_11"
            profileId = "kube-1"
            agentPoolId = "21"
            agentNamePrefix = "k8s-pspec"
            maxInstancesCount = 5
            podSpecification = customTemplate {
                customPod = """
                    apiVersion: v1
                    kind: Pod
                    metadata:
                      labels:
                        app: teamcity-agent
                    spec:
                      restartPolicy: Never
                      containers:
                        - name: teamcity-agent
                          image: jetbrains/teamcity-agent
                          resources:
                            limits:
                              memory: "2Gi"
                """.trimIndent()
            }
        }
    }
}

  

その他の例と API の説明については、 KubernetesCloudProfile および KubernetesCloudImage を参照してください。

2026 年 9 月 11 日