• 列出项目的代理
• 获取代理详细信息
• 注册项目代理
• 删除注册代理
• 列出代理的令牌
• 获取单个代理令牌
• 创建代理令牌
• 撤回代理令牌
• Receptive agents
  • List URL configurations for a receptive agent
  • Get a single agent URL configuration
  • 创建大理的 URL 配置
  • 删除代理的 URL 配置

代理 API

• 引入于极狐GitLab 14.10。

• 代理令牌 API 引入于极狐GitLab 15.0。

使用代理 API 与 Kubernetes 的极狐GitLab 代理一起工作。

列出项目的代理

返回项目注册的代理列表。

您必须至少具有开发者的角色才能使用这个端点。

GET /projects/:id/cluster_agents

参数：

响应：

响应是包含以下字段的代理列表：

请求示例：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents"

响应示例：

[
  {
    "id": 1,
    "name": "agent-1",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  },
  {
    "id": 2,
    "name": "agent-2",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  }
]

获取代理详细信息

获取单个代理的详细信息。

您必须至少具有开发者的角色才能使用这个端点。

GET /projects/:id/cluster_agents/:agent_id

参数：

响应：

响应是包含以下字段的单个代理：

请求示例：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1"

响应示例：

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

注册项目代理

注册项目代理。

您必须至少具有维护者的角色才能使用这个端点。

POST /projects/:id/cluster_agents

参数：

响应：

响应是包含以下字段的新代理：

请求示例：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents" \
    -H "Content-Type:application/json" \
    -X POST --data '{"name":"some-agent"}'

响应示例：

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

删除注册代理

删除现存的代理注册。

您必须至少具有维护者的角色才能使用这个端点。

DELETE /projects/:id/cluster_agents/:agent_id

参数：

| 参数 | 类型 | 是否必需 | 描述 | |——–|——————-|——|—————————————————————| | id | integer or string | yes | 授权用户维护的 ID 或 URL 编码的项目路径 | | agent_id | integer | yes | 代理 ID | 请求示例：

curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1

列出代理的令牌

• 引入于极狐GitLab 15.0。

返回代理的活跃令牌的列表。

您必须至少具有开发者的角色才能使用这个端点。

GET /projects/:id/cluster_agents/:agent_id/tokens

支持的参数：

响应：

响应是包含以下字段的令牌列表：

请求示例：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens"

响应示例：

[
  {
    "id": 1,
    "name": "abcd",
    "description": "Some token",
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  },
  {
    "id": 2,
    "name": "foobar",
    "description": null,
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  }
]

获取单个代理令牌

引入于极狐GitLab 15.0。

获取单个代理令牌。

您必须至少具有开发者的角色才能使用这个端点。

如果代理令牌已被撤销，则返回 404。

GET /projects/:id/cluster_agents/:agent_id/tokens/:token_id

支持的参数：

响应：

响应是包含以下字段的单个令牌：

请求示例：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/token/1"

响应示例：

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null
}

创建代理令牌

• 引入于极狐GitLab 15.0。
• 双令牌限制引入于极狐GitLab 16.1，功能标志为 cluster_agents_limit_tokens_created。
• 双令牌限制普遍可用于极狐GitLab 16.2。移除 cluster_agents_limit_tokens_created 功能标志。

为代理创建新的令牌。

您必须至少具有维护者的角色才能使用这个端点。

代理一次只能拥有两个活动令牌。

POST /projects/:id/cluster_agents/:agent_id/tokens

支持的参数：

响应：

响应是包含以下字段的新令牌：

请求示例：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens" \
    -H "Content-Type:application/json" \
    -X POST --data '{"name":"some-token"}'

响应示例：

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null,
  "token": "qeY8UVRisx9y3Loxo1scLxFuRxYcgeX3sxsdrpP_fR3Loq4xyg"
}

撤回代理令牌

引入于极狐GitLab 15.0。

撤回代理令牌。

您必须至少具有维护者的角色才能使用这个端点。

DELETE /projects/:id/cluster_agents/:agent_id/tokens/:token_id

支持的参数：

| 参数 | 类型 | 是否必需 | 描述 | |————|——————-|——|—————————————————————| | id | integer or string | yes | 授权用户维护的 ID 或 URL 编码的项目路径 | | agent_id | integer | yes | 代理 ID | | token_id | integer | yes | 令牌 ID | 请求示例：

curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens/1

Receptive agents

DETAILS: Tier: Ultimate Offering: Self-managed

Receptive agents allow GitLab to integrate with Kubernetes clusters that cannot establish a network connection to the GitLab instance, but can be connected to by GitLab.

List URL configurations for a receptive agent

Returns a list of URL configurations for an agent.

You must have at least the Developer role to use this endpoint.

GET /projects/:id/cluster_agents/:agent_id/url_configurations

Supported attributes:

Response:

The response is a list of URL configurations with the following fields:

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations"

Example response:

[
  {
    "id": 1,
    "agent_id": 5,
    "url": "grpcs://agent.example.com:4242",
    "public_key": "..."
  }
]

Get a single agent URL configuration

Gets a single agent URL configuration.

You must have at least the Developer role to use this endpoint.

GET /projects/:id/cluster_agents/:agent_id/url_configurations/:url_configuration_id

Supported attributes:

Response:

The response is a single URL configuration with the following fields:

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations/1"

Example response:

{
"id": 1,
"agent_id": 5,
"url": "grpcs://agent.example.com:4242",
"public_key": "..."
}

创建大理的 URL 配置

为代理创建新的 URL 配置。

您必须至少具有维护者角色才能使用才端点。

一个代码同时只能拥有一个 URL 配置。

POST /projects/:id/cluster_agents/:agent_id/url_configurations

支持的属性：

响应：

响应时新的 URL 配置并具有以下字段：

使用 JWT 令牌创建 URL 配置的示例请求如下：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations" \
    -H "Content-Type:application/json" \
    -X POST --data '{"url":"grpcs://agent.example.com:4242"}'

JWT 认证的示例响应如下：

{
"id": 1,
"agent_id": 5,
"url": "grpcs://agent.example.com:4242",
"public_key": "..."
}

使用 mTLS 并使用来自文件 client.pem 和 client-key.pme 的证书和密钥来创建 URL 配置的示例：

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations" \
    -H "Content-Type:application/json" \
    -X POST --data '{"url":"grpcs://agent.example.com:4242", "client_cert":"'"$(awk -v ORS='\\n' '1' client.pem)"'", "client_key": "'"$(awk -v ORS='\\n' '1' client-key.pem)"'"}'

mTLS 的示例响应：

{
"id": 1,
"agent_id": 5,
"url": "grpcs://agent.example.com:4242",
"client_cert": "..."
}

删除代理的 URL 配置

删除某个代理的 URL 配置。

您必须至少是维护者角色才能使用此端点。

DELETE /projects/:id/cluster_agents/:agent_id/url_configurations/:url_configuration_id

支持的属性：

示例请求：

curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations/1