代理 API (BASIC ALL)
引入于极狐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 | 令牌的状态。有效值为 active 和 revoked
|
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
}
]
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 | 令牌状态。有效值为 active 和 revoked
|
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 | 令牌状态。有效值为 active 和 revoked
|
created_at
| string | 创建令牌的 ISO8601 日期时间 |
created_by_user_id
| string | 创建令牌的用户的 ID |
last_used_at
| string or null | 上次使用的令牌的 ISO8601 日期时间 |
token
| string | Secret 令牌值 |
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