diff options
| -rw-r--r-- | doc/api/README.md | 1 | ||||
| -rw-r--r-- | doc/api/project_clusters.md | 346 |
2 files changed, 347 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index fd5e88cb9d5..50bb529b2ab 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -49,6 +49,7 @@ The following API resources are available: - [Projects](projects.md) including setting Webhooks - [Project access requests](access_requests.md) - [Project badges](project_badges.md) + - [Project clusters](project_clusters.md) - [Project-level variables](project_level_variables.md) - [Project import/export](project_import_export.md) - [Project members](members.md) diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md new file mode 100644 index 00000000000..c51a3564211 --- /dev/null +++ b/doc/api/project_clusters.md @@ -0,0 +1,346 @@ +# 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' +``` |