代理 API

  • 引入于极狐GitLab 14.10。

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

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

列出项目的代理

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

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

GET /projects/:id/cluster_agents

参数:

参数 类型 是否必需 描述
id integer or string yes 授权用户维护的 ID 或 URL 编码的项目路径

响应:

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

参数 类型 描述
id integer 代理 ID
name string 代理名称
config_project object 代表代理从属的项目的对象
config_project.id integer 项目 ID
config_project.description string 项目描述
config_project.name string 项目名称
config_project.name_with_namespace string 带有项目命名空间的全名
config_project.path string 项目路径
config_project.path_with_namespace string 带有项目命名空间的完整路径
config_project.created_at string 创建项目的 ISO8601 日期时间
created_at string 创建代理的 ISO8601 日期时间
created_by_user_id integer 创建代理的用户的 ID

请求示例:

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

参数:

参数 类型 是否必需 描述
id integer or string yes 授权用户维护的 ID 或 URL 编码的项目路径
agent_id integer yes 代理 ID

响应:

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

参数 类型 描述
id integer 代理 ID
name string 代理名称
config_project object 代表代理从属的项目的对象
config_project.id integer 项目 ID
config_project.description string 项目描述
config_project.name string 项目名称
config_project.name_with_namespace string 带有项目命名空间的全名
config_project.path string 项目路径
config_project.path_with_namespace string 带有项目命名空间的完整路径
config_project.created_at string 创建项目的 ISO8601 日期时间
created_at string 创建代理的 ISO8601 日期时间
created_by_user_id integer 创建代理的用户的 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

参数:

参数 类型 是否必需 描述
id integer or string yes 授权用户维护的 ID 或 URL 编码的项目路径
name string yes 代理名称

响应:

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

参数 类型 描述
id integer 代理 ID
name string 代理名称
config_project object 代表代理从属的项目的对象
config_project.id integer 项目 ID
config_project.description string 项目描述
config_project.name string 项目名称
config_project.name_with_namespace string 带有项目命名空间的全名
config_project.path string 项目路径
config_project.path_with_namespace string 带有项目命名空间的完整路径
config_project.created_at string 创建项目的 ISO8601 日期时间
created_at string 创建代理的 ISO8601 日期时间
created_by_user_id integer 创建代理的用户的 ID

请求示例:

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

支持的参数:

参数 类型 是否必需 描述
id integer or string yes 授权用户维护的 ID 或 URL 编码的项目路径
agent_id integer or string yes 代理 ID

响应:

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

参数 类型 描述
id integer 令牌 ID
name string 令牌名称
description string or null 令牌描述
agent_id integer 令牌从属的代理的 ID
status string 令牌的状态。有效值为 activerevoked
created_at string 创建令牌的 ISO8601 日期时间
created_by_user_id string 创建令牌的用户的 ID

请求示例:

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
  }
]
note 只有在获取单个代理令牌的时候,才返回令牌的 last_used_at 字段。

获取单个代理令牌

引入于极狐GitLab 15.0。

获取单个代理令牌。

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

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

GET /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

响应:

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

参数 类型 描述
id integer 令牌 ID
name string 令牌名称
description string or null 令牌描述
agent_id integer 令牌从属的代理的 ID
status string 令牌状态。有效值为 activerevoked
created_at string 创建令牌的 ISO8601 日期时间
created_by_user_id string 创建令牌的用户的 ID
last_used_at string or null 上次使用令牌的 ISO8601 日期时间

请求示例:

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

支持的参数:

参数 类型 是否必需 描述
id integer or string yes 授权用户维护的 ID 或 URL 编码的项目路径
agent_id integer yes 代理 ID
name string yes 令牌名称
description string no 令牌描述

响应:

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

参数 类型 描述
id integer 令牌 ID
name string 令牌名称
description string or null 令牌描述
agent_id integer 令牌从属的代理的 ID
status string 令牌状态。有效值为 activerevoked
created_at string 创建令牌的 ISO8601 日期时间
created_by_user_id string 创建令牌的用户的 ID
last_used_at string or null 上次使用的令牌的 ISO8601 日期时间
token string Secret 令牌值
note 只有响应 POST 端点的时候才能返回 token,且之后无法检索。

请求示例:

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