인스턴스 클러스터 API (인증서 기반) (deprecated)

요약

이 기능은 GitLab 14.5에서 deprecated되었습니다. 인스턴스 레벨 Kubernetes 클러스터를 사용하면 Kubernetes 클러스터를 GitLab 인스턴스에 연결하고 인스턴스 내 모든 프로젝트에서 동일한 클러스터를 사용할 수 있습니다.

Warning

이 기능은 GitLab 14.5에서 deprecated되었습니다.

인스턴스 레벨 Kubernetes 클러스터를 사용하면 Kubernetes 클러스터를 GitLab 인스턴스에 연결하고 인스턴스 내 모든 프로젝트에서 동일한 클러스터를 사용할 수 있습니다.

이 엔드포인트를 사용하려면 관리자 권한이 필요합니다.

인스턴스 클러스터 목록 조회#

모든 인스턴스 클러스터 목록을 조회합니다.

GET /admin/clusters

요청 예시:

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

응답 예시:

[
  {
    "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",
    ...
  }
]

단일 인스턴스 클러스터 조회#

단일 인스턴스 클러스터를 조회합니다.

파라미터:

속성	타입	필수 여부	설명
`cluster_id`	integer	yes	클러스터의 ID

GET /admin/clusters/:cluster_id

요청 예시:

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

응답 예시:

{
  "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
}

인스턴스 클러스터 생성#

기존 Kubernetes 클러스터를 추가하여 인스턴스 클러스터를 생성합니다.

POST /admin/clusters/add

파라미터:

속성	타입	필수 여부	설명
`name`	string	yes	클러스터의 이름
`domain`	string	no	클러스터의 기본 도메인
`environment_scope`	string	no	클러스터에 연결된 환경. 기본값은 `*`
`management_project_id`	integer	no	클러스터의 관리 프로젝트 ID
`enabled`	boolean	no	클러스터의 활성화 여부. 기본값은 `true`
`managed`	boolean	no	GitLab이 이 클러스터의 네임스페이스와 서비스 계정을 관리할지 여부. 기본값은 `true`
`platform_kubernetes_attributes[api_url]`	string	yes	Kubernetes API에 접근하기 위한 URL
`platform_kubernetes_attributes[token]`	string	yes	Kubernetes 인증에 사용할 토큰
`platform_kubernetes_attributes[ca_cert]`	string	no	TLS 인증서. API가 자체 서명된 TLS 인증서를 사용하는 경우 필수
`platform_kubernetes_attributes[namespace]`	string	no	프로젝트와 관련된 고유 네임스페이스
`platform_kubernetes_attributes[authorization_type]`	string	no	클러스터 인증 유형: `rbac`, `abac` 또는 `unknown_authorization`. 기본값은 `rbac`

요청 예시:

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"

응답 예시:

{
  "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
}

인스턴스 클러스터 업데이트#

기존 인스턴스 클러스터를 업데이트합니다.

PUT /admin/clusters/:cluster_id

파라미터:

속성	타입	필수 여부	설명
`cluster_id`	integer	yes	클러스터의 ID
`name`	string	no	클러스터의 이름
`domain`	string	no	클러스터의 기본 도메인
`environment_scope`	string	no	클러스터에 연결된 환경
`management_project_id`	integer	no	클러스터의 관리 프로젝트 ID
`enabled`	boolean	no	클러스터의 활성화 여부
`managed`	boolean	no	GitLab이 이 클러스터의 네임스페이스와 서비스 계정을 관리할지 여부
`platform_kubernetes_attributes[api_url]`	string	no	Kubernetes API에 접근하기 위한 URL
`platform_kubernetes_attributes[token]`	string	no	Kubernetes 인증에 사용할 토큰
`platform_kubernetes_attributes[ca_cert]`	string	no	TLS 인증서. API가 자체 서명된 TLS 인증서를 사용하는 경우 필수
`platform_kubernetes_attributes[namespace]`	string	no	프로젝트와 관련된 고유 네임스페이스

Note

name, api_url, ca_cert, token은 기존 Kubernetes 클러스터 추가 옵션이나 인스턴스 클러스터 생성 엔드포인트를 통해 추가된 클러스터에서만 업데이트할 수 있습니다.

요청 예시:

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"

응답 예시:

{
  "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
}

