极狐 GitLab Logo

安装 Kubernetes 代理

  • Tier: 基础版、专业版、旗舰版
  • Offering: JihuLab.com, 私有化部署

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

先决条件#

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

  • 一个现有的 Kubernetes 集群，您可以从本地终端连接。
  • 在极狐GitLab 私有化部署上，极狐GitLab 管理员必须设置 代理服务器。然后它默认可用，地址为 wss://gitlab.example.com/-/kubernetes-agent/。在 JihuLab.com 上，代理服务器的地址是 wss://kas.gitlab.com。

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

您可以使用 极狐GitLab CLI (glab) 和 Flux 引导安装代理。

先决条件：

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

要安装代理：

  • 运行 glab cluster agent bootstrap：

    shell
    glab cluster agent bootstrap <agent-name> --manifest-path <same as --path used in flux bootstrap>

默认情况下，命令：

  1. 注册代理。
  2. 配置代理。
  3. 为代理配置带有仪表盘的环境。
  4. 创建代理令牌。
  5. 在集群中，创建一个带有代理令牌的 Kubernetes 密钥。
  6. 将 Flux Helm 资源提交到 Git 仓库。
  7. 触发 Flux 对账。

有关自定义选项，请运行 glab cluster agent bootstrap --help。您可能至少希望使用 --path <flux_manifests_directory> 选项。

手动安装代理#

在您的集群中安装代理需要三个步骤：

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

观看 该过程的演练。

创建代理配置文件#

对于配置设置，代理在极狐GitLab 项目中使用 YAML 文件。添加代理配置文件是可选的。您必须创建此文件，如果：

要创建代理配置文件：

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

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

  2. 在仓库中，在默认分支上，创建一个代理配置文件：

    plaintext
    .gitlab/agents/<agent-name>/config.yaml

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

在极狐GitLab 中注册代理#

选项 1：代理连接到极狐GitLab#

您可以直接从极狐GitLab UI 创建新的代理记录。代理可以在不创建代理配置文件的情况下注册。

您必须注册代理才能在集群中安装代理。要注册代理：

  1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。 如果您有一个 代理配置文件， 它必须在此项目中。您的集群清单文件也应该在此项目中。

  2. 选择 操作 > Kubernetes 集群。

  3. 选择 连接集群（代理）。

  4. 在 新代理名称 字段中，为您的代理输入一个唯一名称。

    • 如果已经存在一个具有此名称的 代理配置文件，则使用该文件。
    • 如果没有此名称的配置，则会使用默认配置创建一个新的代理。

  5. 选择 创建和注册。

  6. 极狐GitLab 生成一个代理的访问令牌。您需要此令牌来安装代理 在您的集群中。

安全存储代理访问令牌。恶意行为者可以使用此令牌访问代理配置项目中的源代码，访问极狐GitLab 实例上任何公共项目中的源代码，甚至在非常特定的条件下获取 Kubernetes 清单。

  1. 复制 推荐安装方法 下的命令。当您使用单行安装方法在集群中安装代理时需要它。

选项 2：极狐GitLab 连接到代理（接收代理）#

  • Tier: 旗舰版
  • Offering: 极狐GitLab 私有化部署
History
    • 在极狐GitLab 17.4 中引入。

极狐GitLab 代理 Helm Chart 版本不完全支持 mTLS 身份验证。您应该使用 JWT 方法进行身份验证。

接收代理 允许极狐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 设置：

    shell
    1helm repo add gitlab https://charts.gitlab.io
2helm repo update
3helm upgrade --install my-agent gitlab/gitlab-agent \
4 --namespace ns \
5 --create-namespace \
6 --set config.token=.... \
7 --set config.receptive.enabled=true \
8 --set config.api.jwtPublicKey=<public_key from the response>

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

在集群中安装代理#

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

要将您的集群连接到极狐GitLab，请在集群中安装注册的代理。您可以：

如果您不知道选择哪个，我们建议从 Helm 开始。

要安装接收代理，请按照 极狐GitLab 连接到代理（接收代理） 中的步骤进行。

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

使用 Helm 安装代理#

为了简单起见，默认的 Helm chart 配置为代理设置了一个具有 cluster-admin 权限的服务帐户。您不应该在生产系统上使用此配置。要部署到生产系统，请按照 自定义 Helm 安装 中的说明创建具有最低权限的服务帐户，并在安装期间指定。

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

  1. 安装 Helm CLI。

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

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

    shell
    1helm repo add gitlab https://charts.gitlab.io
2helm repo update
3helm upgrade --install test gitlab/gitlab-agent \
4    --namespace gitlab-agent-test \
5    --create-namespace \
6    --set image.tag=<current agentk version> \
7    --set config.token=<your_token> \
8    --set config.kasAddress=<address_to_GitLab_KAS_instance>

  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 <your role name> 来自定义分配给服务帐户的角色。在这种情况下，您应该有一个预先创建的角色，该角色具有可供服务帐户使用的受限权限。
    • 通过在 helm install 命令中添加 --set rbac.create=false 来完全跳过角色分配。在这种情况下，您必须手动创建 ClusterRoleBinding。
  • 为代理的访问令牌创建 密钥 资源。要改为使用您自己的带有令牌的密钥，请省略令牌 (--set token=...)，而是使用 --set config.secretName=<your secret name>。
  • 为 agentk pod 创建 部署 资源。
在 KAS 位于自签名证书后时使用代理#

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

shell
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 密钥中提取 CA 证书。

在 HTTP 代理后使用代理#
History
    • 在极狐GitLab 15.0 中引入，极狐GitLab 代理 Helm chart 支持设置环境变量。

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

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

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

当设置了 HTTP_PROXY 或 HTTPS_PROXY 环境变量，并且无法解析域 DNS 时，DNS 重绑定保护会被禁用。

高级安装方法#

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

在集群中安装多个代理#

在大多数情况下，您应该在每个集群中运行一个代理，并使用代理模拟功能（仅旗舰版和专业版）支持多租户。如果您必须运行多个代理，我们希望听到您遇到的任何问题。

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

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

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

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

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

因为集群中的每个代理都是独立运行的，所有启用 Flux 模块的代理都会触发对账。

作为一种解决方法，您可以：

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

更新和版本兼容性#

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

为了获得最佳体验，您集群中安装的代理版本应匹配极狐GitLab 的主要和次要版本。之前和下一个次要版本也受支持。例如，如果您的极狐GitLab 版本是 v14.9.4（主要版本 14，次要版本 9），那么代理的版本 v14.9.0 和 v14.9.1 是理想的，但任何 v14.8.x 或 v14.10.x 的代理版本也受支持。

更新代理版本#

您应该指定所有需要的值，而不是使用 --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 的行为。

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

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

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

shell
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，那么您可以使用以下命令卸载代理：

shell
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/<agent-name>/config.yaml 中有一个代理配置文件， 这不是有效的 Kubernetes 清单。Flux 无法应用此文件，导致错误。 为了解决问题，您应该将 Flux 指向子目录而不是根目录。