작업 클러스터 API

일반적으로 Hadoop Eco에서는 클러스터가 특정 작업을 완료하면 상태가 Terminated로 변경되며, 이 상태에서는 클러스터를 더 이상 사용할 수 없습니다. 하지만 작업 클러스터 API를 사용하면 기존에 생성되어 Terminated 상태인 클러스터에서 작업 스케줄링을 반복해서 실행할 수 있습니다.

작업 클러스터 API는 클러스터의 재사용성을 높이고, 필요할 때마다 새로운 클러스터를 생성하지 않고도 기존 클러스터에서 반복적으로 작업을 수행하여 효율적으로 클러스터를 관리할 수 있도록 지원합니다.

작업 클러스터 API는 다음과 같은 과정을 통해 동작합니다:

클러스터 선택: 콘솔에서 재작업할 클러스터를 선택합니다. 이는 기존에 생성되어 있는 클러스터로, Terminated 상태인 클러스터여야 합니다.
Open API Key 발급: 작업 클러스터 API를 사용하려면 카카오클라우드 콘솔에서 해당 클러스터의 Open API Key를 발급받아야 합니다. 이 키는 API 호출 시 클러스터에 접근하고 제어하는 데 필요합니다.
- Open API Key를 발급하면 해당 Open API 클러스터 전용의 보안 그룹이 자동으로 생성되며, API Key를 삭제하면 보안 그룹이 삭제됩니다.
작업 클러스터 API 호출: 발급받은 Open API Key를 사용하여 작업 클러스터 API를 호출합니다. 이를 통해 Terminated 상태의 클러스터에 새로운 작업을 스케줄링하고 실행할 수 있습니다.

API 사용 준비

작업 클러스터 API를 호출하기 위해서는 액세스 키를 발급받아야 하며, 콘솔에서 Hadoop Eco 클러스터의 Open API Key를 발급받아야 합니다.

작업 클러스터 생성

현재 상태가 Terminated인 클러스터에 작업 스케줄링을 반복해서 실행합니다.

Request

Request Syntax

kr-central-1
kr-central-2

(kr-central-1) 작업 클러스터 생성 Request Syntax
curl -X POST 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}' \
    --header 'Hadoop-Eco-Api-Key: {hadoop-eco-api-key}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
          "workerCnt": 2,
          "workerVolumeSize": 50,
          "configHdfsReplication": 2,
          "configHdfsBlockSize": 128,
          "userTaskDeployMode": "cluster",
          "userTaskExecOpts": "--driver-cores 1 --driver-memory 1024m --executor-cores 1 --num-executors 4 --executor-memory 2048m",
          "userTaskExecParams": "-sparkApplicationParams=testParams"
    }'

(kr-central-2) 리전 클러스터 생성 Request Syntax
curl -X POST 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}' \
    --header 'Hadoop-Eco-Api-Key: {hadoop-eco-api-key}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
          "workerCnt": 2,
          "workerVolumeSize": 50,
          "configHdfsReplication": 2,
          "configHdfsBlockSize": 128,
          "userTaskDeployMode": "cluster",
          "userTaskExecOpts": "--driver-cores 1 --driver-memory 1024m --executor-cores 1 --num-executors 4 --executor-memory 2048m",
          "userTaskExecParams": "-sparkApplicationParams=testParams"
    }'

API 호출 방식

메서드	요청 URL
POST (kr-central-1)	`https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}`
POST (kr-central-2)	`https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}`

종류	파라미터	유형	설명
URL	`{cluster-id}`*	String	클러스터의 ID - 카카오클라우드 콘솔 > Analytics > Hadoop Eco > 좌측 Cluster 메뉴 > 클러스터 정보에서 확인 가능

Request Header

Request	유형	설명
`{credential-id}`*	String	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	String	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급 필요
`{hadoop-eco-api-key}`*	String	Open API key - 카카오클라우드 콘솔 > Analytics > Hadoop Eco > 좌측 Cluster 메뉴에서, 클러스터 선택 후 우측 상단의 클러스터 작업 > Open API 키 발급에서 발급 가능 - 자세한 설명은 Open API 키 발급 참고

Request Elements

필수 값은 아니며 기존 클러스터 설정 변경이 필요한 경우 사용할 수 있습니다.

Request	유형	설명
workerCnt	Integer	Hadoop Eco 워커 노드 개수 - 개수: 1 ~ 1,000개
workerVolumeSize	Integer	Hadoop Eco 워커 노드 블록 스토리지 크기 - 크기: 50 ~ 5120GB
configHdfsReplication	Integer	Hadoop Eco HDFS 복제 개수 - 개수: 1 ~ 500개
configHdfsBlockSize	Integer	Hadoop Eco HDFS 블록 크기 - 크기: 1 ~ 1024MB
userTaskDeployMode	String	Hadoop Eco Spark Job Deploy 모드 - 모드: `client`, `cluster`
userTaskExecOpts	String	Hadoop Eco Hive 설정 파라미터
userTaskExecParams	String	Hadoop Eco Job 애플리케이션 파라미터

