为 Kubernetes 安装代理

要将 Kubernetes 集群连接到 GitLab，您必须在集群中安装一个代理。

前置条件

在集群中安装代理前，您需要：

• 一个现有的 可从本地终端连接的 Kubernetes 集群。如果没有集群，可在云服务提供商上创建，例如：
  • Amazon Elastic Kubernetes Service (EKS)
  • Azure Kubernetes Service (AKS)
  • Digital Ocean
  • Google Kubernetes Engine (GKE)
  • 建议使用 基础设施即代码（Infrastructure as Code）技术 管理大规模基础设施资源。
• 访问代理服务器：
  • 在 GitLab.com 上，代理服务器地址为 wss://kas.gitlab.com。
  • 在 GitLab Self-Managed 上，GitLab 管理员必须设置 代理服务器。 默认地址为 wss://gitlab.example.com/-/kubernetes-agent/。
  • 在 GitLab Dedicated 上，代理服务器地址为 wss://kas.<instance-domain>（例如 wss://kas.example.gitlab-dedicated.com）。如果 GitLab Dedicated 实例使用 自定义主机名，您也可为 KAS 服务选择自定义主机名。

使用 Flux 支持引导代理（推荐）

您可以通过 GitLab CLI (glab) 和 Flux 引导代理来安装它。

前置条件：

• 已安装以下命令行工具：
  • glab
  • kubectl
  • flux
• 本地集群连接可与 kubectl 和 flux 协同工作。
• 您已使用 flux bootstrap 引导 Flux 到集群。
  • 确保在兼容目录中引导 Flux 和代理。如果使用 --path 选项引导 Flux，必须将相同值传递给 glab cluster agent bootstrap 命令的 --manifest-path 选项。

安装代理的方法：

• 在目标项目的 Git 仓库目录中运行 glab cluster agent bootstrap：

  glab cluster agent bootstrap <代理名称> --manifest-path <flux_bootstrap中使用的相同路径>

• 如果必须在目标项目的 Git 仓库外运行命令，请使用 glab -R path-with-namespace cluster agent bootstrap：

  glab -R <项目完整路径> cluster agent bootstrap <代理名称> --manifest-path <flux_bootstrap中使用的相同路径>

默认情况下，该命令会：

1. 注册代理。
2. 配置代理。
3. 配置带有代理仪表板的环境。
4. 创建代理令牌。
5. 在集群中创建包含代理令牌的 Kubernetes Secret。
6. 将 Flux Helm 资源提交到 Git 仓库。
7. 触发 Flux 协调。

自定义选项请运行 glab cluster agent bootstrap --help。您可能至少需要使用 --path <flux_manifests_directory> 选项。

手动安装代理

在集群中安装代理需三步：

1. 可选。创建代理配置文件。
2. 向 GitLab 注册代理。
3. 在集群中安装代理。

观看此过程的操作演示。

创建代理配置文件

代理使用 GitLab 项目中的 YAML 文件进行配置。添加代理配置文件是可选的。如果满足以下条件则必须创建此文件：

• 您使用 GitLab CI/CD 工作流 并希望授权不同项目或组访问代理。
• 您允许特定项目或组成员访问 Kubernetes。

创建代理配置文件：

1. 为代理选择名称。代理名称需遵循 RFC 1123 的 DNS 标签标准。名称必须：

   • 在项目中唯一。
   • 最多包含 63 个字符。
   • 仅包含小写字母数字字符或 -。
   • 以字母数字字符开头。
   • 以字母数字字符结尾。

2. 在仓库的默认分支中，在以下位置创建代理配置文件：

   .gitlab/agents/<代理名称>/config.yaml

您可以暂时留空文件，稍后进行配置。

向 GitLab 注册代理

选项 1：代理连接 GitLab

您可以直接从 GitLab UI 创建新的代理记录。 无需创建代理配置文件即可注册代理。

在集群中安装代理前必须注册代理。注册代理步骤：

1. 在左侧边栏选择 Search or go to 并找到您的项目。 如果存在代理配置文件，它必须位于此项目中。 您的集群清单文件也应在此项目中。

2. 选择 Operate > Kubernetes clusters。

3. 选择 Connect a cluster (agent)。

