安装 Kubernetes 代理

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

先决条件

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

  • 现有的 Kubernetes 集群。如果您没有集群，您可以在云提供商上创建一个。
  • 在私有化部署版极狐GitLab 实例上，管理员必须设置代理服务器。然后将默认在 wss://gitlab.example.com/-/kubernetes-agent/ 上可用。在 JihuLab.com 上，代理服务器在 wss://kas.jihulab.com 上可用。

使用 Flux 启用代理（推荐）

您可以通过使用极狐GitLab CLI（glab和 Flux 来启用代理。

先决条件：

  • 您已经安装了如下命令行工具：

    • glab
    • kubectl
    • flux
  • 您有一个本地集群，而且连接能够通过 kubectl 和 flux 正常使用。
  • 您使用 flux bootstrap 命令将 Flux bootstrap 到了集群。
    • 确保将 Flux 和代理 bootstrap 到了兼容的目录中。如果您使用 --path 选项，您必须将相同的值传递给使用 --manifest-path 选项的 glab cluster agent bootstrap 命令 。

要安装代理：

  • 运行 glab cluster agent bootstrap： 

    glab cluster agent bootstrap <agent-name>

默认情况下，命令会：

  1. 注册代理。
  2. 配置代理。
  3. 配置一个环境，为代理添加一个仪表板。
  4. 创建一个代理令牌。
  5. 在集群中创建一个 Kubernetes secret，用于存储代理令牌。
  6. 将 Flux Helm 资源提交到 Git 仓库。
  7. 触发 Flux 的重新配置。

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

手动安装代理

有三种方法可以在集群中安装代理：

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

创建代理配置文件

代理使用 YAML 文件进行配置设置。如果出现以下情况，您需要一个配置文件：

要创建代理配置文件：

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

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

  2. 在仓库中，在默认分支中，在根目录下创建此目录： 

    .gitlab/agents/<agent-name>

您现在可以将文件留空，稍后配置它。

向极狐GitLab 注册代理

选项 1: 搭理连接到极狐GitLab

您可以直接从极狐GitLab UI 上创建一个新的代理记录。该代理无需创建带来配置文件即可被注册。

在您安装代理到集群之间，您必须先注册代理。要注册代理：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的项目。如果您已经有代理配置文件，那么该文件必须在此项目中。而且您集群的清单文件也应该在此项目中。
  2. 选择 运维 > Kubernetes 集群。
  3. 选择 连接集群 (代理)。
    • 如果您想使用 CI/CD 默认配置来创建配置，输入代理名称。
    • 如果您已经有代理配置文件，从列表中选择即可。
  4. 选择 注册代理。
  5. 极狐GitLab 会生成一个访问令牌，您需要在安装代理时使用。
caution 安全存储代理访问令牌。攻击者可以使用此令牌来访问代理配置项目中的源代码、访问任何公共项目中的源代码，或者在非常特定的条件下获取 Kubernetes 清单。
  1. 复制 推荐安装方法 下的命令。您需要在安装代理时使用。

选项 2：极狐GitLab 连接到代理（接受型带来）

  • 引入于极狐GitLab 17.4。
note极狐GitLab 代理 Helm Chart 版本完全支持 mTLS 认证。您应该使用 JWT 方法认证。

