getCluster

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

이 가이드는 API 명세를 기반으로 AI가 자동 생성했습니다.

VPC 환경에서 이용 가능합니다.

Ncloud 표준 표현을 적용한 API입니다.

클러스터의 전체 필드를 조회합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
GET	/clusters/{clusterName}

요청 헤더

Cloud DB Serverless API에서 공통으로 사용하는 헤더에 대한 정보는 Cloud DB Serverless 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`clusterName`	String	Required	클러스터 이름 (cluster의 name — 3~30자, 소문자/숫자/하이픈) 패턴: `^[a-z0-9-]+$` 길이: 3 ~ 30 <예시> new-cluster

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request GET 'https://clouddb-serverless.apigw.ntruss.com/mysql/v1/clusters/new-cluster' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`cluster`	Cluster	-	클러스터

Cluster

DB 클러스터

필드	타입	필수 여부	설명
`name`	String	-	클러스터 이름 (하이픈 시작/끝 불가, 예약 prefix 금지, 멤버 내 유일, 생성 후 변경 불가) 패턴: `^[a-z0-9-]+$` 길이: 3 ~ 30 <예시> new-cluster (읽기 전용)
`storageType`	String	-	데이터 스토리지 타입 `CB2` `CB2`: 현재 제공하는 유일한 스토리지 타입 <예시> CB2
`port`	Integer (int32)	-	DB 접속 포트 <예시> 3306
`vpcNo`	Integer (int64)	-	VPC 번호 <예시> 12345
`vpcName`	String	-	클러스터가 배치된 VPC의 이름 <예시> my-vpc (읽기 전용)
`writeEndpoint`	String	-	쓰기 엔드포인트 <예시> 10.1.2.6 (읽기 전용)
`readEndpoint`	String	-	읽기 엔드포인트 <예시> 10.1.2.7 (읽기 전용)
`endpoints`	List<ClusterEndpoint>	-	인터페이스 상세 (읽기 전용)
`multiZone`	Boolean	-	멀티 존 구성 여부 `true` \| `false` `true`: 백업 존에 복제본 배치 `false`: 단일 존 구성 <예시> false
`primaryZoneCode`	String \| null	-	주 인스턴스가 배치된 존 코드 (배치 전이면 null) <예시> KR-1 (읽기 전용)
`backupZoneCode`	String \| null	-	멀티 존 구성 시 백업 복제본이 배치된 존 코드 (단일 존이면 null) (읽기 전용)
`unit`	UnitRange	-	컴퓨팅 unit
`replica`	Object	-	복제본 현황 (읽기 전용)
`replica.target`	Integer (int32)	-	목표 복제본 수 <예시> 2
`replica.current`	Integer (int32)	-	현재 복제본 수 <예시> 2
`replica.ready`	Integer (int32)	-	준비된 복제본 수 <예시> 2
`replica.min`	Integer (int32)	-	최솟값 <예시> 1
`replica.max`	Integer (int32)	-	최댓값 <예시> 4
`autoScale`	AutoscaleConfig	-	Auto Scaling 설정 (수평·수직 확장 조건)
`backupConfig`	BackupConfig	-	자동 백업 설정 (백업 시각·보관일)
`status`	String	-	클러스터 상태 `CREATING` \| `RUNNING` \| `MODIFYING` \| `PAUSED` \| `DELETING` \| `FAILED` `CREATING`: 생성 중인 상태 `RUNNING`: 정상 기동되어 접속 가능한 상태 `MODIFYING`: 설정 변경을 적용 중인 상태 `PAUSED`: 일시 정지된 상태 `DELETING`: 삭제 중인 상태 `FAILED`: 오류로 중단된 상태 <예시> RUNNING (읽기 전용)
`ready`	Boolean	-	목표 복제본이 모두 서비스 가능한 상태인지 여부 `true` \| `false` `true`: 접속 가능 `false`: 일부 복제본 준비 중 <예시> true (읽기 전용)
`createdDateTime`	String (date-time)	-	클러스터 생성 시각 (RFC3339 UTC) <예시> 2026-07-01T09:00:00Z (읽기 전용)
`startDateTime`	String (date-time)	-	클러스터가 기동되어 서비스 가능해진 시각 (RFC3339 UTC) <예시> 2026-07-01T09:05:00Z (읽기 전용)
`highAvailability`	Boolean	-	고가용성(자동 장애 조치) 사용 여부 `true` \| `false` `true`: 사용 `false`: 미사용 <예시> true
`engineVersion`	String	-	DB 엔진 버전 <예시> 8.4.5
`clusterNo`	Integer (int64)	-	클러스터 번호 (내부 숫자 식별자, 참고용 — API 경로 식별자는 name) <예시> 100001 (읽기 전용)

ClusterEndpoint

클러스터 엔드포인트(인터페이스) 상세

필드	타입	필수 여부	설명
`interfaceName`	String	-	네트워크 인터페이스 이름 <예시> new-cluster-rw
`interfaceType`	String	-	엔드포인트 용도 `READ_WRITE` \| `READ_ONLY` `READ_WRITE`: 쓰기. Primary에 연결 `READ_ONLY`: 읽기. Replica에 연결 <예시> READ_WRITE
`subnetNo`	Integer (int64)	-	서브넷 번호 <예시> 67890
`subnetName`	String	-	인터페이스가 배치된 서브넷 이름 <예시> my-subnet
`zoneCode`	String	-	인터페이스가 배치된 존 코드 <예시> KR-1
`accessControlGroupNo`	Integer (int64)	-	인터페이스에 적용된 ACG(Access Control Group) 번호 <예시> 1111
`accessControlGroupName`	String	-	인터페이스에 적용된 ACG 이름 <예시> my-acg