4. 在 Name of new agent 字段中输入代理的唯一名称。

   • 如果已存在同名代理配置文件，则使用该文件。
   • 如果不存在该名称的配置，将使用默认配置创建新代理。

5. 选择 Create and register。

6. GitLab 为代理生成访问令牌。安装代理到集群时需要此令牌。

   请妥善保存代理访问令牌。恶意行为者可能使用此令牌访问代理配置项目中的源代码、访问 GitLab 实例上任何公共项目中的源代码，甚至在特定条件下获取 Kubernetes 清单。

7. 复制 Recommended installation method 下的命令。使用单行安装方法在集群中安装代理时需要此命令。

选项 2：GitLab 连接代理（响应式代理）

响应式代理 允许 GitLab 与无法建立到 GitLab 实例网络连接但可被 GitLab 连接的 Kubernetes 集群集成。

1. 按照选项 1 的步骤在集群中注册代理。 保存代理令牌和安装命令以备后用，但暂不安装代理。

2. 准备身份验证方法。

   GitLab 到代理的连接可以是明文 gRPC (grpc://) 或加密 gRPC (grpcs://，推荐）。 GitLab 可使用以下方式向集群中的代理进行身份验证：

   • JWT 令牌。在 grpc:// 和 grpcs:// 配置中均可用。此方法无需生成客户端证书。

3. 使用集群代理 API 向代理添加 URL 配置。如果删除 URL 配置，响应式代理将变为普通代理。一次只能将响应式代理关联一个 URL 配置。

4. 将代理安装到集群。使用注册代理时复制的命令，但删除 --set config.kasAddress=... 参数。

   JWT 令牌身份验证示例。注意添加的 config.receptive.enabled=true 和 config.api.jwt 设置：

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   helm upgrade --install my-agent gitlab/gitlab-agent \
    --namespace ns \
    --create-namespace \
    --set config.token=.... \
    --set config.receptive.enabled=true \
    --set config.api.jwtPublicKey=<响应中的公钥>

GitLab 可能需要最多 10 分钟开始尝试与新代理建立连接。

在集群中安装代理

要将集群连接到 GitLab，使用 Helm 安装已注册的代理。

安装响应式代理，请遵循 GitLab 连接代理（响应式代理） 中的步骤。

使用 Helm 安装代理

使用 Helm 在集群中安装代理：

1. 安装 Helm CLI。

2. 在计算机上打开终端并连接到您的集群。

3. 运行在向 GitLab 注册代理时复制的命令。命令应如下所示：

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   helm upgrade --install test gitlab/gitlab-agent \
       --namespace gitlab-agent-test \
       --create-namespace \
       --set image.tag=<当前 agentk 版本> \
       --set config.token=<您的令牌> \
       --set config.kasAddress=<GitLab KAS 实例地址>

4. 可选。自定义 Helm 安装。 如果在生产系统上安装代理，应自定义 Helm 安装以限制服务账户权限。相关自定义选项如下所述。

自定义 Helm 安装

默认情况下，GitLab 生成的 Helm 安装命令：

• 为部署创建名为 gitlab-agent 的命名空间 (--namespace gitlab-agent)。可通过省略 --create-namespace 标志跳过创建命名空间。
• 为代理设置服务账户并分配 cluster-admin 角色。您可以：
  • 通过向 helm install 命令添加 --set serviceAccount.create=false 跳过创建服务账户。此时必须将 serviceAccount.name 设置为现有服务账户。
  • 通过向 helm install 命令添加 --set rbac.useExistingRole <您的角色名称> 自定义分配给服务账户的角色。此时应具有具有受限权限的预创建角色供服务账户使用。
  • 通过向 helm install 命令添加 --set rbac.create=false 完全跳过角色分配。此时必须手动创建 ClusterRoleBinding。
• 为代理的访问令牌创建 Secret 资源。若要使用自有令牌 Secret，请省略令牌 (--set token=...) 并改用 --set config.secretName=<您的 Secret 名称>。
• 为 agentk Pod 创建 Deployment 资源。

要查看所有可用自定义选项，请参阅 Helm Chart 的 README。

当 KAS 使用自签名证书时使用代理

当 KAS 使用自签名证书时， 可将 config.kasCaCert 的值设置为证书。例如：

helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --set-file config.kasCaCert=my-custom-ca.pem

在此示例中，my-custom-ca.pem 是包含 KAS 使用的 CA 证书的本地文件路径。 证书会自动存储在配置映射中并挂载到 agentk Pod。

如果 KAS 使用 GitLab Chart 安装，且 Chart 配置为提供自动生成的自签名通配符证书，您可以从 RELEASE-wildcard-tls-ca Secret 中提取 CA 证书。

在 HTTP 代理后使用代理

使用 Helm Chart 配置 HTTP 代理时，可使用环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。大小写均可接受。

您可以通过 extraEnv 值（作为具有 name 和 value 键的对象列表）设置这些变量。 例如，仅将环境变量 HTTPS_PROXY 设置为 https://example.com/proxy，可运行：

helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --set extraEnv[0].name=HTTPS_PROXY \
  --set extraEnv[0].value=https://example.com/proxy \
  ...

在集群中安装多个代理

要在集群中安装第二个代理，可再次遵循之前的步骤。为避免集群内资源名称冲突，必须：

• 为代理使用不同的发布名称，例如 second-gitlab-agent：

  helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...

• 或者在不同的命名空间中安装代理，例如 different-namespace：

  helm upgrade --install gitlab-agent gitlab/gitlab-agent \
    --namespace different-namespace \
    ...

由于集群中的每个代理独立运行，每个启用了 Flux 模块的代理都会触发协调。 Issue 357516 提议更改此行为。

作为临时解决方案，您可以：

• 配置代理的 RBAC，使其仅访问所需的 Flux 资源。
• 在不使用 Flux 的代理上禁用 Flux 模块。

示例项目

以下示例项目可帮助您入门代理。

• 独立应用和清单仓库示例
• 使用 CI/CD 工作流的 Auto DevOps 设置
• 使用 CI/CD 工作流的集群管理项目模板示例

更新和版本兼容性

GitLab 在代理列表页面上会提示您更新集群中安装的代理版本。

为获得最佳体验，集群中安装的代理版本应与 GitLab 的主版本和次版本匹配。也支持前一个和后一个次版本。例如，如果您的 GitLab 版本是 v14.9.4（主版本 14，次版本 9），则代理版本 v14.9.0 和 v14.9.1 是理想选择，但任何 v14.8.x 或 v14.10.x 版本也受支持。请参阅 GitLab Agent for Kubernetes 的发布页面。

更新代理版本

要将代理更新到最新版本，可运行：

helm repo update
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --namespace gitlab-agent

要设置特定版本，可覆盖 image.tag 值。例如，安装版本 v14.9.1，请运行：

helm upgrade gitlab-agent gitlab/gitlab-agent \
  --namespace gitlab-agent \
  --set image.tag=v14.9.1

Helm Chart 与 Kubernetes 代理的更新是分开的，偶尔可能滞后于代理的最新版本。如果运行 helm repo update 且未指定镜像标签，代理将运行 Chart 中指定的版本。

要使用 Kubernetes 代理的最新版本，请将镜像标签设置为与最新的代理镜像匹配。

卸载代理

如果您使用 Helm 安装了代理，也可使用 Helm 卸载。例如，如果发布和命名空间都名为 gitlab-agent，则可使用以下命令卸载代理：

helm uninstall gitlab-agent \
    --namespace gitlab-agent

故障排除

安装 Kubernetes 代理时，可能会遇到以下问题。

错误：failed to reconcile the GitLab Agent

如果 glab cluster agent bootstrap 命令失败并显示消息 failed to reconcile the GitLab Agent， 表示 glab 无法将代理与 Flux 协调。

此错误可能是因为：

• Flux 设置未指向 glab 放置代理 Flux 清单的目录。 如果使用 --path 选项引导 Flux，必须将相同值传递给 glab cluster agent bootstrap 命令的 --manifest-path 选项。
• Flux 指向项目的根目录，但该目录没有 kustomization.yaml，导致 Flux 遍历子目录查找 YAML 文件。 要使用代理，必须在 .gitlab/agents/<代理名称>/config.yaml 处有代理配置文件， 这不是有效的 Kubernetes 清单。Flux 无法应用此文件，导致错误。 解决方案应将 Flux 指向子目录而非根目录。