Adds project cluster documentationdocs-kubernetes-api-40473

Project cluster API was included on 11.7. This MR describes the new
project cluster endpoints

2 files changed, 340 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..198a8f9c70e
--- /dev/null
+++ b/doc/api/project_clusters.md
@@ -0,0 +1,339 @@
+# 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:
+
+```bash
+curl --header 'Private-Token: '9koXpg98eAheJpvBs5tK'' https://gitlab.example.com/api/v4/projects/26/clusters
+```
+
+```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 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:
+
+```bash
+curl --header 'Private-Token: '9koXpg98eAheJpvBs5tK'' https://gitlab.example.com/api/v4/projects/26/clusters/18
+```
+
+```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 an existing cluster
+
+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:
+
+```bash
+curl --header 'Private-Token: '$MAINTAINER_PAT'' 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-----"}}'
+```
+
+```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 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 an existing cluster"](#add-an-existing-kubernetes-cluster) endpoint.
+
+Example:
+
+```bash
+curl --header 'Private-Token: '9koXpg98eAheJpvBs5tK'' 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"}'
+```
+
+```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:
+
+```bash
+curl --header 'Private-Token: '9koXpg98eAheJpvBs5tK'' https://gitlab.example.com/api/v4/projects/26/clusters/23'
+```