安装极狐GitLab 代理服务器（KAS）

安装选项
- 对于 Linux 软件包安装
  - 在单个节点上禁用
  - 在多个节点上开启 KAS
- 对于 GitLab Helm Chart
Kubernetes API 代理 cookie
启用接收代理
故障排除

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

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

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

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

安装选项

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

对于 Linux 软件包安装。
对于 GitLab Helm chart 安装。

对于 Linux 软件包安装

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

在单个节点上禁用

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

编辑 /etc/gitlab/gitlab.rb 文件：
```
gitlab_kas['enable'] = false
```
重新配置极狐 GitLab。

在多个节点上开启 KAS

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

要在多个节点上开启 KAS：

添加通用配置。
添加以下选项之一的配置：
重新配置极狐 GitLab。
（可选）如果使用具有单独极狐 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 的自动配置

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

如果 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：

注释掉通用配置中的 OWN_PRIVATE_API_URL 以关闭此变量。
配置 OWN_PRIVATE_API_CIDR 以指定 KAS 节点监听的网络。启动 KAS 时，它通过选择与指定 CIDR 匹配的主机地址来确定使用哪个私有 IP 地址。
配置 OWN_PRIVATE_API_PORT 以使用不同的端口。默认情况下，KAS 使用 private_api_listen_address 参数中的端口。
如果在私有 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 - 基于侦听器配置的自动配置

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

KAS 节点可以根据 private_api_listen_network 和 private_api_listen_address 设置来确定可用的 IP 地址：

如果 private_api_listen_address 设置为固定 IP 地址和端口号（例如，ip:port），它使用该 IP 地址。
如果 private_api_listen_address 没有 IP 地址（例如，:8155），或者有未指定的 IP 地址（例如，[::]:8155 或 0.0.0.0:8155），KAS 将所有非回环和非链路本地 IP 地址分配给节点。IPv4 和 IPv6 地址根据 private_api_listen_network 的值进行过滤。
如果 private_api_listen_address 是 hostname: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` 时使用哪个方案的可选值。可以是 `grpc` 或 `grpcs`。
`OWN_PRIVATE_API_URL`	KAS 用于服务发现的环境变量。设置为您正在配置的节点的主机名或 IP 地址。节点必须能够被集群中的其他节点访问。
`OWN_PRIVATE_API_HOST`	验证 TLS 证书主机名时使用的可选值。 ¹ 客户端将此值与服务器的 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。可以是完全合格的域名或子域名，² 或极狐 GitLab 外部 URL。 ³ 如果为空，默认为极狐 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。

脚注：

当 OWN_PRIVATE_API_URL 或 OWN_PRIVATE_API_SCHEME 以 grpcs 开头时，启用出站连接的 TLS。
例如，wss://kas.gitlab.example.com/。
例如，wss://gitlab.example.com/-/kubernetes-agent/。

对于 GitLab Helm Chart

请参阅如何使用 GitLab-KAS chart。

在极狐 GitLab 15.10 引入，使用名为 kas_user_access 和 kas_user_access_project 的功能标志。默认禁用。
在极狐 GitLab 16.1 中启用功能标志 kas_user_access 和 kas_user_access_project。
在极狐 GitLab 16.2 中移除功能标志 kas_user_access 和 kas_user_access_project。

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

CI/CD 作业。
极狐 GitLab 用户凭证。

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

启用接收代理

Tier: Ultimate
Offering: GitLab Self-Managed

在极狐 GitLab 17.4 引入。

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

要启用接收代理：

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

故障排除

如果在使用用于 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/"
 }

要应用更改：

重新配置极狐 GitLab：

sudo gitlab-ctl reconfigure

重启代理服务器：

gitlab-ctl restart gitlab-kas

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

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

解决步骤

添加或更新以下配置以增加超时值：

gitlab_kas['client_timeout_seconds'] = "10"

通过重新配置极狐 GitLab 来应用更改：

gitlab-ctl reconfigure

注意

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