{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: 私有化部署
{{< /details >}}
代理服务器是与极狐 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
在多个节点上开启 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 的自动配置
{{< 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:
- 注释掉通用配置中的
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 - 基于侦听器配置的自动配置
{{< history >}}
- 在极狐GitLab 16.5.0 中引入。
- 更新 KAS 以侦听和发布所有非回环 IP 地址,并根据
private_api_listen_network
的值过滤出 IPv4 和 IPv6 地址。
{{< /history >}}
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 证书主机名时使用的可选值。 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。 |
脚注:
- 当
OWN_PRIVATE_API_URL
或OWN_PRIVATE_API_SCHEME
以grpcs
开头时,启用出站连接的 TLS。 - 例如,
wss://kas.gitlab.example.com/
。 - 例如,
wss://gitlab.example.com/-/kubernetes-agent/
。
对于 GitLab Helm Chart
Kubernetes API 代理 cookie
{{< history >}}
- 在极狐 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
。
{{< /history >}}
KAS 将 Kubernetes API 请求代理到极狐 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 集群进行集成。
要启用接收代理:
- 在左侧边栏底部,选择 管理员。
- 选择 设置 > 常规。
- 展开 极狐 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
注意
您可以根据具体需求调整超时值。建议进行测试以确保问题已解决而不会影响系统性能。