Response

Response Syntax

클러스터 생성 Response Syntax
{
  "clusterId": "58ceed05-e4f5-4a85-b9a6-e9b79ae8dcdf",
  "clusterName": "test-cluster",
  "requestId": "req-f02cf9abc130410ab365e77511db4318",
  "clusterMainSettingValues": {
    "workerCnt": 1,
    "workerVolumeSize": 50,
    "configHdfsReplication": 1,
    "configHdfsBlockSize": 128,
    "jobType": "hive",
    "userTaskDeployMode": true,
    "userTaskExecOpts": "",
    "userTaskExecParams": ""
  }
}

Response Elements

Response	설명
clusterId	생성된 클러스터 ID
clusterName	생성된 클러스터 이름
requestId	요청 ID
clusterMainSettingValues▼	설정 정보
workerCnt	Hadoop Eco 워커 노드 개수
workerVolumeSize	Hadoop Eco 워커 노드 블록 스토리지 크기
configHdfsReplication	Hadoop Eco HDFS 복제 개수
configHdfsBlockSize	Hadoop Eco HDFS 블록 크기
jobType	작업 유형 - 유형: `Spark`, `Hive`
userTaskDeployMode	Hadoop Eco Spark Job Deploy 모드
userTaskExecOpts	Hadoop Eco Spark or Hive Job 설정 파라미터
userTaskExecParams	Hadoop Eco Spark Application 파라미터

상태 코드

HTTP Status	설명
`200`	성공
`202`	해당 클러스터 작업(생성) 중
`400`	요청 정보 오류
`401`, `403`	인증 실패, 권한 없음
`404`	클러스터를 찾을 수 없음

작업 클러스터 상세 조회

Open API Key가 발급된 클러스터의 상태를 조회할 수 있습니다.

Request

Request Syntax

kr-central-1
kr-central-2

(kr-central-1) 리전 클러스터 상태 조회 Request Syntax
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}' \
    --header 'Hadoop-Eco-Api-Key: {hadoop-eco-api-key}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json'
 
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}?verbose=true' \
    --header 'Hadoop-Eco-Api-Key: {hadoop-eco-api-key}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json'

(kr-central-2) 리전 클러스터 상태 조회 Request Syntax
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}' \
    --header 'Hadoop-Eco-Api-Key: {hadoop-eco-api-key}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json'
 
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}?verbose=true' \
    --header 'Hadoop-Eco-Api-Key: {hadoop-eco-api-key}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json'

API 호출 방식

메서드	요청 URL
GET (Kr-central-1)	`https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}`
GET (Kr-central-2)	`https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}/requests/{request-id}`

Path	유형	설명
`{cluster-id}`*	String	클러스터의 ID - 카카오클라우드 콘솔 > Analytics > Hadoop Eco > 좌측 Cluster 메뉴 > 클러스터 정보에서 확인 가능
`{request-id}`*	String	작업 클러스터 생성 후 응답으로 받은 `requestid`값

Query parameters

Request	유형	설명
verbose	Boolean	verbose 옵션 설정 시 마스터/워커 노드까지 상태 조회 가능 - `true`, `false`

Request Header

Request	유형	설명
`{credential-id}`*	String	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	String	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급 필요
`{hadoop-eco-api-key}`*	String	Open API key - 카카오클라우드 콘솔 > Analytics > Hadoop Eco > 좌측 Cluster 메뉴에서, 클러스터 선택 후 우측 상단의 클러스터 작업 > Open API 키 발급에서 발급 가능 - 자세한 설명은 Open API 키 발급 참고

Response

Response Syntax

verbose=false로 설정 시, 클러스터 정보 조회 Response Syntax
{
  "clusterId": "58ceed05-e4f5-4a85-b9a6-e9b79ae8dcdf",
  "clusterName": "peb-hadoop-ga-test",
  "requestId": "req-ac2aad4c128d4486bbc34fe4862737cb",
  "requestStatus": "Terminate",
  "requestResult": "Success"
}

