- List project clusters
- Get a single project cluster
- Add existing cluster to project
- Edit project cluster
- Delete project cluster
Project clusters API
Introduced in GitLab 11.7.
Note:
User will need at least maintainer access to use these endpoints.
List project clusters
Returns a list of project clusters.
GET /projects/:id/clusters
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | The ID of the project owned by the authenticated user |
Example request:
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters
Example response:
[
{
"id":18,
"name":"cluster-1",
"domain":"example.com",
"created_at":"2019-01-02T20:18:12.563Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://104.197.68.152",
"namespace":"cluster-1-namespace",
"authorization_type":"rbac",
"ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
},
"management_project":
{
"id":2,
"description":null,
"name":"project2",
"name_with_namespace":"John Doe8 / project2",
"path":"project2",
"path_with_namespace":"namespace2/project2",
"created_at":"2019-10-11T02:55:54.138Z"
}
},
{
"id":19,
"name":"cluster-2",
...
}
]
Get a single project cluster
Gets a single project cluster.
GET /projects/:id/clusters/:cluster_id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | The ID of the project owned by the authenticated user |
cluster_id
| integer | yes | The ID of the cluster |
Example request:
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/18
Example response:
{
"id":18,
"name":"cluster-1",
"domain":"example.com",
"created_at":"2019-01-02T20:18:12.563Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://104.197.68.152",
"namespace":"cluster-1-namespace",
"authorization_type":"rbac",
"ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
},
"management_project":
{
"id":2,
"description":null,
"name":"project2",
"name_with_namespace":"John Doe8 / project2",
"path":"project2",
"path_with_namespace":"namespace2/project2",
"created_at":"2019-10-11T02:55:54.138Z"
},
"project":
{
"id":26,
"description":"",
"name":"project-with-clusters-api",
"name_with_namespace":"Administrator / project-with-clusters-api",
"path":"project-with-clusters-api",
"path_with_namespace":"root/project-with-clusters-api",
"created_at":"2019-01-02T20:13:32.600Z",
"default_branch":null,
"tag_list":[],
"ssh_url_to_repo":"ssh://gitlab.example.com/root/project-with-clusters-api.git",
"http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git",
"web_url":"https://gitlab.example.com/root/project-with-clusters-api",
"readme_url":null,
"avatar_url":null,
"star_count":0,
"forks_count":0,
"last_activity_at":"2019-01-02T20:13:32.600Z",
"namespace":
{
"id":1,
"name":"root",
"path":"root",
"kind":"user",
"full_path":"root",
"parent_id":null
}
}
}
Add existing cluster to project
Adds an existing Kubernetes cluster to the project.
POST /projects/:id/clusters/user
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | The ID of the project owned by the authenticated user |
name
| string | yes | The name of the cluster |
domain
| string | no | The base domain of the cluster |
management_project_id
| integer | no | The ID of the management project 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[namespace]
| string | no | The unique namespace related to the project |
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 *
|
Example request:
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/user \
-H "Accept: application/json" \
-H "Content-Type:application/json" \
-X POST --data '{"name":"cluster-5", "platform_kubernetes_attributes":{"api_url":"https://35.111.51.20","token":"12345","namespace":"cluster-5-namespace","ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"}}'
Example response:
{
"id":24,
"name":"cluster-5",
"created_at":"2019-01-03T21:53:40.610Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://35.111.51.20",
"namespace":"cluster-5-namespace",
"authorization_type":"rbac",
"ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
},
"management_project":null,
"project":
{
"id":26,
"description":"",
"name":"project-with-clusters-api",
"name_with_namespace":"Administrator / project-with-clusters-api",
"path":"project-with-clusters-api",
"path_with_namespace":"root/project-with-clusters-api",
"created_at":"2019-01-02T20:13:32.600Z",
"default_branch":null,
"tag_list":[],
"ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git",
"http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git",
"web_url":"https://gitlab.example.com/root/project-with-clusters-api",
"readme_url":null,
"avatar_url":null,
"star_count":0,
"forks_count":0,
"last_activity_at":"2019-01-02T20:13:32.600Z",
"namespace":
{
"id":1,
"name":"root",
"path":"root",
"kind":"user",
"full_path":"root",
"parent_id":null
}
}
}
Edit project cluster
Updates an existing project cluster.
PUT /projects/:id/clusters/:cluster_id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | The ID of the project owned by the authenticated user |
cluster_id
| integer | yes | The ID of the cluster |
name
| string | no | The name of the cluster |
domain
| string | no | The base domain of the cluster |
management_project_id
| integer | no | The ID of the management project 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. |
platform_kubernetes_attributes[namespace]
| string | no | The unique namespace related to the project |
environment_scope
| string | no | The associated environment to the cluster |
Note:
name
, api_url
, ca_cert
and token
can only be updated if the cluster was added
through the “Add existing Kubernetes cluster” option or
through the “Add existing cluster to project” endpoint.Example request:
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/24 \
-H "Content-Type:application/json" \
-X PUT --data '{"name":"new-cluster-name","domain":"new-domain.com","api_url":"https://new-api-url.com"}'
Example response:
{
"id":24,
"name":"new-cluster-name",
"domain":"new-domain.com",
"created_at":"2019-01-03T21:53:40.610Z",
"provider_type":"user",
"platform_type":"kubernetes",
"environment_scope":"*",
"cluster_type":"project_type",
"user":
{
"id":1,
"name":"Administrator",
"username":"root",
"state":"active",
"avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..",
"web_url":"https://gitlab.example.com/root"
},
"platform_kubernetes":
{
"api_url":"https://new-api-url.com",
"namespace":"cluster-5-namespace",
"authorization_type":"rbac",
"ca_cert":null
},
"management_project":
{
"id":2,
"description":null,
"name":"project2",
"name_with_namespace":"John Doe8 / project2",
"path":"project2",
"path_with_namespace":"namespace2/project2",
"created_at":"2019-10-11T02:55:54.138Z"
},
"project":
{
"id":26,
"description":"",
"name":"project-with-clusters-api",
"name_with_namespace":"Administrator / project-with-clusters-api",
"path":"project-with-clusters-api",
"path_with_namespace":"root/project-with-clusters-api",
"created_at":"2019-01-02T20:13:32.600Z",
"default_branch":null,
"tag_list":[],
"ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git",
"http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git",
"web_url":"https://gitlab.example.com/root/project-with-clusters-api",
"readme_url":null,
"avatar_url":null,
"star_count":0,
"forks_count":0,
"last_activity_at":"2019-01-02T20:13:32.600Z",
"namespace":
{
"id":1,
"name":"root",
"path":"root",
"kind":"user",
"full_path":"root",
"parent_id":null
}
}
}
Delete project cluster
Deletes an existing project cluster.
DELETE /projects/:id/clusters/:cluster_id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | The ID of the project owned by the authenticated user |
cluster_id
| integer | yes | The ID of the cluster |
Example request:
curl --request DELETE --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/23
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc