Use this API to interact with the GitLab agent for Kubernetes.
List all agents
GET /api/v4/projects/{id}/cluster_agents
Lists all agents registered for the project. You must have the Developer, Maintainer, or Owner role to use this endpoint.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Create an agent
POST /api/v4/projects/{id}/cluster_agents
Creates an agent for the project. You must have the Maintainer or Owner role to use this endpoint.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
nameRequired | String | The name of the agent |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Retrieve details on an agent
GET /api/v4/projects/{id}/cluster_agents/{agent_id}
Retrieves details on a specified agent. You must have the Developer, Maintainer, or Owner role to use this endpoint.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
agent_Path, | Integer | The ID of an agent |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Delete an agent
DELETE /api/v4/projects/{id}/cluster_agents/{agent_id}
Deletes an existing agent registration. You must have the Maintainer or Owner role to use this endpoint.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
agent_Path, | Integer | The ID of an agent |
Responses
| Code | Description | Schema |
|---|---|---|
204 | Resource deleted | — |
400 | Bad Request | — |
404 | Not Found | — |
List all agent tokens
GET /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens
Lists all active tokens for an agent. You must have the Developer, Maintainer, or Owner role to use this endpoint.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
agent_Path, | Integer | The ID of an agent |
pageQuery | Integer | Current page number Default: 1Example: 1 |
per_Query | Integer | Number of items per page Default: 20Example: 20 |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Create an agent token
POST /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens
Creates a token for an agent. You must have the Maintainer or Owner role to use this endpoint. An agent can have only two active tokens at one time.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
agent_Path, | Integer | The ID of an agent |
Request body (application/json)
| Property | Type | Description |
|---|---|---|
description | String | The description for the token |
nameRequired | String | The name for the token |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Retrieve an agent token
GET /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens/{token_id}
Retrieves a specified agent token. You must have the Developer, Maintainer, or Owner role to use this endpoint. Returns a 404 if the agent token has been revoked.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
agent_Path, | Integer | The ID of an agent |
token_Path, | Integer | The ID of the agent token |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
400 | Bad Request | — |
404 | Not Found | — |
Revoke an agent token
DELETE /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens/{token_id}
Revokes an agent token. You must have the Maintainer or Owner role to use this endpoint.
Parameters
| Name | Type | Description |
|---|---|---|
idPath, | String or integer | The ID or URL- |
agent_Path, | Integer | The ID of an agent |
token_Path, | Integer | The ID of the agent token |
Responses
| Code | Description | Schema |
|---|---|---|
204 | Resource deleted | — |
400 | Bad Request | — |
404 | Not Found | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesClustersAgent
| Property | Type | Description |
|---|---|---|
config_ | APIEntities | — |
created_ | String (date- | — |
created_ | Integer (int64) | Example:1 |
id | Integer (int64) | Example:1 |
name | String | — |
APIEntitiesClustersAgentToken
| Property | Type | Description |
|---|---|---|
agent_ | Integer (int64) | Example:1 |
created_ | String (date- | — |
created_ | Integer (int64) | Example:1 |
description | String | — |
id | Integer (int64) | Example:1 |
last_ | String (date- | — |
name | String | — |
status | String | — |
APIEntitiesClustersAgentTokenBasic
| Property | Type | Description |
|---|---|---|
agent_ | Integer (int64) | Example:1 |
created_ | String (date- | — |
created_ | Integer (int64) | Example:1 |
description | String | — |
id | Integer (int64) | Example:1 |
name | String | — |
status | String | — |
APIEntitiesClustersAgentTokenWithToken
| Property | Type | Description |
|---|---|---|
agent_ | Integer (int64) | Example:1 |
created_ | String (date- | — |
created_ | Integer (int64) | Example:1 |
description | String | — |
id | Integer (int64) | Example:1 |
last_ | String (date- | — |
name | String | — |
status | String | — |
token | String | — |
APIEntitiesProjectIdentity
| Property | Type | Description |
|---|---|---|
created_ | String (date- | Example:2020- |
description | String | Example:desc |
id | Integer (int64) | Example:1 |
name | String | Example:project1 |
name_ | String | Example:John Doe / |
path | String | Example:project1 |
path_ | String | Example:namespace1/ |