인스턴스 클러스터 삭제#

기존 인스턴스 클러스터를 삭제합니다. 연결된 Kubernetes 클러스터의 기존 리소스는 제거하지 않습니다.

DELETE /admin/clusters/:cluster_id

파라미터:

속성	타입	필수 여부	설명
`cluster_id`	integer	yes	클러스터의 ID

요청 예시:

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

인스턴스 클러스터 API (인증서 기반) (deprecated)

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

원문 보기

번역일: 2026-05-22

요약

Warning

이 기능은 GitLab 14.5에서 deprecated되었습니다.

이 엔드포인트를 사용하려면 관리자 권한이 필요합니다.

인스턴스 클러스터 목록 조회#

모든 인스턴스 클러스터 목록을 조회합니다.

GET /admin/clusters

요청 예시:

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

응답 예시:

[
  {
    "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",
    ...
  }
]

단일 인스턴스 클러스터 조회#

단일 인스턴스 클러스터를 조회합니다.

파라미터:

속성	타입	필수 여부	설명
`cluster_id`	integer	yes	클러스터의 ID

GET /admin/clusters/:cluster_id

요청 예시:

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

응답 예시:

{
  "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
}

인스턴스 클러스터 생성#

기존 Kubernetes 클러스터를 추가하여 인스턴스 클러스터를 생성합니다.

POST /admin/clusters/add

파라미터:

속성	타입	필수 여부	설명
`name`	string	yes	클러스터의 이름
`domain`	string	no	클러스터의 기본 도메인
`environment_scope`	string	no	클러스터에 연결된 환경. 기본값은 `*`
`management_project_id`	integer	no	클러스터의 관리 프로젝트 ID
`enabled`	boolean	no	클러스터의 활성화 여부. 기본값은 `true`
`managed`	boolean	no	GitLab이 이 클러스터의 네임스페이스와 서비스 계정을 관리할지 여부. 기본값은 `true`
`platform_kubernetes_attributes[api_url]`	string	yes	Kubernetes API에 접근하기 위한 URL
`platform_kubernetes_attributes[token]`	string	yes	Kubernetes 인증에 사용할 토큰
`platform_kubernetes_attributes[ca_cert]`	string	no	TLS 인증서. API가 자체 서명된 TLS 인증서를 사용하는 경우 필수
`platform_kubernetes_attributes[namespace]`	string	no	프로젝트와 관련된 고유 네임스페이스
`platform_kubernetes_attributes[authorization_type]`	string	no	클러스터 인증 유형: `rbac`, `abac` 또는 `unknown_authorization`. 기본값은 `rbac`

요청 예시:

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"

응답 예시:

{
  "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
}

인스턴스 클러스터 업데이트#

기존 인스턴스 클러스터를 업데이트합니다.

PUT /admin/clusters/:cluster_id

파라미터:

속성	타입	필수 여부	설명
`cluster_id`	integer	yes	클러스터의 ID
`name`	string	no	클러스터의 이름
`domain`	string	no	클러스터의 기본 도메인
`environment_scope`	string	no	클러스터에 연결된 환경
`management_project_id`	integer	no	클러스터의 관리 프로젝트 ID
`enabled`	boolean	no	클러스터의 활성화 여부
`managed`	boolean	no	GitLab이 이 클러스터의 네임스페이스와 서비스 계정을 관리할지 여부
`platform_kubernetes_attributes[api_url]`	string	no	Kubernetes API에 접근하기 위한 URL
`platform_kubernetes_attributes[token]`	string	no	Kubernetes 인증에 사용할 토큰
`platform_kubernetes_attributes[ca_cert]`	string	no	TLS 인증서. API가 자체 서명된 TLS 인증서를 사용하는 경우 필수
`platform_kubernetes_attributes[namespace]`	string	no	프로젝트와 관련된 고유 네임스페이스

Note

요청 예시:

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"

응답 예시:

{
  "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
}

인스턴스 클러스터 삭제#

기존 인스턴스 클러스터를 삭제합니다. 연결된 Kubernetes 클러스터의 기존 리소스는 제거하지 않습니다.

DELETE /admin/clusters/:cluster_id

파라미터:

속성	타입	필수 여부	설명
`cluster_id`	integer	yes	클러스터의 ID

요청 예시:

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