{{< details >}}

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

{{< /details >}}

代理服务器是与极狐 GitLab 一起安装的组件。它用于管理 GitLab agent for Kubernetes

KAS 的缩写指的是以前的名称,Kubernetes agent server

用于 Kubernetes 的代理服务器已安装并可在 JihuLab.com 上使用,地址为 wss://kas.gitlab.com。如果使用极狐 GitLab 私有化部署,默认情况下代理服务器已安装并可用。

安装选项

作为极狐 GitLab 管理员,您可以控制代理服务器的安装:

  1. 对于 Linux 软件包安装
  2. 对于 GitLab Helm chart 安装

对于 Linux 软件包安装

Linux 软件包安装的代理服务器可以在单个节点或多个节点上启用。默认情况下,代理服务器已启用,并可在 ws://gitlab.example.com/-/kubernetes-agent/ 上使用。

在单个节点上禁用

要在单个节点上禁用代理服务器:

  1. 编辑 /etc/gitlab/gitlab.rb 文件:

    gitlab_kas['enable'] = false
    
  2. 重新配置极狐 GitLab

在多个节点上开启 KAS

KAS 实例通过在 Redis 中一个知名位置注册其私有地址进行通信。每个 KAS 必须配置以显示其私有地址详细信息,以便其他实例可以访问它。

要在多个节点上开启 KAS:

  1. 添加通用配置
  2. 添加以下选项之一的配置:

  3. 重新配置极狐 GitLab
  4. (可选)如果使用具有单独极狐 GitLab Rails 和 Sidekiq 节点的多服务器环境,请在 Sidekiq 节点上启用 KAS。

通用配置

对于每个 KAS 节点,编辑 /etc/gitlab/gitlab.rb 文件并添加以下配置:

gitlab_kas_external_url 'wss://kas.gitlab.example.com/'

gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>'

# private_api_listen_address 示例,选择一个:

gitlab_kas['private_api_listen_address'] = 'A.B.C.D:8155' # 在特定 IPv4 上侦听。每个节点必须使用自己唯一的 IP。
# gitlab_kas['private_api_listen_address'] = '[A:B:C::D]:8155' # 在特定 IPv6 上侦听。每个节点必须使用自己唯一的 IP。
# gitlab_kas['private_api_listen_address'] = 'kas-N.gitlab.example.com:8155' # 在 DNS 名称解析到的所有 IPv4 和 IPv6 接口上侦听。每个节点必须使用自己唯一的域名。
# gitlab_kas['private_api_listen_address'] = ':8155' # 在所有 IPv4 和 IPv6 接口上侦听。
# gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155' # 在所有 IPv4 接口上侦听。
# gitlab_kas['private_api_listen_address'] = '[::]:8155' # 在所有 IPv6 接口上侦听。

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_HOST' => '<server-name-from-cert>' # 如果您希望使用 TLS 进行 KAS->KAS 通信,请添加。此名称用于验证 TLS 证书主机名,而不是目标 KAS 的 URL 中的主机。
  'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
}

gitlab_rails['gitlab_kas_external_url'] = 'wss://gitlab.example.com/-/kubernetes-agent/'
gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com'
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://gitlab.example.com/-/kubernetes-agent/k8s-proxy/'

不要private_api_listen_address 设置为侦听内部地址,例如:

  • localhost
  • 回环 IP 地址,如 127.0.0.1::1
  • UNIX 套接字

其他 KAS 节点无法访问这些地址。

对于单节点配置,可以将 private_api_listen_address 设置为侦听内部地址。

选项 1 - 明确手动配置

对于每个 KAS 节点,编辑 /etc/gitlab/gitlab.rb 文件并显式设置 OWN_PRIVATE_API_URL 环境变量:

