执行模式：外部 Kubernetes 集成

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

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

本文解释了原生集成方法。若要了解传统集成，请参阅为 Kubernetes 配置 TeamCity 主题。

工作原理

创建一个 Kubernetes 连接，以允许 TeamCity 访问您的 K8s 集群。
在项目设置中，转到云配置文件部分并点击创建新配置文件。
点击“将任务卸载到外部代理”部分下的 Kubernetes 图块。
按以下方式设置您的 K8s 集成：
- 连接 — 选择在步骤 1 中创建的连接。
- 服务器 URL — 输入您的 TeamCity 服务器 URL，或留空以使用服务器全局设置页面上指定的 URL。
- Pod 模板 — 选择所需的 pod 配置。有关更多信息，请参阅 Pod 模板部分。
- 最大构建数量 — 输入集群容量。当达到此容量时，新构建将保持排队状态，直到当前正在进行的构建完成。
在您的构建配置设置中，指定代理需求和步骤容器（如果需要）。
触发一个新构建。
TeamCity K8s 执行器收集带有其参数的构建步骤列表，生成一个 pod 定义，并将其提交到 K8s 集群。每个构建步骤在一个单独的容器中运行，这允许您为各个步骤指定不同的镜像。
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 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 的本地代理，但其数量仍受您的代理许可证限制。 “本地”构建和执行器构建的总数不能超过此许可限制。当达到限制时，新构建将保持排队状态，并显示“已达到最大并发构建数”消息，等待空闲代理槽位。

分离构建以及由复合构建配置生成的构建不会占用代理槽位，可以无限制运行。

特别说明和限制

目前，一个项目只能使用一个 Kubernetes 集成。我们预计在未来的发布周期中支持每个项目的多个执行器（以及优先级机制）。
Kubernetes 集群充当外部协调器，处理构建而无需使用连接到 TeamCity 服务器的“经典”构建代理。这会导致在执行器处理的构建运行时显示“构建代理在运行构建时断开连接”警告。只要构建成功完成，此警告并不表示配置错误或连接问题，可以忽略。我们预计将在即将发布的错误修复版本中解决此行为。
Pod 模板指定自定义容器属性时，必须具有“template-container”容器名称。
# ... template: spec: containers: - name: template-container image: johndoe/custom_agent_image:latest # ...
否则，容器将使用默认设置。例如，它将覆盖 image 属性，使用标准的“jetbrains/teamcity-agent:latest”镜像。
目前，Kubernetes 执行器不支持 Windows 节点。由这些节点处理的构建会卡在“设置资源”阶段，pod 显示 MountVolume.SetUp failed for volume "kube-api-access-sfhbc" 错误。因此，设计为在 Windows 下运行的构建无法委派给 Kubernetes 执行器。
为避免混合集群（同时包含 Windows 和 Linux 节点）中的此问题，请在 pod 模板中指定所需节点：
spec: containers: # ... nodeSelector: kubernetes.io/os: linux
Docker 构建步骤不受支持。
不支持 Docker inside Docker (DinD) 设置。
Pod 初始化可能会在清理“/agent/temp/.old”目录时停滞。
如果配置的父项目已配置 Kubernetes 执行器，则构建步骤中无法使用高级容器包装器。

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