debian-mirror-gitlab/doc/api/instance_clusters.md

Instance clusters API

Introduced in GitLab 13.2.

NOTE: Note: User will need admin access to use these endpoints.

Use these API endpoints with your instance clusters, which enable you to use the same cluster across multiple projects. More information

List instance clusters

Returns a list of instance clusters.

GET /admin/clusters

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/admin/clusters"

Example response:

[
  {
    "id": 9,
    "name": "cluster-1",
    "created_at": "2020-07-14T18:36:10.440Z",
    "domain": null,
    "provider_type": "user",
    "platform_type": "kubernetes",
    "environment_scope": "*",
    "cluster_type": "instance_type",
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/root"
    },
    "platform_kubernetes": {
      "api_url": "https://example.com",
      "namespace": null,
      "authorization_type": "rbac",
      "ca_cert":"-----BEGIN CERTIFICATE-----IxMDM1MV0ZDJkZjM...-----END CERTIFICATE-----"
    },
    "provider_gcp": null,
    "management_project": null
  },
  {
    "id": 10,
    "name": "cluster-2",
    "created_at": "2020-07-14T18:39:05.383Z",
    "domain": null,
    "provider_type": "user",
    "platform_type": "kubernetes",
    "environment_scope": "staging",
    "cluster_type": "instance_type",
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
      "web_url": "https://gitlab.example.com/root"
    },
    "platform_kubernetes": {
      "api_url": "https://example.com",
      "namespace": null,
      "authorization_type": "rbac",
      "ca_cert":"-----BEGIN CERTIFICATE-----LzEtMCadtaLGxcsGAZjM...-----END CERTIFICATE-----"
    },
    "provider_gcp": null,
    "management_project": null
  }
  {
    "id": 11,
    "name": "cluster-3",
    ...
  }
]

Get a single instance cluster

Returns a single instance cluster.

Parameters:

Attribute	Type	Required	Description
cluster_id	integer	yes	The ID of the cluster

GET /admin/clusters/:cluster_id

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/admin/clusters/9"

Example response:

{
  "id": 9,
  "name": "cluster-1",
  "created_at": "2020-07-14T18:36:10.440Z",
  "domain": null,
  "provider_type": "user",
  "platform_type": "kubernetes",
  "environment_scope": "*",
  "cluster_type": "instance_type",
  "user": {
    "id": 1,
    "name": "Administrator",
    "username": "root",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/root"
  },
  "platform_kubernetes": {
    "api_url": "https://example.com",
    "namespace": null,
    "authorization_type": "rbac",
    "ca_cert":"-----BEGIN CERTIFICATE-----IxMDM1MV0ZDJkZjM...-----END CERTIFICATE-----"
  },
  "provider_gcp": null,
  "management_project": null
}

Add existing instance cluster

Adds an existing Kubernetes instance cluster.

POST /admin/clusters/add

Parameters:

Attribute	Type	Required	Description
name	string	yes	The name of the cluster
domain	string	no	The base domain of the cluster
environment_scope	string	no	The associated environment to the cluster. Defaults to *
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.

Example request:

curl --header "Private-Token:<your_access_token>" "http://gitlab.example.com/api/v4/admin/clusters/add" \
-H "Accept:application/json" \
-H "Content-Type:application/json" \
-X POST --data '{"name":"cluster-3", "environment_scope":"production", "platform_kubernetes_attributes":{"api_url":"https://example.com", "token":"12345",  "ca_cert":"-----BEGIN CERTIFICATE-----qpoeiXXZafCM0ZDJkZjM...-----END CERTIFICATE-----"}}'

Example response:

{
  "id": 11,
  "name": "cluster-3",
  "created_at": "2020-07-14T18:42:50.805Z",
  "domain": null,
  "provider_type": "user",
  "platform_type": "kubernetes",
  "environment_scope": "production",
  "cluster_type": "instance_type",
  "user": {
    "id": 1,
    "name": "Administrator",
    "username": "root",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "http://gitlab.example.com:3000/root"
  },
  "platform_kubernetes": {
    "api_url": "https://example.com",
    "namespace": null,
    "authorization_type": "rbac",
    "ca_cert":"-----BEGIN CERTIFICATE-----qpoeiXXZafCM0ZDJkZjM...-----END CERTIFICATE-----"
  },
  "provider_gcp": null,
  "management_project": null
}

Edit instance cluster

Updates an existing instance cluster.

PUT /admin/clusters/:cluster_id

Parameters:

Attribute	Type	Required	Description
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
environment_scope	string	no	The associated environment to 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
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

NOTE: 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 instance cluster endpoint.

Example request:

curl --header "Private-Token: <your_access_token>" "http://gitlab.example.com/api/v4/admin/clusters/9" \
-H "Content-Type:application/json" \
-X PUT --data '{"name":"update-cluster-name", "platform_kubernetes_attributes":{"api_url":"https://new-example.com","token":"new-token"}}'

Example response:

{
  "id": 9,
  "name": "update-cluster-name",
  "created_at": "2020-07-14T18:36:10.440Z",
  "domain": null,
  "provider_type": "user",
  "platform_type": "kubernetes",
  "environment_scope": "*",
  "cluster_type": "instance_type",
  "user": {
    "id": 1,
    "name": "Administrator",
    "username": "root",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/root"
  },
  "platform_kubernetes": {
    "api_url": "https://new-example.com",
    "namespace": null,
    "authorization_type": "rbac",
    "ca_cert":"-----BEGIN CERTIFICATE-----IxMDM1MV0ZDJkZjM...-----END CERTIFICATE-----"
  },
  "provider_gcp": null,
  "management_project": null,
  "project": null
}

Delete instance cluster

Deletes an existing instance cluster.

DELETE /admin/clusters/:cluster_id

Parameters:

Attribute	Type	Required	Description
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/admin/clusters/11"