gitlab_kas['env'] = {
  # OWN_PRIVATE_API_URL 示例,选择一个。每个节点必须使用自己唯一的 IP 或 DNS 名称。
  # 使用 grpcs:// 时,在私有 API 端点上使用 TLS。

  'OWN_PRIVATE_API_URL' => 'grpc://A.B.C.D:8155' # IPv4
  # 'OWN_PRIVATE_API_URL' => 'grpcs://A.B.C.D:8155' # IPv4 + TLS
  # 'OWN_PRIVATE_API_URL' => 'grpc://[A:B:C::D]:8155' # IPv6
  # 'OWN_PRIVATE_API_URL' => 'grpc://kas-N-private-api.gitlab.example.com:8155' # DNS 名称
}

选项 2 - 基于 CIDR 的自动配置

{{< history >}}

  • 在极狐GitLab 16.5.0 中引入。
  • 在极狐GitLab 17.8.1 中为 OWN_PRIVATE_API_CIDR 添加了多个 CIDR 支持。

{{< /history >}}

如果 KAS 主机被动态分配 IP 地址和主机名,您可能无法在 OWN_PRIVATE_API_URL 变量中设置确切的 IP 地址或主机名。

如果无法设置确切的 IP 地址或主机名,可以配置 OWN_PRIVATE_API_CIDR 来动态构建 KAS 的 OWN_PRIVATE_API_URL,基于一个或多个 CIDR:

此方法允许每个 KAS 节点使用静态配置,只要 CIDR 不变即可正常工作。

对于每个 KAS 节点,编辑 /etc/gitlab/gitlab.rb 文件以动态构建 OWN_PRIVATE_API_URL URL:

  1. 注释掉通用配置中的 OWN_PRIVATE_API_URL 以关闭此变量。
  2. 配置 OWN_PRIVATE_API_CIDR 以指定 KAS 节点监听的网络。 启动 KAS 时,它通过选择与指定 CIDR 匹配的主机地址来确定使用哪个私有 IP 地址。
  3. 配置 OWN_PRIVATE_API_PORT 以使用不同的端口。默认情况下,KAS 使用 private_api_listen_address 参数中的端口。
  4. 如果在私有 API 端点上使用 TLS,请配置 OWN_PRIVATE_API_SCHEME=grpcs。默认情况下,KAS 使用 grpc 方案。
gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8', # IPv4 示例
  # 'OWN_PRIVATE_API_CIDR' => '2001:db8:8a2e:370::7334/64', # IPv6 示例
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8,2001:db8:8a2e:370::7334/64', # 多个 CIRDs 示例

  # 'OWN_PRIVATE_API_PORT' => '8155',
  # 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}

选项 3 - 基于侦听器配置的自动配置

{{< history >}}

  • 在极狐GitLab 16.5.0 中引入。
  • 更新 KAS 以侦听和发布所有非回环 IP 地址,并根据 private_api_listen_network 的值过滤出 IPv4 和 IPv6 地址。

{{< /history >}}

KAS 节点可以根据 private_api_listen_networkprivate_api_listen_address 设置来确定可用的 IP 地址:

  • 如果 private_api_listen_address 设置为固定 IP 地址和端口号(例如,ip:port),它使用该 IP 地址。
  • 如果 private_api_listen_address 没有 IP 地址(例如,:8155),或者有未指定的 IP 地址(例如,[::]:81550.0.0.0:8155),KAS 将所有非回环和非链路本地 IP 地址分配给节点。IPv4 和 IPv6 地址根据 private_api_listen_network 的值进行过滤。
  • 如果 private_api_listen_addresshostname:PORT(例如,kas-N-private-api.gitlab.example.com:8155),KAS 解析 DNS 名称并将所有 IP 地址分配给节点。在这种模式下,KAS 仅侦听第一个 IP 地址(此行为由 Go 标准库 定义)。IPv4 和 IPv6 地址根据 private_api_listen_network 的值进行过滤。

在所有 IP 地址上暴露 KAS 的私有 API 地址之前,请确保此操作不会与组织的安全策略冲突。私有 API 端点要求所有请求都具有有效的认证令牌。

对于每个 KAS 节点,编辑 /etc/gitlab/gitlab.rb 文件:

示例 1. 监听所有 IPv4 和 IPv6 接口:

