Clusters

These certificate-based cluster endpoints are deprecated.

Use this API to manage and discover the certificate-based Kubernetes clusters of an instance, a group, or a project. Connecting a cluster to a group or an instance lets you use the same cluster across multiple projects.

Instance endpoints require administrator access. Group and project endpoints require the Maintainer or Owner role.

List all instance clusters

GET /api/v4/admin/clusters

Lists all instance clusters for the instance.

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCluster
`403`	Forbidden	—

Create an instance cluster

POST /api/v4/admin/clusters/add

Creates an instance cluster by adding an existing Kubernetes cluster.

Request body (application/json)

Property	Type	Description
`domain`	String	Base domain of the cluster
`enabled`	Boolean	If `true`, the cluster is active and GitLab’s connection to the Kubernetes cluster is enabled Default: `true`
`environment_scope`	String	Associated environment to the cluster Default: `*`
`managed`	Boolean	If `true`, GitLab manages namespaces and service accounts for this cluster Default: `true`
`management_project_id`	Integer	ID of the management project for the cluster
`name` Required	String	Name of the cluster
`namespace_per_environment`	Boolean	If `true`, deploys each environment to a separate Kubernetes namespace Default: `true`
`platform_kubernetes_attributes` Required	Object	Platform Kubernetes data
`platform_kubernetes_attributes.api_url` Required	String	URL to access the Kubernetes API
`platform_kubernetes_attributes.authorization_type`	String	Cluster authorization type Allowed values: `unknown_authorization`, `rbac`, `abac` Default: `rbac`
`platform_kubernetes_attributes.ca_cert`	String	TLS certificate (needed if API is using a self-signed TLS certificate)
`platform_kubernetes_attributes.namespace`	String	Kubernetes namespace that environments deploy to. Allowed only when `managed` is `false`
`platform_kubernetes_attributes.token` Required	String	Token to authenticate against Kubernetes

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCluster
`400`	Validation error	—
`403`	Forbidden	—
`404`	Not found	—

Retrieve a single instance cluster

GET /api/v4/admin/clusters/{cluster_id}

Retrieves a specified instance cluster.

Parameters

Name	Type	Description
`cluster_id` Path, required	Integer	ID of the cluster

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCluster
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not found	—

Update an instance cluster

PUT /api/v4/admin/clusters/{cluster_id}

Updates an existing instance cluster.

Parameters

Name	Type	Description
`cluster_id` Path, required	Integer	ID of the cluster

Request body (application/json)

Property	Type	Description
`domain`	String	Base domain of the cluster
`enabled`	Boolean	If `true`, the cluster is active and GitLab’s connection to the Kubernetes cluster is enabled
`environment_scope`	String	Associated environment to the cluster
`managed`	Boolean	If `true`, GitLab manages namespaces and service accounts for this cluster
`management_project_id`	Integer	ID of the management project for the cluster
`name`	String	Name of the cluster
`namespace_per_environment`	Boolean	If `true`, deploys each environment to a separate Kubernetes namespace Default: `true`
`platform_kubernetes_attributes`	Object	Platform Kubernetes data
`platform_kubernetes_attributes.api_url`	String	URL to access the Kubernetes API
`platform_kubernetes_attributes.ca_cert`	String	TLS certificate (needed if API is using a self-signed TLS certificate)
`platform_kubernetes_attributes.namespace`	String	Kubernetes namespace that environments deploy to. Allowed only when `managed` is `false`
`platform_kubernetes_attributes.token`	String	Token to authenticate against Kubernetes

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCluster
`400`	Validation error	—
`403`	Forbidden	—
`404`	Not found	—

Delete instance cluster

DELETE /api/v4/admin/clusters/{cluster_id}

Deletes an existing instance cluster. Does not remove existing resources in the connected Kubernetes cluster.

Parameters

Name	Type	Description
`cluster_id` Path, required	Integer	ID of the cluster

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCluster
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not found	—

List all certificate-based clusters

GET /api/v4/discover-cert-based-clusters

Lists all certificate-based clusters associated with a project. This feature was introduced in GitLab 17.9.

Parameters

Name	Type	Description
`group_id` Query, required	Integer	ID of the group to find all certificate-based clusters in the hierarchy

Responses

Code	Description	Schema
`200`	OK	APIEntitiesDiscoveredClusters
`400`	Bad Request	—
`403`	Forbidden	—

List all group clusters

GET /api/v4/groups/{id}/clusters

Lists all group clusters for a specified group.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCluster
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not Found	—

Create a group cluster

POST /api/v4/groups/{id}/clusters/user

