安装选项
- Linux 软件包安装实例
  - 在单个节点上禁用
    - 配置 KAS 侦听 UNIX 套接字
  - 在多个节点上启用
    - 代理服务器节点设置
- Helm Chart 安装实例
Kubernetes API 代理缓存
启用接受代理
故障排除
- 未找到配置文件
- dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused

安装适用于 Kubernetes 的极狐GitLab 代理服务器（KAS）

代理服务器是与极狐GitLab 一起安装的组件，对于管理 Kubernetes 的极狐GitLab 代理是必需的。

KAS 作为首字母缩略词，指的是以前的名称，Kubernetes agent server。

如果您使用私有化部署版极狐GitLab，则必须安装代理服务器或指定外部安装。

安装选项

作为极狐GitLab 管理员，您可以为以下类型的实例安装代理服务器：

Linux 软件包安装实例。
Helm chart 安装实例。

Linux 软件包安装实例

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

在单个节点上禁用

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

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

配置 KAS 侦听 UNIX 套接字

如果您在代理后面使用极狐GitLab，KAS 可能无法正常工作。您可以在单节点安装实例上解决此问题，您可以将 KAS 配置为侦听 UNIX 套接字。

要将 KAS 配置为侦听 UNIX 套接字：

为 KAS 套接字创建目录：

sudo mkdir -p /var/opt/gitlab/gitlab-kas/sockets/

编辑 /etc/gitlab/gitlab.rb：

gitlab_kas['internal_api_listen_network'] = 'unix'
gitlab_kas['internal_api_listen_address'] = '/var/opt/gitlab/gitlab-kas/sockets/internal-api.socket'
gitlab_kas['private_api_listen_network'] = 'unix'
gitlab_kas['private_api_listen_address'] = '/var/opt/gitlab/gitlab-kas/sockets/private-api.socket'
gitlab_kas['env'] = {
  'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
  'OWN_PRIVATE_API_URL' => 'unix:///var/opt/gitlab/gitlab-kas/sockets/private-api.socket'
}

重新配置极狐GitLab。

有关其它配置选项，请参阅 gitlab.rb.template 的 Enable GitLab KAS 部分。

在多个节点上启用

在多个节点上启用代理服务器：

对于每个代理服务器节点，编辑 /etc/gitlab/gitlab.rb：
```
gitlab_kas['enable'] = true
gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155'
gitlab_kas['env'] = {
  'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
  'OWN_PRIVATE_API_URL' => 'grpc://<ip_or_hostname_of_this_host>:8155'
}

gitlab_rails['gitlab_kas_enabled'] = true
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/'
```
您可能无法在 OWN_PRIVATE_API_URL 变量中指定准确的 IP 地址或主机名。比如，kas 主机是否被动态分配了 IP。

在这种情况下，您可以配置 OWN_PRIVATE_API_URL 而不是设置 kas 来动态构建 OWN_PRIVATE_API_URL：
- 注释掉 OWN_PRIVATE_API_URL 以禁用此变量。
- 配置 OWN_PRIVATE_API_CIDR 来指定 kas 应该监听的网络。当开启 kas 时，kas 会寻找宿主机被指派的 IP 地址，并且使用与指定的 CIDR 匹配的地址作为自己的私有 IP 地址。
- 默认情况下，kas 使用 private_api_listen_address 参数中的端口。配置 OWN_PRIVATE_API_PORT 来使用不同的端口。
- 可选。默认情况下，kas 使用 grpc 方案。如果您在私有 API 端点上使用 TLS，请配置 OWN_PRIVATE_API_SCHEME=grpcs。
重新配置极狐GitLab。
可选。如果您使用的是极狐GitLab Rails 和 Sidekiq 节点相互独立的多服务器环境，要在 Sidekiq 节点上启用代理服务器。

代理服务器节点设置

设置	描述
`gitlab_kas['private_api_listen_address']`	代理服务器监听的地址。您可以将其设置为 `0.0.0.0` 或集群中其他节点可访问的 IP 地址。
`gitlab_kas['api_secret_key']`	用于 KAS 和极狐GitLab 之间身份验证的共享密钥。此值必须采用 Base64 编码且长度正好为 32 个字节。
`gitlab_kas['private_api_secret_key']`	用于不同 KAS 实例之间身份验证的共享密钥。此值必须采用 Base64 编码且长度正好为 32 个字节。
`OWN_PRIVATE_API_URL`	KAS 用于服务发现的环境变量。您可以将其设置为正在配置的节点的主机名或 IP 地址。集群中的其他节点必须可以访问该节点。
`OWN_PRIVATE_API_HOST`	用于验证 TLS 证书宿主机名称的可选值。 ¹ 客户端会用服务器的 TLS 证书文件中的宿主机名称和此值进行对比。
`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 安装实例

有关详细信息，请参阅如何使用 KAS chart。

Kubernetes API 代理缓存

引入于极狐GitLab 15.10，功能标志为 kas_user_access 和 kas_user_access_project。默认禁用。

功能标志 kas_user_access 和 kas_user_access_project 启用于极狐GitLab 16.1。

功能标志 kas_user_access 和 kas_user_access_project 移除于极狐GitLab 16.2。

KAS 通过以下任一方式将 Kubernetes API 请求代理到极狐GitLab 代理：

为了使用用户证书进行身份验证，Rails 为极狐GitLab 前端设置了一个缓存。该缓存叫做 _gitlab_kas，它包含一个加密的会话 ID，如 _gitlab_session 缓存。每个请求都必须将 _gitlab_kas 缓存发送到 KAS 代理端点，以对用户进行身份验证和授权。

启用接受代理

引入于极狐GitLab 17.4。

接收代理允许极狐GitLab 能够和那些无法与极狐GitLab 建立网络链接的 Kubernetes 集群进行集成。

要启用接收代理：

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

故障排除

如果您在使用 Kubernetes 代理服务器时遇到问题，请运行以下命令查看服务日志：

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

在 Omnibus GitLab 中，在 /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"}

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

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