# gitlab_kas['private_api_listen_network'] = 'tcp' # 这是默认值,无需设置。
gitlab_kas['private_api_listen_address'] = ':8155' # 监听所有 IPv4 和 IPv6 接口

示例 2. 监听所有 IPv4 接口:

gitlab_kas['private_api_listen_network'] = 'tcp4'
gitlab_kas['private_api_listen_address'] = ':8155'

示例 3. 监听所有 IPv6 接口:

gitlab_kas['private_api_listen_network'] = 'tcp6'
gitlab_kas['private_api_listen_address'] = ':8155'

您可以使用环境变量覆盖构建 OWN_PRIVATE_API_URL 的方案和端口:

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_PORT' => '8155',
  # 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}

代理服务器节点设置
设置 描述
gitlab_kas['private_api_listen_network'] KAS 监听的网络系列。默认为 tcp,适用于 IPv4 和 IPv6 网络。设置为 tcp4 适用于 IPv4 或 tcp6 适用于 IPv6。
gitlab_kas['private_api_listen_address'] KAS 监听的地址。设置为 0.0.0.0:8155 或集群中其他节点可访问的 IP:PORT。
gitlab_kas['api_secret_key'] 用于 KAS 和极狐 GitLab 之间的身份验证的共享密钥。该值必须是 Base64 编码且长度恰好为 32 字节。
gitlab_kas['private_api_secret_key'] 用于不同 KAS 实例之间的身份验证的共享密钥。该值必须是 Base64 编码且长度恰好为 32 字节。
OWN_PRIVATE_API_SCHEME 用于指定构建 OWN_PRIVATE_API_URL 时使用哪个方案的可选值。可以是 grpcgrpcs
OWN_PRIVATE_API_URL KAS 用于服务发现的环境变量。设置为您正在配置的节点的主机名或 IP 地址。节点必须能够被集群中的其他节点访问。
OWN_PRIVATE_API_HOST 验证 TLS 证书主机名时使用的可选值。 1 客户端将此值与服务器的 TLS 证书文件中的主机名进行比较。
OWN_PRIVATE_API_PORT 用于指定构建 OWN_PRIVATE_API_URL 时使用哪个端口的可选值。
OWN_PRIVATE_API_CIDR 用于指定构建 OWN_PRIVATE_API_URL 时使用哪些可用网络的 IP 地址的可选值。
gitlab_kas['client_timeout_seconds'] 客户端连接到 KAS 的超时时间。
gitlab_kas_external_url 集群中 agentk 的用户访问 URL。可以是完全合格的域名或子域名,2 或极狐 GitLab 外部 URL。 3 如果为空,默认为极狐 GitLab 外部 URL。
gitlab_rails['gitlab_kas_external_url'] 集群中 agentk 的用户访问 URL。如果为空,默认为 gitlab_kas_external_url
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] Kubernetes API 代理的用户访问 URL。如果为空,默认为基于 gitlab_kas_external_url 的 URL。
gitlab_rails['gitlab_kas_internal_url'] 极狐 GitLab 后端用于与 KAS 通信的内部 URL。

脚注:

  1. OWN_PRIVATE_API_URLOWN_PRIVATE_API_SCHEMEgrpcs 开头时,启用出站连接的 TLS。
  2. 例如,wss://kas.gitlab.example.com/
  3. 例如,wss://gitlab.example.com/-/kubernetes-agent/

对于 GitLab Helm Chart

请参阅 如何使用 GitLab-KAS chart

{{< history >}}

  • 在极狐 GitLab 15.10 引入,使用名为 kas_user_accesskas_user_access_project功能标志。默认禁用。
  • 在极狐 GitLab 16.1 中启用功能标志 kas_user_accesskas_user_access_project
  • 在极狐 GitLab 16.2 中移除功能标志 kas_user_accesskas_user_access_project

{{< /history >}}

KAS 将 Kubernetes API 请求代理到极狐 GitLab 代理,使用以下方式之一:

  1. CI/CD 作业
  2. 极狐 GitLab 用户凭证