UnitRange

컴퓨팅 unit 범위 (0.5 단위, 1 이상, min ≤ max)

필드	타입	필수 여부	설명
`min`	Number (double)	-	최솟값 범위: 1 ~ 0.5의 배수 <예시> 1
`max`	Number (double)	-	최댓값 범위: 1 ~ 0.5의 배수 <예시> 3

AutoscaleConfig

Auto Scaling 설정

필드	타입	필수 여부	설명
`scaleOut`	Object	-	수평 확장 (replica 수)
`scaleOut.enabled`	Boolean	-	수평 확장 활성화 여부 `true` \| `false` `true`: 활성화 `false`: 비활성화 <예시> true
`scaleOut.thresholdConnection`	Integer (int32) \| null	-	연결 수 임계값 (thresholdCpu와 상호 배타) 범위: 500 ~ 30,000
`scaleOut.thresholdCpu`	Integer (int32) \| null	-	CPU 사용률 임계값 (%) (thresholdConnection과 상호 배타) 범위: 30 ~ 99
`scaleOut.replica`	Object	-	복제본 수 범위 (정책 허용 범위 내)
`scaleOut.replica.min`	Integer (int32)	-	최솟값 <예시> 1
`scaleOut.replica.max`	Integer (int32)	-	최댓값 <예시> 4
`scaleUp`	Object	-	수직 확장 (unit)
`scaleUp.enabled`	Boolean	-	수직 확장 활성화 여부 `true` \| `false` `true`: 활성화 `false`: 비활성화 <예시> true
`scaleUp.unit`	Object	-	unit 범위 (변경은 updateCluster) (읽기 전용)
`scaleUp.unit.min`	Number (double)	-	최솟값 범위: 1 ~ 0.5의 배수 <예시> 1
`scaleUp.unit.max`	Number (double)	-	최댓값 범위: 1 ~ 0.5의 배수 <예시> 3
`scaleIn`	Object	-	축소 임계값 (시스템 산출) (읽기 전용)
`scaleIn.thresholdConnection`	Integer (int32)	-	연결 수 임계값 <예시> 500
`scaleIn.thresholdCpu`	Integer (int32)	-	CPU 사용률 임계값 (%) <예시> 70

BackupConfig

자동 백업 설정

필드	타입	필수 여부	설명
`backupAuto`	Boolean	-	자동 백업 시각 지정 방식 `true` \| `false` `true`: 상품 지정 시각에 백업 (backupTime 무시) `false`: backupTime에 지정한 시각에 백업 기본값: true <예시> true
`backupTime`	String \| null	-	HH:MM (UTC). backupAuto=false 시 필수 패턴: `^([01][0-9]\|2[0-3]):[0-5][0-9]$` <예시> 02:00
`retentionDays`	Integer (int32)	-	백업 보관일 범위: 1 ~ 30 <예시> 3

응답 상태 코드

Cloud DB Serverless API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Cloud DB Serverless 응답 상태 코드를 참조해 주십시오.

이 API에만 해당하는 응답 상태 코드는 다음과 같습니다.

HTTP 상태 코드	코드	메시지	설명
200	-	-	클러스터 상세
400	InvalidParameter	The specified parameter is invalid.	파라미터 값이 허용 범위나 형식을 벗어난 경우

응답 예시

응답 예시는 다음과 같습니다.

{
  "cluster": {
    "name": "new-cluster",
    "storageType": "CB2",
    "port": 3306,
    "vpcNo": 12345,
    "vpcName": "my-vpc",
    "writeEndpoint": "10.1.2.6",
    "readEndpoint": "10.1.2.7",
    "endpoints": [
      {
        "interfaceName": "new-cluster-rw",
        "interfaceType": "READ_WRITE",
        "subnetNo": 67890,
        "subnetName": "my-subnet",
        "zoneCode": "KR-1",
        "accessControlGroupNo": 1111,
        "accessControlGroupName": "my-acg"
      }
    ],
    "multiZone": false,
    "primaryZoneCode": "KR-1",
    "backupZoneCode": "string",
    "unit": {
      "min": 1,
      "max": 3
    },
    "replica": {
      "target": 2,
      "current": 2,
      "ready": 2,
      "min": 1,
      "max": 4
    },
    "autoScale": {
      "scaleOut": {
        "enabled": true,
        "thresholdConnection": "integer",
        "thresholdCpu": "integer",
        "replica": {
          "min": 1,
          "max": 4
        }
      },
      "scaleUp": {
        "enabled": true,
        "unit": {
          "min": 1,
          "max": 3
        }
      },
      "scaleIn": {
        "thresholdConnection": 500,
        "thresholdCpu": 70
      }
    },
    "backupConfig": {
      "backupAuto": true,
      "backupTime": "02:00",
      "retentionDays": 3
    },
    "status": "RUNNING",
    "ready": true,
    "createdDateTime": "2026-07-01T09:00:00Z",
    "startDateTime": "2026-07-01T09:05:00Z",
    "highAvailability": true,
    "engineVersion": "8.4.5",
    "clusterNo": 100001
  }
}