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	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	Cluster base domain
`enabled`	Boolean	Determines if cluster is active or not, defaults to true Default: `true`
`environment_scope`	String	The associated environment to the cluster Default: `*`
`managed`	Boolean	Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true Default: `true`
`management_project_id`	Integer	The ID of the management project
`name` Required	String	Cluster name
`namespace_per_environment`	Boolean	Deploy 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, defaults to RBAC 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	Unique namespace related to Project
`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	The cluster ID

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	The cluster ID

Request body (application/json)

Property	Type	Description
`domain`	String	Cluster base domain
`enabled`	Boolean	Enable or disable Gitlab’s connection to your Kubernetes cluster
`environment_scope`	String	The associated environment to the cluster
`managed`	Boolean	Determines if GitLab will manage namespaces and service accounts for this cluster
`management_project_id`	Integer	The ID of the management project
`name`	String	Cluster name
`namespace_per_environment`	Boolean	Deploy 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	Unique namespace related to Project
`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	The cluster ID

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	The group ID 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	The ID of the group
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	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	The ID of the group

Request body (application/json)

Property	Type	Description
`domain`	String	Cluster base domain
`enabled`	Boolean	Determines if cluster is active or not, defaults to true Default: `true`
`environment_scope`	String	The associated environment to the cluster Default: `*`
`managed`	Boolean	Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true Default: `true`
`management_project_id`	Integer	The ID of the management project
`name` Required	String	Cluster name
`namespace_per_environment`	Boolean	Deploy 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, defaults to RBAC 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	Unique namespace related to Group
`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	The ID of the group
`cluster_id` Path, required	Integer	The cluster ID

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	The ID of the group
`cluster_id` Path, required	Integer	The cluster ID

Request body (application/json)

Property	Type	Description
`domain`	String	Cluster base domain
`enabled`	Boolean	Determines if cluster is active or not
`environment_scope`	String	The associated environment to the cluster
`managed`	Boolean	Determines if GitLab will manage namespaces and service accounts for this cluster
`management_project_id`	Integer	The ID of the management project
`name`	String	Cluster name
`namespace_per_environment`	Boolean	Deploy 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	Unique namespace related to Group
`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	The ID of the group
`cluster_id` Path, required	Integer	The Cluster ID

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	The ID or URL-encoded path of the project
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	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	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`domain`	String	Cluster base domain
`enabled`	Boolean	Determines if cluster is active or not, defaults to true Default: `true`
`environment_scope`	String	The associated environment to the cluster Default: `*`
`managed`	Boolean	Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true Default: `true`
`management_project_id`	Integer	The ID of the management project
`name` Required	String	Cluster name
`namespace_per_environment`	Boolean	Deploy 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, defaults to RBAC 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	Unique namespace related to Project
`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	The ID or URL-encoded path of the project
`cluster_id` Path, required	Integer	The cluster ID

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	The ID or URL-encoded path of the project
`cluster_id` Path, required	Integer	The cluster ID

Request body (application/json)

Property	Type	Description
`domain`	String	Cluster base domain
`enabled`	Boolean	Determines if cluster is active or not
`environment_scope`	String	The associated environment to the cluster
`managed`	Boolean	Determines if GitLab will manage namespaces and service accounts for this cluster
`management_project_id`	Integer	The ID of the management project
`name`	String	Cluster name
`namespace_per_environment`	Boolean	Deploy 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	Unique namespace related to Project
`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	The ID or URL-encoded path of the project
`cluster_id` Path, required	Integer	The Cluster ID

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