要使用用户凭证进行身份验证,Rails 会为极狐 GitLab 前端设置一个 cookie。此 cookie 称为 _gitlab_kas,其中包含加密的会话 ID,就像 _gitlab_session cookie。必须将 _gitlab_kas cookie 发送到 KAS 代理端点以进行用户身份验证和授权。

启用接收代理

{{< details >}}

  • Tier: Ultimate
  • Offering: GitLab Self-Managed

{{< /details >}}

{{< history >}}

  • 在极狐 GitLab 17.4 引入。

{{< /history >}}

接收代理允许极狐 GitLab 与无法建立到极狐 GitLab 实例的网络连接但可以由极狐 GitLab 连接的 Kubernetes 集群进行集成。

要启用接收代理:

  1. 在左侧边栏底部,选择 管理员
  2. 选择 设置 > 常规
  3. 展开 极狐 GitLab Kubernetes 代理
  4. 打开 启用接收模式 开关。

故障排除

如果在使用用于 Kubernetes 的代理服务器时遇到问题,请通过运行以下命令查看服务日志:

kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>

在 Linux 软件包安装中,可以在 /var/log/gitlab/gitlab-kas/ 中找到日志。

您还可以排除个别代理的问题

配置文件未找到

如果收到以下错误信息:

time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\

路径不正确,可能是以下原因之一:

  • 注册代理的仓库。
  • 代理配置文件。

要解决此问题,请确保路径正确。

dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused

如果您正在运行极狐 GitLab 私有化部署,并且:

  • 实例未运行在 SSL 终止代理后面。
  • 实例本身没有在极狐 GitLab 实例上配置 HTTPS。
  • 实例的主机名在本地解析为其内部 IP 地址。

当代理服务器尝试连接到极狐 GitLab API 时,可能会发生以下错误:

{"level":"error","time":"2021-08-16T14:56:47.289Z","msg":"GetAgentInfo()","correlation_id":"01FD7QE35RXXXX8R47WZFBAXTN","grpc_service":"gitlab.agent.reverse_tunnel.rpc.ReverseTunnel","grpc_method":"Connect","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": dial tcp 172.17.0.4:443: connect: connection refused"}

要解决 Linux 软件包安装中的此问题,请在 /etc/gitlab/gitlab.rb 中设置以下参数。将 gitlab.example.com 替换为您的极狐 GitLab 实例的主机名:

gitlab_kas['gitlab_address'] = 'http://gitlab.example.com'

错误:x509: certificate signed by unknown authority

如果在尝试访问极狐 GitLab URL 时遇到此错误,则表示它不信任极狐 GitLab 证书。

您可能会在极狐 GitLab 应用服务器的 KAS 日志中看到类似的错误:

{"level":"error","time":"2023-03-07T20:19:48.151Z","msg":"AgentInfo()","grpc_service":"gitlab.agent.agent_configuration.rpc.AgentConfiguration","grpc_method":"GetConfiguration","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": x509: certificate signed by unknown authority"}

要解决此错误,请在 /etc/gitlab/trusted-certs 目录中安装内部 CA 的公用证书。

或者,您可以配置 KAS 从自定义目录读取证书。为此,请在 /etc/gitlab/gitlab.rb 文件中添加以下配置:

gitlab_kas['env'] = {
   'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/"
 }

要应用更改:

  1. 重新配置极狐 GitLab:
sudo gitlab-ctl reconfigure
  1. 重启代理服务器:
gitlab-ctl restart gitlab-kas

GRPC::DeadlineExceeded 在 Clusters::Agents::NotifyGitPushWorker 中

此错误可能发生在客户端在默认超时时间(5 秒)内没有收到响应时。要解决此问题,可以通过修改 /etc/gitlab/gitlab.rb 配置文件来增加客户端超时时间。

解决步骤

  1. 添加或更新以下配置以增加超时值:
gitlab_kas['client_timeout_seconds'] = "10"
  1. 通过重新配置极狐 GitLab 来应用更改:
gitlab-ctl reconfigure

注意

您可以根据具体需求调整超时值。建议进行测试以确保问题已解决而不会影响系统性能。