- List group clusters
- Get a single group cluster
- Add existing cluster to group
- Edit group cluster
- Delete group cluster
Group clusters API
Introduced in GitLab 12.1.
Note:
User will need at least maintainer access for the group to use these endpoints.
List group clusters
Returns a list of group clusters.
GET /groups/:id/clusters
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group |
Example request:
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/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":"group_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",
"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 group cluster
Gets a single group cluster.
GET /groups/:id/clusters/:cluster_id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group |
cluster_id
| integer | yes | The ID of the cluster |
Example request:
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/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":"group_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",
"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"
},
"group":
{
"id":26,
"name":"group-with-clusters-api",
"web_url":"https://gitlab.example.com/group-with-clusters-api"
}
}
Add existing cluster to group
Adds an existing Kubernetes cluster to the group.
POST /groups/:id/clusters/user
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group |
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[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/groups/26/clusters/user \
-H "Accept: application/json" \
-H "Content-Type:application/json" \
--request POST --data '{"name":"cluster-5", "platform_kubernetes_attributes":{"api_url":"https://35.111.51.20","token":"12345","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":"group_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",
"authorization_type":"rbac",
"ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"
},
"management_project":null,
"group":
{
"id":26,
"name":"group-with-clusters-api",
"web_url":"https://gitlab.example.com/root/group-with-clusters-api"
}
}
Edit group cluster
Updates an existing group cluster.
PUT /groups/:id/clusters/:cluster_id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group |
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. |
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 group” endpoint.Example request:
curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/24 \
-H "Content-Type:application/json" \
--request 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":"group_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",
"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"
},
"group":
{
"id":26,
"name":"group-with-clusters-api",
"web_url":"https://gitlab.example.com/group-with-clusters-api"
}
}
Delete group cluster
Deletes an existing group cluster.
DELETE /groups/:id/clusters/:cluster_id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group |
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/groups/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