极狐 GitLab

设置 GitLab Orbit

Tier: 专业版，旗舰版

Offering: 私有化部署

GitLab Orbit 作为 Helm release 与您的极狐GitLab 实例一起运行。

先决条件：

  • 数据复制正在运行，并且数据行已到达数据湖。
  • 一个 ClickHouse 管理员账号。
  • 极狐GitLab 的管理员访问权限。

请按以下顺序设置 GitLab Orbit：

  1. 在极狐GitLab 中开启 GitLab Orbit。
  2. 创建密钥。
  3. 安装 GitLab Orbit。
  4. 为群组开启索引。

在极狐GitLab 中开启 GitLab Orbit#

极狐GitLab 和 GitLab Orbit 使用一个共享密钥进行认证，该密钥由极狐GitLab 持有。请先在极狐GitLab 中开启 GitLab Orbit，以便在将密钥复制到集群之前该密钥已存在。

极狐GitLab 连接到端口 50054 上的 gRPC 端点，以 tls:// 开头的端点使用 TLS。如需改用服务网格进行加密，请参阅使用明文连接。

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

    ruby
    gitlab_rails['orbit_enabled'] = true
gitlab_rails['orbit_grpc_endpoint'] = 'tls://orbit.example.com:50054'

  2. 重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure

  3. 复制极狐GitLab 生成的密钥。请勿重新编码或裁剪该密钥：

    shell
    sudo cat /var/opt/gitlab/gitlab-rails/etc/gitlab_knowledge_graph_secret

如果您运行多个 Rails 节点，或者使用 Ansible 等工具替换 /etc/gitlab/gitlab-secrets.json， 请将 gitlab_rails['orbit_secret'] 设置为 gitlab.rb中的密钥。 否则，重新配置可能会生成新密钥，导致 GitLab Orbit 拒绝所有请求。

在您安装 GitLab Orbit 之前，极狐GitLab 会持续记录连接错误。

创建密钥#

GitLab Orbit 从 Kubernetes 密钥中读取极狐GitLab 密钥和 ClickHouse 密码。 chart 的设置 hook 使用管理员密码创建 GitLab Orbit 用户。

要创建密钥：

  1. 创建命名空间：

    shell
    kubectl create namespace gitlab-orbit

  2. 创建密钥：

    shell
    1kubectl -n gitlab-orbit create secret generic orbit-secrets \
2  --from-literal=gitlab-jwt-verifying-key='<gitlab_key>' \
3  --from-literal=gitlab-jwt-signing-key='<gitlab_key>' \
4  --from-literal=admin-password='<clickhouse_admin_password>' \
5  --from-literal=datalake-password='<siphon_reader_password>' \
6  --from-literal=graph-password='<writer_password>' \
7  --from-literal=graph-read-password='<reader_password>'

    替换以下值：

    • <gitlab_key>：来自在极狐GitLab 中开启 GitLab Orbit的密钥。
    • <clickhouse_admin_password>：ClickHouse 管理员账号的密码。
    • <siphon_reader_password>、<writer_password> 和 <reader_password>：为 gkg_siphon_reader、gkg_writer 和 gkg_reader 用户设置的新密码。

  3. 如果 Web 服务器终止 TLS，请为 gRPC 端点创建 TLS 密钥：

    shell
    kubectl -n gitlab-orbit create secret tls orbit-webserver-tls --cert=<cert_file> --key=<key_file>

在生产环境中，请从您的密钥管理器同步密钥，例如使用 External Secrets Operator。pod 在启动时读取密钥，因此更改后请重启它们：

shell
kubectl -n gitlab-orbit rollout restart deployment

安装 GitLab Orbit#

要安装 GitLab Orbit：

  1. 将以下内容保存为 orbit-values.yaml：

    yaml
    1secrets:
