执行模式：无代理 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。
- YAML 配置 — 选择所需的 pod 配置。有关更多信息，请参阅 YAML 配置部分。
- 最大构建数量 — 输入集群容量。当达到此容量时，新构建将保持排队状态，直到当前正在进行的构建完成。
- 参数 — 输入参数列表（以 name=value 格式），这些参数应存在于 K8s 容器中。这些参数将与排队构建的显式代理需求匹配。因此，您可以指定哪些构建可以在您的 K8s 集群中运行。
  例如，将 k8s=yes 值添加到此字段中，以卸载具有 equals("k8s", "yes") 代理需求的构建。
  写入到 pods 的参数对在其上运行的构建不可访问。也就是说，您无法在构建过程中访问这些参数（例如，通过回显其值）或在构建结果页面或通过 /app/rest/builds/id:<Int32>?fields=properties(property) REST API 请求中查看它们。
  这些参数仅用于将执行器与配置需求匹配。
在您的构建配置设置中，指定代理需求和步骤容器（如果需要）。
触发一个新构建。
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

  

YAML 配置

podtemplates 列表 权限使 TeamCity 能够访问存储在集群中的 pod 模板列表（与所选 Kubernetes 连接中指定的命名空间相同）。检索到的模板显示在 YAML 配置下拉菜单中。

以下示例模板启动具有 2GB 内存和 25GB 存储的 pods，并使用自定义构建代理镜像（请参阅特别说明和限制部分）。

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

  

特别说明和限制

目前，一个项目只能使用一个 Kubernetes 集成。我们预计在未来的发布周期中支持每个项目的多个执行器（以及优先级机制）。
执行模式是一种无代理集成，因此 TeamCity 无法识别 Kubernetes 端的任何“经典”构建代理。这会导致在执行器处理的构建运行时显示“构建代理在运行构建时断开连接”警告。只要构建成功完成，此警告并不表示配置错误或连接问题，可以忽略。我们预计将在即将发布的错误修复版本中解决此行为。
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 因卷 "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”目录时停滞。

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