为 Kubernetes 配置 TeamCity

TeamCity 提供两种类型的 Kubernetes 集成：

常规 Kubernetes 集成。此方法使用 TeamCity 云配置文件和镜像，类似于与其他云提供商（如 AWS、Microsoft Azure 或 Google Cloud）的集成。您可以在 TeamCity 中配置构建代理，并使用 Kubernetes 集群来托管它们。此集成类型依赖于外部 Kubernetes Support 插件。
Kubernetes 集群作为外部执行器. 在此模式下，TeamCity 不会感知 Kubernetes 端的任何构建代理。相反，它识别集群运行构建的能力，并将运行其构建的实体的分配和生命周期管理完全委托给集群。

本文解释了传统的集成方法。要了解原生集成，请参阅执行模式：外部 Kubernetes 集成主题。

要求

TeamCity 与 Kubernetes 的整合并不依赖于 kubectl 工具，因此您的集群中无需安装它。

确保 TeamCity 用户有权限在 TeamCity 代理使用的 Kubernetes namespace 中执行写操作。

您可能还需要为您的 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	指定 Kubernetes API server 的 URL。
证书颁发机构（CA）	请输入您的集群的 CA 证书内容。
Kubernetes 命名空间	指定一个必需的 Kubernetes 命名空间。留空则使用默认命名空间。
认证策略	选择所需的身份验证策略。根据所选策略，额外选项的设置会有所不同。请参考 Kubernetes 文档，了解可用选项的详细信息。 Token 策略接受 Kubernetes 支持的任何 token 类型。

添加 Kubernetes 云镜像

在配置完一般的 Kubernetes 设置后，您可以继续添加新的构建代理镜像。

点击添加镜像并配置其选项：

选项	描述
Pod 规格说明	选择下面描述的三种类型中的一种。
Agent pool（代理池）	将启动的实例分配给特定的代理池。
代理名称前缀	（可选）在 TeamCity 中显示此镜像的所有实例时，显示相同的前缀。
最大实例数	（可选）如果您想限制基于此镜像启动的实例数量，请设置此数字。

使用部署中的 pod 模板

选择此选项，以基于在您的 Kubernetes 集群中创建的特定部署配置运行新的 pod。如果您使用 Kubernetes Dashboard，您可以在工作负载 | 部署下找到可用部署的列表。

您可以按照以下步骤，从最新的 TeamCity 代理镜像创建一个简单的部署：

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

运行单个容器

选择此选项可基于任何给定的代理 Docker 镜像运行单个容器，这些镜像来自 Docker Hub。您需要指定：

选项	描述
Docker 镜像名称	Docker 镜像的名称，类似于与 `docker run` 命令一起使用的那个（例如， `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 类实例。将镜像 profileId 属性设置为配置文件 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()
            }
        }
    }
}

  

参见 KubernetesCloudProfile 和 KubernetesCloudImage 获取更多实例和 API 说明。

最后修改日期： 2025年 9月 3日