2  gitlabJwtVerifyingKey: {secretName: orbit-secrets}
3  gitlabJwtSigningKey: {secretName: orbit-secrets}
4  datalakePassword: {secretName: orbit-secrets}
5  graphPassword: {secretName: orbit-secrets}
6  graphReadPassword: {secretName: orbit-secrets}
7
8clickhouseSetup:
9  enabled: true
10  adminSecret:
11    secretName: orbit-secrets
12
13clickhouse:
14  datalake:
15    host: <clickhouse_host>
16    database: gitlab_clickhouse_main_production
17    user: gkg_siphon_reader
18  graph:
19    host: <clickhouse_host>
20    database: orbit
21    user: gkg_writer
22    readUser: gkg_reader
23
24dispatcher:
25  enabled: true
26
27nats:
28  url: nats://nats.nats.svc.cluster.local:4222
29
30gitlab:
31  # The GitLab address the cluster reaches, such as an internal address or load balancer.
32  # If it differs from the certificate host name, set resolveHost. See Networking.
33  baseUrl: https://gitlab.example.com
34  # resolveHost: gitlab.internal
35
36tls:
37  enabled: true
38  existingSecret: orbit-webserver-tls

    将 <clickhouse_host> 替换为您的 ClickHouse 服务器的主机名。

  2. 安装 chart：

    shell
    helm upgrade --install orbit oci://registry.gitlab.com/gitlab-org/orbit/orbit-helm-charts/orbit \
  --namespace gitlab-orbit --values orbit-values.yaml

  3. 确认 Web 服务器、索引器和调度器 pod 均处于 Running 状态：

    shell
    kubectl -n gitlab-orbit get pods

请根据您的环境调整这些值：

  • 对于通过 TLS 连接的 ClickHouse（例如 ClickHouse Cloud），请为两个 ClickHouse 连接都添加 httpPort: 8443 和 ssl: true。
  • 如果 ClickHouse 证书来自您自己的 CA，请将该 CA 证书添加到 trust.extraCAs。
  • 如果由负载均衡器或服务网格处理 TLS，请移除 tls 块。
  • 如果 NATS 需要密码，请设置 nats.username，将 nats-password 添加到密钥中，并将 natsPassword 添加到 secrets，同时开启 nats.tls，以免密码以明文形式在网络上传输。
  • Snowplow 分析默认关闭。要开启它，请设置 analytics.enabled: true。

有关 TLS、私有证书颁发机构、NATS TLS 和明文连接的信息，请参阅 GitLab Orbit 的网络配置。 有关所有值及其默认值，请参阅 GitLab Orbit Helm chart。 有关 pod 规格，请参阅 GitLab Orbit 容量规划。

为群组开启索引#

GitLab Orbit 为顶级群组及其子群组和项目建立索引。

要为群组开启索引：

  1. 在右上角，选择管理员。
  2. 前往 /admin/orbit 上的 GitLab Orbit 配置页面。
  3. 在顶级群组下，找到您的群组并选择开启 GitLab Orbit。
  4. 确认。

要为所有顶级群组建立索引，请开启自动为所有顶级群组开启 GitLab Orbit。

您也可以通过 API 开启索引：

shell
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/knowledge_graph/namespaces/<group_id>"

首次索引需要几分钟到几小时不等。每小时执行一次的扫描会补上索引遗漏的任何数据。

验证安装#

为您已开启索引的群组中的项目查询图谱。该查询使用 GQL，支持的极狐GitLab 版本默认接受该查询。

要验证安装：

  1. 将查询保存为 query.gql：

    gql
    MATCH (p:Project) WHERE p.full_path STARTS WITH 'your-group/' RETURN p.name, p.full_path LIMIT 10

    将 your-group/ 替换为您群组的完整路径，并在其后加上 /。

  2. 发送查询：

    shell
    jq -Rs '{query: ., response_format: "raw"}' query.gql | curl --request POST \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data @- \
  --url "https://gitlab.example.com/api/v4/orbit/query"

    将 <your_access_token> 替换为您的个人访问令牌。

首次索引完成后，该查询会返回数据行。在此之前，pod 状态和 /-/readiness 端点就已通过检查，因此它们不能确认索引已完成。

升级 GitLab Orbit#

升级会复用图谱数据库。当某个版本更改了 schema 时，GitLab Orbit 会在当前活动版本旁边构建新版本，并在索引完成后切换。请为图谱的第二份副本规划 ClickHouse 磁盘空间。

要升级 GitLab Orbit：

  1. 运行安装 GitLab Orbit中的 helm upgrade 命令。
  2. 运行验证安装中的查询。

升级极狐GitLab#

升级极狐GitLab 时，请同时升级 Siphon 和 GitLab Orbit。

要升级极狐GitLab：

  1. 升级极狐GitLab。

  2. 在 siphon-values.yaml中，将 global.gitlabVersion 设置为新的极狐GitLab 版本，然后升级 Siphon。

  3. 升级 GitLab Orbit。

  4. 在 Linux 软件包上，确认极狐GitLab 中的密钥与 Kubernetes 密钥中存储的值一致：

    shell
    sudo cat /var/opt/gitlab/gitlab-rails/etc/gitlab_knowledge_graph_secret
    shell
    kubectl -n gitlab-orbit get secret orbit-secrets -o jsonpath='{.data.gitlab-jwt-verifying-key}' | base64 -d