Documentation
Documentation
https://docs.gitlab.com/api/
APIReference
https://docs.gitlab.com/api/api_resources/
Authentication
https://docs.gitlab.com/api/rest/authentication/
OpenAPI Specification
swagger: '2.0'
info:
title: GitLab access_requests clusters API
version: v4
description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: clusters
description: Operations related to clusters
paths:
/api/v4/groups/{id}/clusters:
get:
summary: List group clusters
description: This feature was introduced in GitLab 12.1. Returns a list of group clusters.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of the group
type: string
required: true
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List group clusters
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Cluster'
'403':
description: Forbidden
tags:
- clusters
operationId: getApiV4GroupsIdClusters
/api/v4/groups/{id}/clusters/{cluster_id}:
get:
summary: Get a single group cluster
description: This feature was introduced in GitLab 12.1. Gets a single group cluster.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of the group
type: string
required: true
- in: path
name: cluster_id
description: The cluster ID
type: integer
format: int32
required: true
responses:
'200':
description: Get a single group cluster
schema:
$ref: '#/definitions/API_Entities_ClusterGroup'
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: getApiV4GroupsIdClustersClusterId
put:
summary: Edit group cluster
description: This feature was introduced in GitLab 12.1. Updates an existing group cluster.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID of the group
type: string
required: true
- in: path
name: cluster_id
description: The cluster ID
type: integer
format: int32
required: true
- name: putApiV4GroupsIdClustersClusterId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4GroupsIdClustersClusterId'
responses:
'200':
description: Edit group cluster
schema:
$ref: '#/definitions/API_Entities_ClusterGroup'
'400':
description: Validation error
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: putApiV4GroupsIdClustersClusterId
delete:
summary: Delete group cluster
description: This feature was introduced in GitLab 12.1. Deletes an existing group cluster. Does not remove existing resources within the connected Kubernetes cluster.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of the group
type: string
required: true
- in: path
name: cluster_id
description: The Cluster ID
type: integer
format: int32
required: true
responses:
'403':
description: Forbidden
'204':
description: Delete group cluster
schema:
$ref: '#/definitions/API_Entities_ClusterGroup'
'404':
description: Not found
tags:
- clusters
operationId: deleteApiV4GroupsIdClustersClusterId
/api/v4/groups/{id}/clusters/user:
post:
summary: Add existing cluster to group
description: This feature was introduced in GitLab 12.1. Adds an existing Kubernetes cluster to the group.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID of the group
type: string
required: true
- name: postApiV4GroupsIdClustersUser
in: body
required: true
schema:
$ref: '#/definitions/postApiV4GroupsIdClustersUser'
responses:
'201':
description: Add existing cluster to group
schema:
$ref: '#/definitions/API_Entities_ClusterGroup'
'400':
description: Validation error
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: postApiV4GroupsIdClustersUser
/api/v4/projects/{id}/clusters:
get:
summary: List project clusters
description: This feature was introduced in GitLab 11.7. Returns a list of project clusters.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List project clusters
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Cluster'
'403':
description: Forbidden
tags:
- clusters
operationId: getApiV4ProjectsIdClusters
/api/v4/projects/{id}/clusters/{cluster_id}:
get:
summary: Get a single project cluster
description: This feature was introduced in GitLab 11.7. Gets a single project cluster.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: cluster_id
description: The cluster ID
type: integer
format: int32
required: true
responses:
'200':
description: Get a single project cluster
schema:
$ref: '#/definitions/API_Entities_ClusterProject'
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: getApiV4ProjectsIdClustersClusterId
put:
summary: Edit project cluster
description: This feature was introduced in GitLab 11.7. Updates an existing project cluster.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: cluster_id
description: The cluster ID
type: integer
format: int32
required: true
- name: putApiV4ProjectsIdClustersClusterId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4ProjectsIdClustersClusterId'
responses:
'200':
description: Edit project cluster
schema:
$ref: '#/definitions/API_Entities_ClusterProject'
'400':
description: Validation error
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: putApiV4ProjectsIdClustersClusterId
delete:
summary: Delete project cluster
description: This feature was introduced in GitLab 11.7. Deletes an existing project cluster. Does not remove existing resources within the connected Kubernetes cluster.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: cluster_id
description: The Cluster ID
type: integer
format: int32
required: true
responses:
'403':
description: Forbidden
'204':
description: Delete project cluster
schema:
$ref: '#/definitions/API_Entities_ClusterProject'
'404':
description: Not found
tags:
- clusters
operationId: deleteApiV4ProjectsIdClustersClusterId
/api/v4/projects/{id}/clusters/user:
post:
summary: Add existing cluster to project
description: This feature was introduced in GitLab 11.7. Adds an existing Kubernetes cluster to the project.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- name: postApiV4ProjectsIdClustersUser
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdClustersUser'
responses:
'201':
description: Add existing cluster to project
schema:
$ref: '#/definitions/API_Entities_ClusterProject'
'400':
description: Validation error
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: postApiV4ProjectsIdClustersUser
/api/v4/admin/clusters:
get:
summary: List instance clusters
description: This feature was introduced in GitLab 13.2. Returns a list of instance clusters.
produces:
- application/json
responses:
'200':
description: List instance clusters
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Cluster'
'403':
description: Forbidden
tags:
- clusters
operationId: getApiV4AdminClusters
/api/v4/admin/clusters/{cluster_id}:
get:
summary: Get a single instance cluster
description: This feature was introduced in GitLab 13.2. Returns a single instance cluster.
produces:
- application/json
parameters:
- in: path
name: cluster_id
description: The cluster ID
type: integer
format: int32
required: true
responses:
'200':
description: Get a single instance cluster
schema:
$ref: '#/definitions/API_Entities_Cluster'
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: getApiV4AdminClustersClusterId
put:
summary: Edit instance cluster
description: This feature was introduced in GitLab 13.2. Updates an existing instance cluster.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: cluster_id
description: The cluster ID
type: integer
format: int32
required: true
- name: putApiV4AdminClustersClusterId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4AdminClustersClusterId'
responses:
'200':
description: Edit instance cluster
schema:
$ref: '#/definitions/API_Entities_Cluster'
'400':
description: Validation error
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: putApiV4AdminClustersClusterId
delete:
summary: Delete instance cluster
description: This feature was introduced in GitLab 13.2. Deletes an existing instance cluster. Does not remove existing resources within the connected Kubernetes cluster.
produces:
- application/json
parameters:
- in: path
name: cluster_id
description: The cluster ID
type: integer
format: int32
required: true
responses:
'403':
description: Forbidden
'204':
description: Delete instance cluster
schema:
$ref: '#/definitions/API_Entities_Cluster'
'404':
description: Not found
tags:
- clusters
operationId: deleteApiV4AdminClustersClusterId
/api/v4/admin/clusters/add:
post:
summary: Add existing instance cluster
description: This feature was introduced in GitLab 13.2. Adds an existing Kubernetes instance cluster.
produces:
- application/json
consumes:
- application/json
parameters:
- name: postApiV4AdminClustersAdd
in: body
required: true
schema:
$ref: '#/definitions/postApiV4AdminClustersAdd'
responses:
'201':
description: Add existing instance cluster
schema:
$ref: '#/definitions/API_Entities_Cluster'
'400':
description: Validation error
'403':
description: Forbidden
'404':
description: Not found
tags:
- clusters
operationId: postApiV4AdminClustersAdd
/api/v4/discover-cert-based-clusters:
get:
summary: Discover all descendant certificate-based clusters in a group
description: This feature was introduced in GitLab 17.9. It will be removed in 18.0.
produces:
- application/json
parameters:
- in: query
name: group_id
description: The group ID to find all certificate-based clusters in the hierarchy
type: integer
format: int32
required: true
responses:
'200':
description: Discover all descendant certificate-based clusters in a group
schema:
$ref: '#/definitions/API_Entities_DiscoveredClusters'
'403':
description: Forbidden
tags:
- clusters
operationId: getApiV4DiscoverCertBasedClusters
definitions:
API_Entities_Cluster:
type: object
properties:
id:
type: string
name:
type: string
created_at:
type: string
domain:
type: string
enabled:
type: string
managed:
type: string
provider_type:
type: string
platform_type:
type: string
environment_scope:
type: string
cluster_type:
type: string
namespace_per_environment:
type: string
user:
$ref: '#/definitions/API_Entities_UserBasic'
platform_kubernetes:
$ref: '#/definitions/API_Entities_Platform_Kubernetes'
provider_gcp:
$ref: '#/definitions/API_Entities_Provider_Gcp'
management_project:
$ref: '#/definitions/API_Entities_ProjectIdentity'
required:
- id
- name
- created_at
- domain
- enabled
- managed
- provider_type
- platform_type
- environment_scope
- cluster_type
- namespace_per_environment
- user
- platform_kubernetes
- provider_gcp
- management_project
description: API_Entities_Cluster model
API_Entities_CustomAttribute:
type: object
properties:
key:
type: string
example: foo
value:
type: string
example: bar
required:
- key
- value
description: API_Entities_CustomAttribute model
putApiV4AdminClustersClusterId:
type: object
properties:
name:
type: string
description: Cluster name
enabled:
type: boolean
description: Enable or disable Gitlab's connection to your Kubernetes cluster
environment_scope:
type: string
description: The associated environment to the cluster
namespace_per_environment:
type: boolean
description: Deploy each environment to a separate Kubernetes namespace
default: true
domain:
type: string
description: Cluster base domain
management_project_id:
type: integer
format: int32
description: The ID of the management project
managed:
type: boolean
description: Determines if GitLab will manage namespaces and service accounts for this cluster
platform_kubernetes_attributes:
type: object
description: Platform Kubernetes data
properties:
api_url:
type: string
description: URL to access the Kubernetes API
token:
type: string
description: Token to authenticate against Kubernetes
ca_cert:
type: string
description: TLS certificate (needed if API is using a self-signed TLS certificate)
namespace:
type: string
description: Unique namespace related to Project
description: Edit instance cluster
API_Entities_ClusterGroup:
type: object
properties:
id:
type: string
name:
type: string
created_at:
type: string
domain:
type: string
enabled:
type: string
managed:
type: string
provider_type:
type: string
platform_type:
type: string
environment_scope:
type: string
cluster_type:
type: string
namespace_per_environment:
type: string
user:
$ref: '#/definitions/API_Entities_UserBasic'
platform_kubernetes:
$ref: '#/definitions/API_Entities_Platform_Kubernetes'
provider_gcp:
$ref: '#/definitions/API_Entities_Provider_Gcp'
management_project:
$ref: '#/definitions/API_Entities_ProjectIdentity'
group:
$ref: '#/definitions/API_Entities_BasicGroupDetails'
required:
- id
- name
- created_at
- domain
- enabled
- managed
- provider_type
- platform_type
- environment_scope
- cluster_type
- namespace_per_environment
- user
- platform_kubernetes
- provider_gcp
- management_project
- group
description: API_Entities_ClusterGroup model
API_Entities_UserBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
username:
type: string
example: admin
public_email:
type: string
example: john@example.com
name:
type: string
example: Administrator
state:
type: string
example: active
locked:
type: boolean
avatar_url:
type: string
example: https://gravatar.com/avatar/1
avatar_path:
type: string
example: /user/avatar/28/The-Big-Lebowski-400-400.png
custom_attributes:
type: array
items:
$ref: '#/definitions/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
description: API_Entities_UserBasic model
API_Entities_ProjectIdentity:
type: object
properties:
id:
type: integer
format: int32
example: 1
description:
type: string
example: desc
name:
type: string
example: project1
name_with_namespace:
type: string
example: John Doe / project1
path:
type: string
example: project1
path_with_namespace:
type: string
example: namespace1/project1
created_at:
type: string
format: date-time
example: '2020-05-07T04:27:17.016Z'
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
postApiV4AdminClustersAdd:
type: object
properties:
name:
type: string
description: Cluster name
enabled:
type: boolean
description: Determines if cluster is active or not, defaults to true
default: true
environment_scope:
type: string
description: The associated environment to the cluster
default: '*'
namespace_per_environment:
type: boolean
description: Deploy each environment to a separate Kubernetes namespace
default: true
domain:
type: string
description: Cluster base domain
management_project_id:
type: integer
format: int32
description: The ID of the management project
managed:
type: boolean
description: Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true
default: true
platform_kubernetes_attributes:
type: object
description: Platform Kubernetes data
properties:
api_url:
type: string
description: URL to access the Kubernetes API
token:
type: string
description: Token to authenticate against Kubernetes
ca_cert:
type: string
description: TLS certificate (needed if API is using a self-signed TLS certificate)
namespace:
type: string
description: Unique namespace related to Project
authorization_type:
type: string
description: Cluster authorization type, defaults to RBAC
enum:
- unknown_authorization
- rbac
- abac
default: rbac
required:
- api_url
- token
required:
- name
- platform_kubernetes_attributes
description: Add existing instance cluster
API_Entities_Platform_Kubernetes:
type: object
properties:
api_url:
type: string
namespace:
type: string
authorization_type:
type: string
ca_cert:
type: string
required:
- api_url
- namespace
- authorization_type
- ca_cert
API_Entities_NamespaceBasic:
type: object
properties:
id:
type: integer
format: int32
example: 2
name:
type: string
example: project
path:
type: string
example: my_project
kind:
type: string
example: project
full_path:
type: string
example: group/my_project
parent_id:
type: integer
format: int32
example: 1
avatar_url:
type: string
example: https://example.com/avatar/12345
web_url:
type: string
example: https://example.com/group/my_project
required:
- id
- name
- path
- kind
- full_path
- parent_id
- avatar_url
- web_url
putApiV4GroupsIdClustersClusterId:
type: object
properties:
name:
type: string
description: Cluster name
enabled:
type: boolean
description: Determines if cluster is active or not
domain:
type: string
description: Cluster base domain
environment_scope:
type: string
description: The associated environment to the cluster
namespace_per_environment:
type: boolean
description: Deploy each environment to a separate Kubernetes namespace
default: true
management_project_id:
type: integer
format: int32
description: The ID of the management project
managed:
type: boolean
description: Determines if GitLab will manage namespaces and service accounts for this cluster
platform_kubernetes_attributes:
type: object
description: Platform Kubernetes data
properties:
api_url:
type: string
description: URL to access the Kubernetes API
token:
type: string
description: Token to authenticate against Kubernetes
ca_cert:
type: string
description: TLS certificate (needed if API is using a self-signed TLS certificate)
namespace:
type: string
description: Unique namespace related to Group
description: Edit group cluster
API_Entities_BasicProjectDetails:
type: object
properties:
id:
type: integer
format: int32
example: 1
description:
type: string
example: desc
name:
type: string
example: project1
name_with_namespace:
type: string
example: John Doe / project1
path:
type: string
example: project1
path_with_namespace:
type: string
example: namespace1/project1
created_at:
type: string
format: date-time
example: '2020-05-07T04:27:17.016Z'
default_branch:
type: string
example: main
tag_list:
type: array
items:
type: string
example:
- tag
topics:
type: array
items:
type: string
example:
- topic
ssh_url_to_repo:
type: string
example: git@gitlab.example.com:gitlab/gitlab.git
http_url_to_repo:
type: string
example: https://gitlab.example.com/gitlab/gitlab.git
web_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab
readme_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab/blob/master/README.md
forks_count:
type: integer
format: int32
example: 1
license_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab/blob/master/LICENCE
license:
$ref: '#/definitions/API_Entities_LicenseBasic'
avatar_url:
type: string
example: http://example.com/uploads/project/avatar/3/uploads/avatar.png
star_count:
type: integer
format: int32
example: 1
last_activity_at:
type: string
format: date-time
example: '2013-09-30T13:46:02Z'
visibility:
type: string
example: public
namespace:
$ref: '#/definitions/API_Entities_NamespaceBasic'
custom_attributes:
$ref: '#/definitions/API_Entities_CustomAttribute'
repository_storage:
type: string
example: default
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
- tag_list
- topics
- ssh_url_to_repo
- http_url_to_repo
- web_url
- avatar_url
- star_count
- last_activity_at
- visibility
- namespace
description: API_Entities_BasicProjectDetails model
API_Entities_Provider_Gcp:
type: object
properties:
cluster_id:
type: string
status_name:
type: string
gcp_project_id:
type: string
zone:
type: string
machine_type:
type: string
num_nodes:
type: string
endpoint:
type: string
required:
- cluster_id
- status_name
- gcp_project_id
- zone
- machine_type
- num_nodes
- endpoint
API_Entities_ClusterProject:
type: object
properties:
id:
type: string
name:
type: string
created_at:
type: string
domain:
type: string
enabled:
type: string
managed:
type: string
provider_type:
type: string
platform_type:
type: string
environment_scope:
type: string
cluster_type:
type: string
namespace_per_environment:
type: string
user:
$ref: '#/definitions/API_Entities_UserBasic'
platform_kubernetes:
$ref: '#/definitions/API_Entities_Platform_Kubernetes'
provider_gcp:
$ref: '#/definitions/API_Entities_Provider_Gcp'
management_project:
$ref: '#/definitions/API_Entities_ProjectIdentity'
project:
$ref: '#/definitions/API_Entities_BasicProjectDetails'
required:
- id
- name
- created_at
- domain
- enabled
- managed
- provider_type
- platform_type
- environment_scope
- cluster_type
- namespace_per_environment
- user
- platform_kubernetes
- provider_gcp
- management_project
- project
description: API_Entities_ClusterProject model
postApiV4GroupsIdClustersUser:
type: object
properties:
name:
type: string
description: Cluster name
enabled:
type: boolean
description: Determines if cluster is active or not, defaults to true
default: true
environment_scope:
type: string
description: The associated environment to the cluster
default: '*'
namespace_per_environment:
type: boolean
description: Deploy each environment to a separate Kubernetes namespace
default: true
domain:
type: string
description: Cluster base domain
management_project_id:
type: integer
format: int32
description: The ID of the management project
managed:
type: boolean
description: Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true
default: true
platform_kubernetes_attributes:
type: object
description: Platform Kubernetes data
properties:
api_url:
type: string
description: URL to access the Kubernetes API
token:
type: string
description: Token to authenticate against Kubernetes
ca_cert:
type: string
description: TLS certificate (needed if API is using a self-signed TLS certificate)
namespace:
type: string
description: Unique namespace related to Group
authorization_type:
type: string
description: Cluster authorization type, defaults to RBAC
enum:
- unknown_authorization
- rbac
- abac
default: rbac
required:
- api_url
- token
required:
- name
- platform_kubernetes_attributes
description: Add existing cluster to group
putApiV4ProjectsIdClustersClusterId:
type: object
properties:
name:
type: string
description: Cluster name
domain:
type: string
description: Cluster base domain
environment_scope:
type: string
description: The associated environment to the cluster
namespace_per_environment:
type: boolean
description: Deploy each environment to a separate Kubernetes namespace
default: true
management_project_id:
type: integer
format: int32
description: The ID of the management project
enabled:
type: boolean
description: Determines if cluster is active or not
managed:
type: boolean
description: Determines if GitLab will manage namespaces and service accounts for this cluster
platform_kubernetes_attributes:
type: object
description: Platform Kubernetes data
properties:
api_url:
type: string
description: URL to access the Kubernetes API
token:
type: string
description: Token to authenticate against Kubernetes
ca_cert:
type: string
description: TLS certificate (needed if API is using a self-signed TLS certificate)
namespace:
type: string
description: Unique namespace related to Project
description: Edit project cluster
API_Entities_DiscoveredClusters:
type: object
properties:
groups:
type: string
projects:
type: string
required:
- groups
- projects
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-clusters-api-openapi.yml