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

Cloud Connector：配置

GitLab Rails 实例通过 Cloud Connector Service Access Token 访问后端服务：

此令牌会从 CustomersDot 每日同步到 GitLab 实例，并存储在实例的本地数据库中。
对于 GitLab.com，我们不需要此步骤；相反，我们为每个请求颁发短期令牌。

Cloud Connector JWT 包含一个自定义声明，代表访问权限列表，定义了此令牌对哪些功能或单元原语有效。

单元原语和配置

根据 Architecture Decision Record (ADR) 003，单元原语的配置由 gitlab-cloud-connector 库维护。该库作为所有 Cloud Connector 配置的单一事实来源（SSoT），同时提供 Ruby gem 和 Python 包两种形式。

配置格式和结构

gitlab-cloud-connector 中的配置遵循以下结构：

config
  ├─ unit_primitives/
  │  ├─ duo_chat.yml
  │  └─ ...
  ├─ backend_services/
  │  ├─ ai_gateway.yml
  │  └─ ...
  ├─ add_ons/
  │  ├─ duo_pro.yml
  │  └─ ...
  ├─ services/
  │  ├─ duo_chat.yml
  │  └─ ...
  └─ license_types/
     ├─ premium.yml
     └─ ...

单元原语配置

每个单元原语都有一个 YAML 文件。它包含有关此单元原语如何与附加组件和许可证类型捆绑的信息，以及其他元数据。每个单元原语的配置遵循以下模式。

必填字段

字段	类型	描述
`name`	string	单元原语名称，采用 `snake_case` 格式（小写字母、数字、下划线）。应遵循 `$VERB_$NOUN` 模式（例如 `explain_vulnerability`）。
`description`	string	单元原语目的和功能的描述。
`group`	string	拥有该单元原语的工程组（例如 “group::duo chat”）。
`feature_category`	string	功能类别分类（参见 categories）。
`documentation_url`	string	单元原语文档的 URL。

可选字段

字段	类型	描述
`milestone`	string	引入该单元原语的 GitLab 里程碑。
`introduced_by_url`	string	引入该单元原语的合并请求 URL。
`unit_primitive_issue_url`	string	提出引入该单元原语的问题 URL。
`deprecated_by_url`	string	弃用该单元原语的合并请求 URL。
`deprecation_message`	string	弃用上下文和原因的解释。
`cut_off_date`	datetime	免费访问结束时的 UTC 时间戳（如果适用）。注意：如果未定义截止日期，则不会强制执行 `add_ons` 元素，该功能保持免费访问。
`min_gitlab_version`	string	所需的最低 GitLab 版本（例如 `17.8`）。
`min_gitlab_version_for_free_access`	string	免费访问期间的最低版本（例如 `17.8`）。

访问控制字段

字段	类型	描述
`license_types`	array[string]	可以访问此原语的 GitLab 许可证类型。可能的值必须与 `config/license_types` 下相应文件中的 name 字段匹配（例如 `premium`）。
`backend_services`	array[string]	托管此原语的后端服务。可能的值必须与 `config/backend_services` 下相应文件中的 name 字段匹配（例如 `ai_gateway`）。
`add_ons`	array[string]	包含此原语的附加产品。要访问此功能，必须拥有所有列出的附加产品。可能的值必须与 `config/add_ons` 下相应文件中的 name 字段匹配（例如 `duo_pro`）。注意：仅在定义了 `cut_off_date` 后才强制执行此字段，之后功能将移出免费访问或测试版状态。

示例单元原语配置：

# config/unit_primitives/new_feature.yml
---
name: new_feature
description: 新功能的描述
cut_off_date: 2024-10-17T00:00:00+00:00  # 可选；付费功能始终需要设置
min_gitlab_version: '16.9'
min_gitlab_version_for_free_access: '16.8'
group: group::your_group
feature_category: your_category
documentation_url: https://docs.gitlab.com/ee/path/to/docs
backend_services:
  - ai_gateway
add_ons:
  - duo_pro
  - duo_enterprise