Creates a group cluster for a specified group by adding an existing Kubernetes cluster.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group

Request body (application/json)

Property	Type	Description
`domain`	String	Base domain of the cluster
`enabled`	Boolean	If `true`, the cluster is active and GitLab’s connection to the Kubernetes cluster is enabled Default: `true`
`environment_scope`	String	Associated environment to the cluster. Premium and Ultimate only Default: `*`
`managed`	Boolean	If `true`, GitLab manages namespaces and service accounts for this cluster Default: `true`
`management_project_id`	Integer	ID of the management project for the cluster
`name` Required	String	Name of the cluster
`namespace_per_environment`	Boolean	If `true`, deploys each environment to a separate Kubernetes namespace Default: `true`
`platform_kubernetes_attributes` Required	Object	Platform Kubernetes data
`platform_kubernetes_attributes.api_url` Required	String	URL to access the Kubernetes API
`platform_kubernetes_attributes.authorization_type`	String	Cluster authorization type Allowed values: `unknown_authorization`, `rbac`, `abac` Default: `rbac`
`platform_kubernetes_attributes.ca_cert`	String	TLS certificate (needed if API is using a self-signed TLS certificate)
`platform_kubernetes_attributes.namespace`	String	Kubernetes namespace that environments deploy to. Allowed only when `managed` is `false`
`platform_kubernetes_attributes.token` Required	String	Token to authenticate against Kubernetes

Responses

Code	Description	Schema
`201`	Created	APIEntitiesClusterGroup
`400`	Validation error	—
`403`	Forbidden	—
`404`	Not found	—

Retrieve a group cluster

GET /api/v4/groups/{id}/clusters/{cluster_id}

Retrieves a specified group cluster.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`cluster_id` Path, required	Integer	ID of the cluster

Responses

Code	Description	Schema
`200`	OK	APIEntitiesClusterGroup
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not found	—

Update a group cluster

PUT /api/v4/groups/{id}/clusters/{cluster_id}

Updates a specified group cluster.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`cluster_id` Path, required	Integer	ID of the cluster

Request body (application/json)

Property	Type	Description
`domain`	String	Base domain of the cluster
`enabled`	Boolean	If `true`, the cluster is active and GitLab’s connection to the Kubernetes cluster is enabled
`environment_scope`	String	Associated environment to the cluster. Premium and Ultimate only
`managed`	Boolean	If `true`, GitLab manages namespaces and service accounts for this cluster
`management_project_id`	Integer	ID of the management project for the cluster
`name`	String	Name of the cluster
`namespace_per_environment`	Boolean	If `true`, deploys each environment to a separate Kubernetes namespace Default: `true`
`platform_kubernetes_attributes`	Object	Platform Kubernetes data
`platform_kubernetes_attributes.api_url`	String	URL to access the Kubernetes API
`platform_kubernetes_attributes.ca_cert`	String	TLS certificate (needed if API is using a self-signed TLS certificate)
`platform_kubernetes_attributes.namespace`	String	Kubernetes namespace that environments deploy to. Allowed only when `managed` is `false`
`platform_kubernetes_attributes.token`	String	Token to authenticate against Kubernetes

Responses

Code	Description	Schema
`200`	OK	APIEntitiesClusterGroup
`400`	Validation error	—
`403`	Forbidden	—
`404`	Not found	—

Delete a group cluster

DELETE /api/v4/groups/{id}/clusters/{cluster_id}

Deletes a specified group cluster. Does not remove existing resources in the connected Kubernetes cluster.

Parameters

Name	Type	Description
`id` Path, required	String	ID or URL-encoded path of the group
`cluster_id` Path, required	Integer	ID of the cluster

Responses

Code	Description	Schema
`200`	OK	APIEntitiesClusterGroup
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not found	—

List all clusters in a project

GET /api/v4/projects/{id}/clusters

Lists all clusters in a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCluster
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not Found	—

Add a cluster to a project

POST /api/v4/projects/{id}/clusters/user

Adds a cluster to a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`domain`	String	Base domain of the cluster
`enabled`	Boolean	If `true`, the cluster is active and GitLab’s connection to the Kubernetes cluster is enabled Default: `true`
`environment_scope`	String	Associated environment to the cluster. Premium and Ultimate only Default: `*`
`managed`	Boolean	If `true`, GitLab manages namespaces and service accounts for this cluster Default: `true`
`management_project_id`	Integer	ID of the management project for the cluster
`name` Required	String	Name of the cluster
`namespace_per_environment`	Boolean	If `true`, deploys each environment to a separate Kubernetes namespace Default: `true`
`platform_kubernetes_attributes` Required	Object	Platform Kubernetes data
`platform_kubernetes_attributes.api_url` Required	String	URL to access the Kubernetes API
`platform_kubernetes_attributes.authorization_type`	String	Cluster authorization type Allowed values: `unknown_authorization`, `rbac`, `abac` Default: `rbac`
`platform_kubernetes_attributes.ca_cert`	String	TLS certificate (needed if API is using a self-signed TLS certificate)
`platform_kubernetes_attributes.namespace`	String	Kubernetes namespace that environments deploy to. If `managed` and `namespace_per_environment` are `true`, the environment slug is appended
`platform_kubernetes_attributes.token` Required	String	Token to authenticate against Kubernetes

