diff options
Diffstat (limited to 'doc/api/group_clusters.md')
| -rw-r--r-- | doc/api/group_clusters.md | 91 |
1 files changed, 53 insertions, 38 deletions
diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index 27b76d1f0c0..f169c1829be 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -1,13 +1,18 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group clusters API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30213) in GitLab 12.1. +Similar to [project-level](../user/project/clusters/index.md) and +[instance-level](../user/instance/clusters/index.md) Kubernetes clusters, +group-level Kubernetes clusters allow you to connect a Kubernetes cluster to +your group, enabling you to use the same cluster across multiple projects. + Users need at least [Maintainer](../user/permissions.md) access for the group to use these endpoints. ## List group clusters @@ -20,9 +25,9 @@ GET /groups/:id/clusters Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | Example request: @@ -39,6 +44,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -87,10 +94,10 @@ GET /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -106,6 +113,8 @@ Example response: "name":"cluster-1", "domain":"example.com", "created_at":"2019-01-02T20:18:12.563Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -154,19 +163,19 @@ POST /groups/:id/clusters/user Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `name` | string | yes | The name of the cluster | -| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | -| `enabled` | boolean | no | Determines if cluster is active or not, defaults to true | -| `managed` | boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, 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. Required if API is using a self-signed TLS certificate. | -| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | -| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | +| Attribute | Type | Required | Description | +| ---------------------------------------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `name` | string | yes | The name of the cluster | +| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not, defaults to `true` | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this cluster. 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. Required if API is using a self-signed TLS certificate. | +| `platform_kubernetes_attributes[authorization_type]` | string | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `environment_scope` | string | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | Example request: @@ -184,6 +193,8 @@ Example response: "id":24, "name":"cluster-5", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -223,19 +234,21 @@ PUT /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | -| `name` | string | no | The name of the cluster | -| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | -| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for 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. Required if API is using a self-signed TLS certificate. | -| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | - -NOTE: **Note:** +| Attribute | Type | Required | Description | +| ----------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------ | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | string | no | The name of the cluster | +| `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | +| `enabled` | boolean | no | Determines if cluster is active or not | +| `managed` | boolean | no | Determines if GitLab manages namespaces and service accounts for this 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. Required if API is using a self-signed TLS certificate. | +| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | + +NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added through the ["Add existing Kubernetes cluster"](../user/project/clusters/add_remove_clusters.md#add-existing-cluster) option or through the ["Add existing cluster to group"](#add-existing-cluster-to-group) endpoint. @@ -256,6 +269,8 @@ Example response: "name":"new-cluster-name", "domain":"new-domain.com", "created_at":"2019-01-03T21:53:40.610Z", + "managed": true, + "enabled": true, "provider_type":"user", "platform_type":"kubernetes", "environment_scope":"*", @@ -304,10 +319,10 @@ DELETE /groups/:id/clusters/:cluster_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `cluster_id` | integer | yes | The ID of the cluster | +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: |