license_types:
  - premium
  - ultimate

根据此定义，该功能：

描述了由"Your Group"拥有的"New Feature"。
从 GitLab 16.8 开始以测试版（免费）形式提供。
仅在 GitLab 16.9 或更高版本中通过付费附加产品提供。
在 2024 年 10 月 17 日 UTC 午夜时从免费访问转为付费访问。在此之后，您必须拥有 Duo Pro 或 Duo Enterprise，以及 Premium 或 Ultimate 订阅。
如果上述条件成立，Cloud Connector 令牌将在其 scopes 声明中携带此功能，允许后端服务相应地验证访问权限。
此功能仅适用于对 AI 网关的请求。当令牌附加到发送到其他后端服务的请求时， scopes 中不需要存在相应的条目。

不设置任何 cut_off_date 意味着功能保持免费可用，无论定义了哪些 add_ons。

向后兼容性

为了支持运行旧版 GitLab 并使用旧版 legacy structure 的客户的向后兼容性，我们提供了从新格式到旧格式的映射，以及即将弃用的"service"抽象。

服务配置

字段	类型	描述
`name`	string	服务的唯一名称，由小写字母数字字符和下划线组成。
`basic_unit_primitive`	string	代表关键配置值（如 `cut_off_date` 和 `min_gitlab_version`）的最基本单元原语。如果未设置，则使用 `unit_primitives` 列表中的第一个单元原语。用于跨服务派生这些共享属性。
`gitlab_realm`	array[string]	服务可用的环境数组。可能的值：`gitlab-com`、`self-managed`。
`description`	string	服务的简要描述。
`unit_primitives`	array[string]	与服务关联的单元原语数组。

新服务映射配置示例：

# config/services/duo_chat.yml
---
name: duo_chat
basic_unit_primitive: duo_chat
gitlab_realm:
  - gitlab-com
  - self-managed
unit_primitives:
  - ask_build
  - ask_commit
  - ask_epic
  - ask_issue
  - ask_merge_request
  - documentation_search
  - duo_chat
  - explain_code
  - fix_code
  - include_dependency_context
  - include_file_context
  - include_issue_context
  - include_local_git_context
  - include_merge_request_context
  - include_snippet_context
  - include_terminal_context
  - include_repository_context
  - refactor_code
  - write_tests

旧版结构

有关付费功能如何捆绑到 GitLab 版本和附加产品的信息配置并存储在 YAML 文件中：

services:
  code_suggestions:
    backend: 'gitlab-ai-gateway'
    cut_off_date: 2024-02-15 00:00:00 UTC
    min_gitlab_version: '16.8'
    bundled_with:
      duo_pro:
        unit_primitives:
          - code_suggestions
  duo_chat:
    backend: 'gitlab-ai-gateway'
    min_gitlab_version_for_beta: '16.8'
    min_gitlab_version: '16.9'
    bundled_with:
      duo_pro:
        unit_primitives:
          - duo_chat
          - documentation_search

字段	类型	描述
`unit_primitives`	array[string]	权限或访问范围可以控制的最小逻辑功能。应遵循 `$VERB_$NOUN` 命名模式（例如 `explain_vulnerability`）。
`service`	string	提供该功能的服务名称。可以是独立的，也可以是现有服务的一部分（例如 `duo_chat`）。
`bundled_with`	object	包含此功能的附加产品映射。一个功能可以与多个附加产品捆绑（例如 `duo_pro`、`duo_enterprise`）。
`cut_off_date`	datetime	免费访问结束时的 UTC 时间戳。如果未设置，功能保持免费。
`min_gitlab_version`	string	所需的最低 GitLab 版本（例如 `17.8`）。如果未设置，适用于所有版本。
`min_gitlab_version_for_free_access`	string	免费访问期间的最低版本（例如 `17.8`）。如果未设置，适用于所有版本。
`backend`	string	托管此功能的后端服务名称，用作令牌受众声明（例如 `gitlab-ai-gateway`）。