| GitLab Docs

Help us learn about your current experience with the documentation. Take the survey.

---
stage: Deploy
group: Environments
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
title: 为 Kubernetes 安装 GitLab 代理服务器 (KAS)
---


      Tier: Free, Premium, Ultimate

      Offering: GitLab Self-Managed


代理服务器是与 GitLab 一同安装的组件，用于管理 [GitLab Kubernetes 代理](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent)。

KAS 是 `Kubernetes agent server`（Kubernetes 代理服务器）的旧称缩写。

GitLab.com 上已预装并启用 Kubernetes 代理服务器，地址为 `wss://kas.gitlab.com`。  
若使用 GitLab 自托管版，代理服务器默认已安装并可用。

## 安装选项

作为 GitLab 管理员，您可控制代理服务器的安装方式：

- [适用于 Linux 包安装](#for-linux-package-installations)
- [适用于 GitLab Helm Chart 安装](#for-gitlab-helm-chart)

### Linux 包安装方式

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

#### 在单节点上禁用

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

1. 编辑 `/etc/gitlab/gitlab.rb`：

   ```ruby
   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字节长_base64编码值>'
gitlab_kas['private_api_secret_key'] = '<32字节长_base64编码值>'

# 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' => '<证书中的服务器名>' # 若需 KAS 间通信使用 TLS，请添加此项。此名称用于验证 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 或域名。
  # 私有 API 端点使用 TLS 时请使用 grpcs://

  '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' # 域名
}

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

若无法在 OWN_PRIVATE_API_URL 中设置精确 IP 或域名（例如 KAS 主机动态分配 IP 和域名），
可配置 OWN_PRIVATE_API_CIDR 让 KAS 基于一个或多个 CIDR动态构建 OWN_PRIVATE_API_URL：

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

为每个 KAS 节点编辑 /etc/gitlab/gitlab.rb 以动态构建 OWN_PRIVATE_API_URL：

在通用配置中注释掉 OWN_PRIVATE_API_URL 以禁用该变量
配置 OWN_PRIVATE_API_CIDR 指定 KAS 节点监听的网络。启动 KAS 时，它会选择匹配指定 CIDR 的主机地址
配置 OWN_PRIVATE_API_PORT 使用不同端口。默认使用 private_api_listen_address 参数中的端口
若私有 API 端点使用 TLS，配置 OWN_PRIVATE_API_SCHEME=grpcs。默认使用 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', # 多 CIDR 示例

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

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

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）。IPv4 设为 `tcp4`，IPv6 设为 `tcp6`。
`gitlab_kas['private_api_listen_address']`	KAS 监听地址。设为 `0.0.0.0:8155` 或集群内其他节点可访问的 IP 和端口。
`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。

KAS 通过以下方式代理 Kubernetes API 请求到 GitLab Kubernetes 代理：

使用用户凭据认证时，Rails 会为 GitLab 前端设置一个名为 _gitlab_kas 的 Cookie。
该 Cookie 包含加密的会话 ID，类似于 _gitlab_session Cookie。
每次请求 KAS 代理端点时，必须发送 _gitlab_kas Cookie 以认证和授权用户。

启用接收式代理

Tier: Ultimate
Offering: GitLab Self-Managed

接收式代理允许 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"}

解决方案：将内部 CA 的公共证书安装到 /etc/gitlab/trusted-certs 目录。

或配置 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 in Clusters::Agents::NotifyGitPushWorker`

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

解决步骤

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

gitlab_kas['client_timeout_seconds'] = "10"

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

sudo gitlab-ctl reconfigure

注意

可根据实际需求调整超时值。建议测试以确保问题解决且不影响系统性能。