verbose=true로 설정 시, 클러스터 정보 조회 Response Syntax
{
  "clusterId": "58ceed05-e4f5-4a85-b9a6-e9b79ae8dcdf",
  "clusterName": "peb-hadoop-ga-test",
  "requestId": "req-ac2aad4c128d4486bbc34fe4862737cb",
  "requestStatus": "Terminate",
  "requestResult": "Failure",
  "clusterMeta": {
    "cluster_version": "hde-1.1.0",
    "service_check_timeout": 10,
    "socket_timeout": 5,
    "global_timeout": 1500,
    "monitoring": false,
    "cluster_id": "58ceed05-e4f5-4a85-b9a6-e9b79ae8dcdf",
    "cluster_name": "peb-hadoop-ga-test",
    "cluster_type": "hadoop_single",
    "project": {
      "id": "353094e122d6493d9899f0f2523d4cc1",
      "name": "bigdata",
      "domain": {
        "id": "982fc392699d4385b0b1a9d10b9f2393",
        "name": "kakaoenterprise"
      }
    },
    "master_vm": {
      "host_list": [
        "HadoopMST-peb-hadoop-ga-test-1"
      ],
      "flavor_id": "9b944f27-12fd-4542-8073-e477931c9365",
      "flavor_name": "a1-4-std",
      "key_pair": "bigdata-peb",
      "network": {
        "uuid": "3541a58c-3930-4dcb-8785-0032ff926b80",
        "subnet_id": "be864742-c658-4f7f-8077-9b9138b86df1",
        "security_group_id_list": [
          "73e64d4f-cf71-4be5-8cd5-42e5cb5ccceb",
          "1a21f01b-0437-40ab-a26b-979552555b50"
        ]
      },
      "block_device": {
        "source_type": "image",
        "uuid": "99612215-f9c2-4914-9c76-c8567285675f",
        "volume_size": 50
      },
      "master_active": "HadoopMST-peb-hadoop-ga-test-1",
      "master_standby": "HadoopMST-peb-hadoop-ga-test-1",
      "master_etc": "HadoopMST-peb-hadoop-ga-test-1"
    },
    "worker_vm": {
      "host_list": [],
      "flavor_id": "9b944f27-12fd-4542-8073-e477931c9365",
      "flavor_name": "a1-4-std",
      "key_pair": "bigdata-peb",
      "network": {
        "uuid": "3541a58c-3930-4dcb-8785-0032ff926b80",
        "subnet_id": "be864742-c658-4f7f-8077-9b9138b86df1",
        "security_group_id_list": [
          "73e64d4f-cf71-4be5-8cd5-42e5cb5ccceb",
          "1a21f01b-0437-40ab-a26b-979552555b50"
        ]
      },
      "block_device": {
        "source_type": "image",
        "uuid": "99612215-f9c2-4914-9c76-c8567285675f",
        "volume_size": 50
      }
    },
    "user_cluster_exec_command": {
      "type": "hive",
      "termination_policy": "always",
      "hive_query": "show databases;",
      "exec_opts": "",
      "exec_params": ""
    }
  }
}

Response Elements

Response	설명
clusterId	생성된 클러스터 ID
clusterName	생성된 클러스터 이름
requestId	요청 ID
requestStatus	요청 상태
requestResult	요청 결과
clusterMeta▼	클러스터 메타 정보
cluster_version	생성된 클러스터 버전
service_check_timeout	서비스 timeout 시간
socket_timeout	socket time out 시간
global_timeout	global time out 시간
monitoring	모니터링 활성화 여부
cluster_id	클러스터 ID
cluster_name	클러스터 이름
cluster_type	클러스터 유형
project	프로젝트 정보
id	프로젝트 ID
name	프로젝트 이름
project	도메인 정보
id(domain)	프로젝트가 속한 조직(domain) ID
name(domain)	프로젝트가 속한 조직(domain) 이름
master_vm▼	마스터 노드 정보
host_list	호스트 이름
flavor_id	플레이버 ID
flavor_name	플레이버 이름
key_pair	키 페어 이름
network▼	네트워크 정보
uuid(network)	네트워크의 UUID
subnet_id(network)	서브넷 ID
security_group_id_list	보안 그룹 ID
block_device▼	블록 스토리지 정보
source_type	블록 스토리지 소스 유형
uuid	블록 스토리지의 UUID
volume_size	블록 스토리지의 크기
master_active	마스터 노드의 active 서버 이름
master_standby	마스터 노드의 standby 서버 이름
master_etc	마스터 노드의 etc 서버 이름
worker_vm▼	워커 노드 정보
host_list	호스트 이름
flavor_id	플레이버 ID
flavor_name	플레이버 이름
key_pair	키 페어 이름
network	네트워크 정보
uuid(network)	네트워크 UUID
subnet_id(network)	서브넷 ID
security_group_id_list	보안 그룹 ID
user_cluster_exec_command▼	사용자가 입력한 작업 정보
type	작업 유형 - `Spark`, `Hive`
termination_policy	작업 종료 동작 정책 -`always`, `onSuccess`, `never`
hive_query	Hive 작업 쿼리
exec_opts	Hive, Spark 설정값
exec_params	Spark 애플리케이션 파라미터 값

상태 코드

HTTP Status	설명
`200`	성공
`400`	요청 정보 오류
`401`, `403`	인증 실패, 권한 없음
`404`	클러스터를 찾을 수 없음

API 사용 준비​

작업 클러스터 생성​

Request​

Request Syntax​

API 호출 방식​

Request Header​

Request Elements​

Response​

Response Syntax​

Response Elements​

상태 코드​

작업 클러스터 상세 조회​

Request​

Request Syntax​

API 호출 방식​

Query parameters​

Request Header​

Response​

Response Syntax​

Response Elements​

상태 코드​

API 사용 준비

작업 클러스터 생성

Request

Request Syntax

API 호출 방식

Request Header

Request Elements

Response

Response Syntax

Response Elements

상태 코드

작업 클러스터 상세 조회

Request

Request Syntax

API 호출 방식

Query parameters

Request Header

Response

Response Syntax

Response Elements

상태 코드