kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/api/project_clusters.md
Mayra Cabrera bb3840048e Adds project cluster documentation 
Project cluster API was included on 11.7. This MR describes the new
project cluster endpoints
2019-01-08 08:46:41 -06:00

346 lines
11 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Project clusters API
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23922)
in GitLab 11.7.
NOTE: **Note:**
User will need at least maintainer access to use these endpoints.
## List project clusters
Returns a list of project clusters.
```
GET /projects/:id/clusters
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the project owned by the authenticated user |
Example request:
```bash
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters
```
Example response:
```json
[
{
"id":18,
"name":"cluster-1",
"created_at":"2019-01-02T20:18:12.563Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://104.197.68.152",
"namespace":"cluster-1-namespace",
"authorization_type":"rbac",
"ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
}
},
{
"id":19,
"name":"cluster-2",
...
}
]
```
## Get a single project cluster
Gets a single project cluster.
```bash
GET /projects/:id/clusters/:cluster_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the project owned by the authenticated user |
| `cluster_id` | integer | yes | The ID of the cluster |
Example request:
```bash
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/18
```
Example response:
```json
{
"id":18,
"name":"cluster-1",
"created_at":"2019-01-02T20:18:12.563Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://104.197.68.152",
"namespace":"cluster-1-namespace",
"authorization_type":"rbac",
"ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
},
"project":
{
"id":26,
"description":"",
"name":"project-with-clusters-api",
"name_with_namespace":"Administrator / project-with-clusters-api",
"path":"project-with-clusters-api",
"path_with_namespace":"root/project-with-clusters-api",
"created_at":"2019-01-02T20:13:32.600Z",
"default_branch":null,
"tag_list":[],
"ssh_url_to_repo":"ssh://gitlab.example.com/root/project-with-clusters-api.git",
"http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git",
"web_url":"https://gitlab.example.com/root/project-with-clusters-api",
"readme_url":null,
"avatar_url":null,
"star_count":0,
"forks_count":0,
"last_activity_at":"2019-01-02T20:13:32.600Z",
"namespace":
{
"id":1,
"name":"root",
"path":"root",
"kind":"user",
"full_path":"root",
"parent_id":null
}
}
}
```
## Add existing cluster to project
Adds an existing Kubernetes cluster to the project.
```bash
POST /projects/:id/clusters/user
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the project owned by the authenticated user |
| `name` | String | yes | The name of the cluster |
| `enabled` | Boolean | no | Determines if cluster is active or not, defaults to true |
| `platform_kubernetes_attributes[api_url]` | String | yes | The URL to access the Kubernetes API |
| `platform_kubernetes_attributes[token]` | String | yes | The token to authenticate against Kubernetes |
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. |
Example request:
```bash
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/user \
-H "Accept: application/json" \
-H "Content-Type:application/json" \
-X POST --data '{"name":"cluster-5", "platform_kubernetes_attributes":{"api_url":"https://35.111.51.20","token":"12345","namespace":"cluster-5-namespace","ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"}}'
```
Example response:
```json
{
"id":24,
"name":"cluster-5",
"created_at":"2019-01-03T21:53:40.610Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://35.111.51.20",
"namespace":"cluster-5-namespace",
"authorization_type":"rbac",
"ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
},
"project":
{
"id":26,
"description":"",
"name":"project-with-clusters-api",
"name_with_namespace":"Administrator / project-with-clusters-api",
"path":"project-with-clusters-api",
"path_with_namespace":"root/project-with-clusters-api",
"created_at":"2019-01-02T20:13:32.600Z",
"default_branch":null,
"tag_list":[],
"ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git",
"http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git",
"web_url":"https://gitlab.example.com/root/project-with-clusters-api",
"readme_url":null,
"avatar_url":null,
"star_count":0,
"forks_count":0,
"last_activity_at":"2019-01-02T20:13:32.600Z",
"namespace":
{
"id":1,
"name":"root",
"path":"root",
"kind":"user",
"full_path":"root",
"parent_id":null
}
}
}
```
## Edit project cluster
Updates an existing project cluster.
```bash
PUT /projects/:id/clusters/:cluster_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the project owned by the authenticated user |
| `name` | String | no | The name of the cluster |
| `platform_kubernetes_attributes[api_url]` | String | no | The URL to access the Kubernetes API |
| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes |
| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate |
| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project |
NOTE: **Note:**
`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added
through the ["Add an existing Kubernetes Cluster"](../user/project/clusters/index.md#adding-an-existing-kubernetes-cluster) option or
through the ["Add existing cluster to project"](#add-existing-cluster-to-project) endpoint.
Example request:
```bash
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/24 \
-H "Content-Type:application/json" \
-X PUT --data '{"name":"new-cluster-name","api_url":"https://new-api-url.com"}'
```
Example response:
```json
{
"id":24,
"name":"new-cluster-name",
"created_at":"2019-01-03T21:53:40.610Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://new-api-url.com",
"namespace":"cluster-5-namespace",
"authorization_type":"rbac",
"ca_cert":null
},
"project":
{
"id":26,
"description":"",
"name":"project-with-clusters-api",
"name_with_namespace":"Administrator / project-with-clusters-api",
"path":"project-with-clusters-api",
"path_with_namespace":"root/project-with-clusters-api",
"created_at":"2019-01-02T20:13:32.600Z",
"default_branch":null,
"tag_list":[],
"ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git",
"http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git",
"web_url":"https://gitlab.example.com/root/project-with-clusters-api",
"readme_url":null,
"avatar_url":null,
"star_count":0,
"forks_count":0,
"last_activity_at":"2019-01-02T20:13:32.600Z",
"namespace":
{
"id":1,
"name":"root",
"path":"root",
"kind":"user",
"full_path":"root",
"parent_id":null
}
}
}
```
## Delete project cluster
Deletes an existing project cluster.
```
DELETE /projects/:id/clusters/:cluster_id
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the project owned by the authenticated user |
| `cluster_id` | integer | yes | The ID of the cluster |
Example request:
```bash
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/23'
```
View git blame Copy permalink