接受型代理允许极狐GitLab 与那些无法建立与极狐GitLab 实例的网络连接，但可以被极狐GitLab 连接的 Kubernetes 集群集成。

  1. 遵循选项 1 中的部署来在集群中注册代理。保存代理令牌并在随后的安装命令中使用，但是先不要安装代理。

  2. 准备认证方法。

    极狐GitLab 到代理的连接可以通过纯文本的 gPRC (grpc://) 或加密的 gRPC (grpcs://，推荐)。可以使用如下方法来在集群中认证代理： - 一个 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=<public_key from the response>

可能需要等 10 分钟，极狐GitLab 才能开始尝试与新代理建立连接。

在集群中安装代理

极狐GitLab 推荐使用 Helm 来安装代理。

要连接集群到极狐GitLab，在您的集群上注册代理。您可以：

如果您不知道选择哪一个，我们推荐您使用 Helm 进行安装。

要安装可接受型代理，遵循极狐GitLab 连接到代理（可接受型代理中的步骤。

note要连接到多个集群，您必须在每个集群中配置、注册和安装代理。确保给每个代理一个唯一的名称。

使用 Helm 安装代理

caution为了简化，Helm chart 默认配置为代理设置 cluster-admin 权限的服务账户。您不应该在生产系统上使用此配置。要部署到生产系统，遵循自定义 Helm 安装中的说明，创建具有您部署所需的最小权限的服务账户，并在安装时指定该服务账户。

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

  1. 安装 Helm CLI。
  2. 在您的计算机上，打开一个终端并连接到您的集群。

  3. 运行您在注册代理是拷贝的命令。命令应该像： 

    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=<current agentk version> \
    --set config.token=<your_token> \
    --set config.kasAddress=<address_to_GitLab_KAS_instance>
  4. 可选。自定义 Helm 安装。如果您在生产系统上安装代理，您应该自定义 Helm 安装以限制服务账户的权限。相关自定义选项描述如下。

自定义 Helm 安装

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

  • 为部署创建命名空间 gitlab-agent（--namespace gitlab-agent）。您可以通过省略 --create-namespace 标志来跳过创建命名空间。
  • 为具有 cluster-admin 权限的代理设置服务账户。您可以：
    • 通过将 --set serviceAccount.create=false 添加到 helm install 命令来跳过创建服务账户。在这种情况下，您必须将 serviceAccount.name 设置为预先存在的服务账户。
    • 通过添加 --set rbac.useExistingRole <your role name> 到 helm install 命令中来自定义指派给服务账号的角色。在这种情况下，您应该有一个预先创建的、具有受限权限的角色，可以被服务账号使用。
    • 通过将 --set rbac.create=false 添加到 helm install 命令来跳过创建 RBAC 权限。在这种情况下，您必须为代理带来自己的 RBAC 权限。否则代理没有权限。
  • 为代理的访问令牌创建一个 Secret 资源。要使用令牌带来您自己的 secret，请省略令牌（--set token=...），而使用 --set config.secretName=<your secret name>。
  • 为 agentk pod 创建一个 Deployment 资源。
当 KAS 在自签名证书后面时使用代理

当 KAS 在自签名证书后面时，您可以将 config.caCert 的值设置为证书。例如： 

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

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

如果 KAS 与极狐GitLab chart 一起安装，并且 chart 配置为提供自动生成的自签名通配符证书，您可以从 RELEASE-wildcard-tls-ca secret 中提取 CA 证书。

在 HTTP 代理后面使用代理
  • 引入于 15.0 版本，GitLab 代理 Helm 图表支持设置环境变量。

如要在使用 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 \
  ...
noteDNS 重绑定保护会在设置 HTTP_PROXY 或 HTTPS_PROXY 环境变量时禁用，而且域名 DNS 也无法被解析。

高级安装方法

极狐GitLab 还提供了代理的 KPT 软件包。此方法提供了更大的灵活性，但是仅推荐高级用户使用。

配置您的代理

要配置您的代理，请将内容添加到 config.yaml 文件：

在集群中安装多个代理

note在大多数情况下，您应该在每个集群中运行一个代理，并使用代理模仿功能（仅支持专业版和旗舰版用户）来支持多租户。

要想在集群中安装第二个代理，您可以再一次执行之前的步骤。为了避免集群内的资源冲突，您必须：

  • 为代理使用不同的版本名称，比如 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 模块启用时，每个代理都会触发调谐。

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

  • 为代理配置 RBAC 以便其只能访问所需的 Flux 资源。
  • 在不使用 Flux 的代理上禁用 Flux 模块。

更新和版本兼容性

极狐GitLab 会在代理列表页面警告您更新集群上安装的代理版本。

最佳体验是，集群上安装的代理版本与极狐GitLab 的主次版本匹配。当然，也会支持之前或下一个小版本。比如，如果您的极狐GitLab 版本是 v14.9.4，那么 v14.9.0 和 v14.9.1 的代理版本都是理想的，但任何 v14.8.x 或 v14.10.x 的代理版本也是支持的。

更新代理版本

note与其使用 --reuse-values，不如指定所有需要的值。如果您使用 --reuse-values，您可能会错过新默认值或使用已弃用的值。要获取之前的 --set 参数，使用 helm get values <release name>。您可以使用 helm get values gitlab-agent > agent.yaml 将值保存到文件中，并使用 -f 传递给 Helm：helm upgrade gitlab-agent gitlab/gitlab-agent -f agent.yaml。这能够很安全地替换 --reuse-values 的行为。

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

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 agent 的更新是分开的，并且可能偶尔会落后于该代理的最新版本。 如果您运行 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 manifest 文件的目录。如果您使用 --path 选项，您必须将相同的值传递给使用 --manifest-path 选项的 glab cluster agent bootstrap 命令。
  • Flux 指向一个没有 kustomization.yaml 的项目根目录，这导致 Flux 遍历子目录查找 YAML 文件。要使用代理，您必须在 .gitlab/agents/<agent-name>/ 目录下创建一个代理配置文件，该文件不是有效的 Kubernetes manifest。Flux 应用此文件失败，就会发生错误。为了解决此问题，您应该将 Flux 指向一个子目录而不是根目录。