Responses

Code	Description	Schema
`201`	Created	APIEntitiesClusterProject
`400`	Validation error	—
`403`	Forbidden	—
`404`	Not found	—

Retrieve a cluster from a project

GET /api/v4/projects/{id}/clusters/{cluster_id}

Retrieves a specified cluster in a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`cluster_id` Path, required	Integer	ID of the cluster

Responses

Code	Description	Schema
`200`	OK	APIEntitiesClusterProject
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not found	—

Update a cluster in a project

PUT /api/v4/projects/{id}/clusters/{cluster_id}

Updates a cluster in a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`cluster_id` Path, required	Integer	ID of the cluster

Request body (application/json)

Property	Type	Description
`domain`	String	Base domain of the cluster
`enabled`	Boolean	If `true`, the cluster is active and GitLab’s connection to the Kubernetes cluster is enabled
`environment_scope`	String	Associated environment to the cluster. Premium and Ultimate only
`managed`	Boolean	If `true`, GitLab manages namespaces and service accounts for this cluster
`management_project_id`	Integer	ID of the management project for the cluster
`name`	String	Name of the cluster
`namespace_per_environment`	Boolean	If `true`, deploys each environment to a separate Kubernetes namespace Default: `true`
`platform_kubernetes_attributes`	Object	Platform Kubernetes data
`platform_kubernetes_attributes.api_url`	String	URL to access the Kubernetes API
`platform_kubernetes_attributes.ca_cert`	String	TLS certificate (needed if API is using a self-signed TLS certificate)
`platform_kubernetes_attributes.namespace`	String	Kubernetes namespace that environments deploy to. If `managed` and `namespace_per_environment` are `true`, the environment slug is appended
`platform_kubernetes_attributes.token`	String	Token to authenticate against Kubernetes

Responses

Code	Description	Schema
`200`	OK	APIEntitiesClusterProject
`400`	Validation error	—
`403`	Forbidden	—
`404`	Not found	—

Delete cluster from a project

DELETE /api/v4/projects/{id}/clusters/{cluster_id}

Deletes a specified cluster from a project. Does not remove existing resources in the connected Kubernetes cluster.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`cluster_id` Path, required	Integer	ID of the cluster

Responses

Code	Description	Schema
`200`	OK	APIEntitiesClusterProject
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesBasicGroupDetails

Property	Type	Description
`id`	Integer (int64)	—
`name`	String	Example: `Diaspora`
`web_url`	String	Example: `http://gitlab.example.com/groups/diaspora`

APIEntitiesBasicProjectDetails

Property	Type	Description
`avatar_url`	String	Example: `http://example.com/uploads/project/avatar/3/uploads/avatar.png`
`created_at`	String (date-time)	Example: `2020-05-07T04:27:17.016Z`
`custom_attributes`	APIEntitiesCustomAttribute	—
`default_branch`	String	Example: `main`
`description`	String	Example: `desc`
`forks_count`	Integer	Example: `1`
`http_url_to_repo`	String	Example: `https://gitlab.example.com/gitlab/gitlab.git`
`id`	Integer (int64)	Example: `1`
`last_activity_at`	String (date-time)	Example: `2013-09-30T13:46:02Z`
`license`	APIEntitiesLicenseBasic	—
`license_url`	String	Example: `https://gitlab.example.com/gitlab/gitlab/blob/master/LICENCE`
`name`	String	Example: `project1`
`name_with_namespace`	String	Example: `John Doe / project1`
`namespace`	APIEntitiesNamespaceBasic	—
`path`	String	Example: `project1`
`path_with_namespace`	String	Example: `namespace1/project1`
`readme_url`	String	Example: `https://gitlab.example.com/gitlab/gitlab/blob/master/README.md`
`repository_storage`	String	Example: `default`
`ssh_url_to_repo`	String	Example: `git@gitlab.example.com:gitlab/gitlab.git`
`star_count`	Integer	Example: `1`
`tag_list`	Array of strings	Example: `["tag"]`
`topics`	Array of strings	Example: `["topic"]`
`visibility`	String	Example: `public`
`web_url`	String	Example: `https://gitlab.example.com/gitlab/gitlab`

