ContextQMD
Back to Gitlabhq

Instance clusters API (certificate-based) (deprecated)

doc/api/instance_clusters.md

18.11.211.7 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

{{< /details >}}

[!warning] This feature was deprecated in GitLab 14.5.

With instance-level Kubernetes clusters, you can connect a Kubernetes cluster to the GitLab instance and use the same cluster across all of the projects within your instance.

Users need administrator access to use these endpoints.

List instance clusters

Lists all instance clusters.

plaintext
GET /admin/clusters

Example request:

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/clusters"

Example response:

json
[
  {
    "id": 9,
    "name": "cluster-1",
    "created_at": "2020-07-14T18:36:10.440Z",
    "managed": true,
    "enabled": true,
    "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",
    ...
  }
]

Retrieve a single instance cluster

Retrieves a single instance cluster.

Parameters:

AttributeTypeRequiredDescription
cluster_idintegeryesThe ID of the cluster
plaintext
GET /admin/clusters/:cluster_id

Example request:

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/clusters/9"

Example response:

json
{
  "id": 9,
  "name": "cluster-1",
  "created_at": "2020-07-14T18:36:10.440Z",
  "managed": true,
  "enabled": true,
  "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
}

Create an instance cluster

Creates an instance cluster by adding an existing Kubernetes cluster.

plaintext
POST /admin/clusters/add

Parameters:

AttributeTypeRequiredDescription
namestringyesThe name of the cluster
domainstringnoThe base domain of the cluster
environment_scopestringnoThe associated environment to the cluster. Defaults to *
management_project_idintegernoThe ID of the management project for the cluster
enabledbooleannoDetermines if cluster is active or not, defaults to true
managedbooleannoDetermines if GitLab manages namespaces and service accounts for this cluster. Defaults to true
platform_kubernetes_attributes[api_url]stringyesThe URL to access the Kubernetes API
platform_kubernetes_attributes[token]stringyesThe token to authenticate against Kubernetes
platform_kubernetes_attributes[ca_cert]stringnoTLS certificate. Required if API is using a self-signed TLS certificate.
platform_kubernetes_attributes[namespace]stringnoThe unique namespace related to the project
platform_kubernetes_attributes[authorization_type]stringnoThe cluster authorization type: rbac, abac or unknown_authorization. Defaults to rbac.

Example request:

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

Example response:

json
{
  "id": 11,
  "name": "cluster-3",
  "created_at": "2020-07-14T18:42:50.805Z",
  "managed": true,
  "enabled": true,
  "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
}

Update an instance cluster

Updates an existing instance cluster.

plaintext
PUT /admin/clusters/:cluster_id

Parameters:

AttributeTypeRequiredDescription
cluster_idintegeryesThe ID of the cluster
namestringnoThe name of the cluster
domainstringnoThe base domain of the cluster
environment_scopestringnoThe associated environment to the cluster
management_project_idintegernoThe ID of the management project for the cluster
enabledbooleannoDetermines if cluster is active or not
managedbooleannoDetermines if GitLab manages namespaces and service accounts for this cluster
platform_kubernetes_attributes[api_url]stringnoThe URL to access the Kubernetes API
platform_kubernetes_attributes[token]stringnoThe token to authenticate against Kubernetes
platform_kubernetes_attributes[ca_cert]stringnoTLS certificate. Required if API is using a self-signed TLS certificate.
platform_kubernetes_attributes[namespace]stringnoThe unique namespace related to the project

[!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 Create an instance cluster endpoint.

Example request:

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

Example response:

json
{
  "id": 9,
  "name": "update-cluster-name",
  "created_at": "2020-07-14T18:36:10.440Z",
  "managed": true,
  "enabled": true,
  "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. Does not remove existing resources within the connected Kubernetes cluster.

plaintext
DELETE /admin/clusters/:cluster_id

Parameters:

AttributeTypeRequiredDescription
cluster_idintegeryesThe ID of the cluster

Example request:

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/clusters/11"