# Instance clusters API

> 原文：[https://docs.gitlab.com/ee/api/instance_clusters.html](https://docs.gitlab.com/ee/api/instance_clusters.html)

*   [List instance clusters](#list-instance-clusters)
*   [Get a single instance cluster](#get-a-single-instance-cluster)
*   [Add existing instance cluster](#add-existing-instance-cluster)
*   [Edit instance cluster](#edit-instance-cluster)
*   [Delete instance cluster](#delete-instance-cluster)

# Instance clusters API[](#instance-clusters-api "Permalink")

在 GitLab 13.2 中[引入](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) .

**注意：**用户将需要管理员权限才能使用这些端点.

将这些 API 端点与实例集群一起使用，使您可以在多个项目中使用同一集群. [更多信息](../user/instance/clusters/index.html)

## List instance clusters[](#list-instance-clusters "Permalink")

返回实例集群的列表.

```
GET /admin/clusters 
```

请求示例：

```
curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/admin/clusters" 
```

响应示例：

```
[  {  "id":  9,  "name":  "cluster-1",  "created_at":  "2020-07-14T18:36:10.440Z",  "domain":  null,  "provider_type":  "user",  "platform_type":  "kubernetes",  "environment_scope":  "*",  "cluster_type":  "instance_type",  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "https://gitlab.example.com/root"  },  "platform_kubernetes":  {  "api_url":  "https://example.com",  "namespace":  null,  "authorization_type":  "rbac",  "ca_cert":"-----BEGIN CERTIFICATE-----IxMDM1MV0ZDJkZjM...-----END CERTIFICATE-----"  },  "provider_gcp":  null,  "management_project":  null  },  {  "id":  10,  "name":  "cluster-2",  "created_at":  "2020-07-14T18:39:05.383Z",  "domain":  null,  "provider_type":  "user",  "platform_type":  "kubernetes",  "environment_scope":  "staging",  "cluster_type":  "instance_type",  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "https://gitlab.example.com/root"  },  "platform_kubernetes":  {  "api_url":  "https://example.com",  "namespace":  null,  "authorization_type":  "rbac",  "ca_cert":"-----BEGIN CERTIFICATE-----LzEtMCadtaLGxcsGAZjM...-----END CERTIFICATE-----"  },  "provider_gcp":  null,  "management_project":  null  }  {  "id":  11,  "name":  "cluster-3",  ...  }  ] 
```

## Get a single instance cluster[](#get-a-single-instance-cluster "Permalink")

返回单个实例集群.

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `cluster_id` | integer | yes | 集群的 ID |

```
GET /admin/clusters/:cluster_id 
```

请求示例：

```
curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/admin/clusters/9" 
```

响应示例：

```
{  "id":  9,  "name":  "cluster-1",  "created_at":  "2020-07-14T18:36:10.440Z",  "domain":  null,  "provider_type":  "user",  "platform_type":  "kubernetes",  "environment_scope":  "*",  "cluster_type":  "instance_type",  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "https://gitlab.example.com/root"  },  "platform_kubernetes":  {  "api_url":  "https://example.com",  "namespace":  null,  "authorization_type":  "rbac",  "ca_cert":"-----BEGIN CERTIFICATE-----IxMDM1MV0ZDJkZjM...-----END CERTIFICATE-----"  },  "provider_gcp":  null,  "management_project":  null  } 
```

## Add existing instance cluster[](#add-existing-instance-cluster "Permalink")

添加现有的 Kubernetes 实例集群.

```
POST /admin/clusters/add 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 集群名称 |
| `domain` | string | no | 集群的[基础域](../user/project/clusters/index.html#base-domain) |
| `environment_scope` | string | no | 集群的关联环境. 默认为`*` |
| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.html) for the cluster |
| `enabled` | boolean | no | 确定集群是否处于活动状态，默认为 true |
| `managed` | boolean | no | 确定 GitLab 是否将管理该集群的名称空间和服务帐户，默认为 true |
| `platform_kubernetes_attributes[api_url]` | string | yes | 访问 Kubernetes API 的 URL |
| `platform_kubernetes_attributes[token]` | string | yes | 针对 Kubernetes 进行身份验证的令牌 |
| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS 证书. 如果 API 使用自签名 TLS 证书，则为必填. |
| `platform_kubernetes_attributes[namespace]` | string | no | 与项目相关的唯一名称空间 |
| `platform_kubernetes_attributes[authorization_type]` | string | no | 集群授权类型： `rbac` ， `abac`或`unknown_authorization` . 默认为`rbac` . |

请求示例：

```
curl --header "Private-Token:<your_access_token>" "http://gitlab.example.com/api/v4/admin/clusters/add" \
-H "Accept:application/json" \
-H "Content-Type:application/json" \
-X POST --data '{"name":"cluster-3", "environment_scope":"production", "platform_kubernetes_attributes":{"api_url":"https://example.com", "token":"12345",  "ca_cert":"-----BEGIN CERTIFICATE-----qpoeiXXZafCM0ZDJkZjM...-----END CERTIFICATE-----"}}' 
```

响应示例：

```
{  "id":  11,  "name":  "cluster-3",  "created_at":  "2020-07-14T18:42:50.805Z",  "domain":  null,  "provider_type":  "user",  "platform_type":  "kubernetes",  "environment_scope":  "production",  "cluster_type":  "instance_type",  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://gitlab.example.com:3000/root"  },  "platform_kubernetes":  {  "api_url":  "https://example.com",  "namespace":  null,  "authorization_type":  "rbac",  "ca_cert":"-----BEGIN CERTIFICATE-----qpoeiXXZafCM0ZDJkZjM...-----END CERTIFICATE-----"  },  "provider_gcp":  null,  "management_project":  null  } 
```

## Edit instance cluster[](#edit-instance-cluster "Permalink")

更新现有的实例集群.

```
PUT /admin/clusters/:cluster_id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `cluster_id` | integer | yes | 集群的 ID |
| `name` | string | no | 集群名称 |
| `domain` | string | no | 集群的[基础域](../user/project/clusters/index.html#base-domain) |
| `environment_scope` | string | no | 集群的关联环境 |
| `management_project_id` | integer | no | 集群[管理项目](../user/clusters/management_project.html)的 ID |
| `enabled` | boolean | no | 确定集群是否处于活动状态，默认为 true |
| `platform_kubernetes_attributes[api_url]` | string | no | 访问 Kubernetes API 的 URL |
| `platform_kubernetes_attributes[token]` | string | no | 针对 Kubernetes 进行身份验证的令牌 |
| `platform_kubernetes_attributes[ca_cert]` | string | no | TLS 证书. 如果 API 使用自签名 TLS 证书，则为必填. |
| `platform_kubernetes_attributes[namespace]` | string | no | 与项目相关的唯一名称空间 |

**注意：**仅通过通过[添加现有 Kubernetes 集群](../user/project/clusters/add_remove_clusters.html#add-existing-cluster)选项或通过[添加现有实例集群](#add-existing-instance-cluster)端点[添加](#add-existing-instance-cluster)集群时，才能更新`name` ， `api_url` ， `ca_cert`和`token` .

请求示例：

```
curl --header "Private-Token: <your_access_token>" "http://gitlab.example.com/api/v4/admin/clusters/9" \
-H "Content-Type:application/json" \
-X PUT --data '{"name":"update-cluster-name", "platform_kubernetes_attributes":{"api_url":"https://new-example.com","token":"new-token"}}' 
```

响应示例：

```
{  "id":  9,  "name":  "update-cluster-name",  "created_at":  "2020-07-14T18:36:10.440Z",  "domain":  null,  "provider_type":  "user",  "platform_type":  "kubernetes",  "environment_scope":  "*",  "cluster_type":  "instance_type",  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "https://gitlab.example.com/root"  },  "platform_kubernetes":  {  "api_url":  "https://new-example.com",  "namespace":  null,  "authorization_type":  "rbac",  "ca_cert":"-----BEGIN CERTIFICATE-----IxMDM1MV0ZDJkZjM...-----END CERTIFICATE-----"  },  "provider_gcp":  null,  "management_project":  null,  "project":  null  } 
```

## Delete instance cluster[](#delete-instance-cluster "Permalink")

删除现有的实例集群.

```
DELETE /admin/clusters/:cluster_id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `cluster_id` | integer | yes | 集群的 ID |

请求示例：

```
curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/admin/clusters/11" 
```