APIEntitiesCluster

Property	Type	Description
`cluster_type`	String	—
`created_at`	String	—
`domain`	String	—
`enabled`	String	—
`environment_scope`	String	—
`id`	String	—
`managed`	String	—
`management_project`	APIEntitiesProjectIdentity	—
`name`	String	—
`namespace_per_environment`	String	—
`platform_kubernetes`	APIEntitiesPlatformKubernetes	—
`platform_type`	String	—
`provider_gcp`	APIEntitiesProviderGcp	—
`provider_type`	String	—
`user`	APIEntitiesUserBasic	—

APIEntitiesClusterGroup

Property	Type	Description
`cluster_type`	String	—
`created_at`	String	—
`domain`	String	—
`enabled`	String	—
`environment_scope`	String	—
`group`	APIEntitiesBasicGroupDetails	—
`id`	String	—
`managed`	String	—
`management_project`	APIEntitiesProjectIdentity	—
`name`	String	—
`namespace_per_environment`	String	—
`platform_kubernetes`	APIEntitiesPlatformKubernetes	—
`platform_type`	String	—
`provider_gcp`	APIEntitiesProviderGcp	—
`provider_type`	String	—
`user`	APIEntitiesUserBasic	—

APIEntitiesClusterProject

Property	Type	Description
`cluster_type`	String	—
`created_at`	String	—
`domain`	String	—
`enabled`	String	—
`environment_scope`	String	—
`id`	String	—
`managed`	String	—
`management_project`	APIEntitiesProjectIdentity	—
`name`	String	—
`namespace_per_environment`	String	—
`platform_kubernetes`	APIEntitiesPlatformKubernetes	—
`platform_type`	String	—
`project`	APIEntitiesBasicProjectDetails	—
`provider_gcp`	APIEntitiesProviderGcp	—
`provider_type`	String	—
`user`	APIEntitiesUserBasic	—

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesDiscoveredClusters

Property	Type	Description
`groups`	Object	—
`projects`	Object	—

APIEntitiesLicenseBasic

Property	Type	Description
`html_url`	String	Example: `http://choosealicense.com/licenses/gpl-3.0`
`key`	String	Example: `gpl-3.0`
`name`	String	Example: `GNU General Public License v3.0`
`nickname`	String	Example: `GNU GPLv3`
`source_url`	String	—

APIEntitiesNamespaceBasic

Property	Type	Description
`avatar_url`	String	Example: `https://example.com/avatar/12345`
`full_path`	String	Example: `group/my_project`
`id`	Integer (int64)	Example: `2`
`kind`	String	Example: `project`
`name`	String	Example: `project`
`parent_id`	Integer (int64)	Example: `1`
`path`	String	Example: `my_project`
`web_url`	String	Example: `https://example.com/group/my_project`

APIEntitiesPlatformKubernetes

Property	Type	Description
`api_url`	String	—
`authorization_type`	String	—
`ca_cert`	String	—
`namespace`	String	—

APIEntitiesProjectIdentity

Property	Type	Description
`created_at`	String (date-time)	Example: `2020-05-07T04:27:17.016Z`
`description`	String	Example: `desc`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `project1`
`name_with_namespace`	String	Example: `John Doe / project1`
`path`	String	Example: `project1`
`path_with_namespace`	String	Example: `namespace1/project1`

APIEntitiesProviderGcp

Property	Type	Description
`cluster_id`	String	—
`endpoint`	String	—
`gcp_project_id`	String	—
`machine_type`	String	—
`num_nodes`	String	—
`status_name`	String	—
`zone`	String	—

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

List all instance clusters

Create an instance cluster

Retrieve a single instance cluster

Update an instance cluster

Delete instance cluster

List all certificate-based clusters

List all group clusters

Create a group cluster

Retrieve a group cluster

Update a group cluster

Delete a group cluster

List all clusters in a project

Add a cluster to a project

Retrieve a cluster from a project

Update a cluster in a project

Delete cluster from a project

Schemas

APIEntitiesBasicGroupDetails

APIEntitiesBasicProjectDetails

APIEntitiesCluster

APIEntitiesClusterGroup

APIEntitiesClusterProject

APIEntitiesCustomAttribute

APIEntitiesDiscoveredClusters

APIEntitiesLicenseBasic

APIEntitiesNamespaceBasic

APIEntitiesPlatformKubernetes

APIEntitiesProjectIdentity

APIEntitiesProviderGcp

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error