Hadoop Eco Open API

시작하기 전에

Hadoop Eco Open API는 신규 클러스터 생성, 클러스터 조회, 클러스터 삭제 및 증설 등의 일반적인 클러스터의 생성 및 관리를 수행합니다. Hadoop Eco Open API 사용 시, Open API Key의 발급은 필요하지 않습니다.

Hadoop Eco Open API 사용 방법은 다음과 같습니다.

API 사용 준비

Hadoop Eco Open API를 호출하기 위해서는 액세스 키를 발급받아야 합니다.

API 엔드포인트

API 요청을 위한 Hadoop Eco API 엔드포인트 URL은 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 리전 API 엔드포인트 URL 형식

https://hadoop-eco.kr-central-1.kakaoi.io

kr-central-2 리전 API 엔드포인트 URL 형식

https://hadoop-eco.kr-central-2.kakaocloud.com

Base64 변환 방법

Open API 사용 시 일부 값들은 Base64로 인코딩 후 해당 값을 입력해야 합니다. 인코딩 방법은 아래와 같습니다.

터미널에서 hello 문자열을 Base64로 인코딩하는 방법
1. Linux: echo "hello" | base64

2. OS X: echo "hello" | base64

3. Windows: echo hello > input.txt
            certutil -encode "input.txt" "output.txt"
            type output.txt

클러스터 생성

Open API를 통해 클러스터를 생성합니다. 엔드포인트는 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 생성
curl -X POST 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{Body}'

kr-central-2 클러스터 생성
curl -X POST 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{Body}'

Request

Request Header

키	값
Content-Type*	`application/json`으로 고정
`{credential-id}`*	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급 필요

Request Body

기본 정보 입력

클러스터 이름, 유형, 버전, 네트워크 정보, 가용성 여부 등 기본적인 정보를 입력합니다.

Request Body
{
  "name": "string",
  "clusterType": "string",
  "clusterVersion": "string",
  "isHa": true | false,
  "keypairName": "string",
  "masterFlavorName": "string",
  "masterVolumeSize": integer,
  "workerCnt": integer,
  "workerFlavorName": "string",
  "workerVolumeSize": integer,
  "monitoring": true,
  "securityGroupIds": ["string"],
  "securityGroupName": "string",
  "vpcId": "string",
  "subnetId": "string",
  "adminInfo": {
    "userId": "string",
    "userPw": "string"
  },
  "config": {
    "hdfsReplication": integer,
    "hdfsBlockSize": integer,
    "configText": "string",
    "fileUrl": "string",
    "userScript": "string"
  }
}

구분	유형	설명
name*	String	클러스터 이름
clusterType*	String	클러스터 유형
clusterVersion*	String	클러스터 버전
isHa*	Boolean	고가용성 여부 - `true`: 고가용성 - `false`: 고가용성이 아님
keypairName*	String	클러스터를 구성하는 Virtual Machine에서 사용할 키 페어 이름
masterFlavorName*	String	마스터 노드의 플레이버 유형 이름 - ex) m2a.xlarge
masterVolumeSize*	Integer	마스터 노드의 볼륨 크기 (GB)
workerCnt*	Integer	워커 노드 개수, HDFS 복제 개수(config.hdfsReplication) 보다 크거나 같아야 함
workerFlavorName*	String	워커 노드의 플레이버 유형 이름 - ex) m2a.xlarge
workerVolumeSize*	Integer	워커 노드의 볼륨 크기 (GB)
monitoring*	Boolean	모니터링 에이전트 설치 여부
securityGroupIds, securityGroupName	String	보안 그룹 ID와 보안 그룹 이름으로, 두 필드 중 한 개는 필수로 입력 - 기존에 생성해 둔 보안 그룹을 재사용할 경우 `securityGroupIds`에 보안 그룹 ID를 입력 - 클러스터 생성 시 자동으로 생성하는 보안 그룹을 사용하고자 할 경우, `securityGroupName`에 보안 그룹 이름을 입력
vpcId*	String	클러스터를 설치할 VPC ID를 입력
subnetId*	String	클러스터를 설치할 서브넷의 ID를 입력
adminInfo.userId	String	Hue, Superset에서 사용할 계정 정보(ID) 설정 - 입력하지 않는 경우 IAM 계정 ID로 설정
adminInfo.userPw	String	Hue, Superset에서 사용할 계정 정보(PW) 설정 - 입력하지 않는 경우 IAM 계정 비밀번호로 설정 - 별도 설정을 원할 경우 Base64로 인코딩된 문자열 입력
config.hdfsReplication*	Integer	복제 개수 - 워커 노드 개수(workerCnt)보다 적거나 같아야 함
config.BlockSize*	Integer	블록 사이즈(mb)
config.configText	String	주입할 클러스터 설정 정보 - JSON 형태의 문자열로 작성 후, String으로 변환 후 Base64로 인코딩하여 입력 - `fileUrl` `configText`에 설정 정보 주입 예시 참고
config.fileUrl	String	Object Storage 파일의 URL 주소를 입력 - Base64로 인코딩은 불필요 예시) `https://objectstorage.{리전명}.kakaocloud.com/v1/<프로젝트 ID>/<버킷명>/<경로>/<파일명>` - `fileUrl` `configText`에 설정 정보 주입 예시 참고
config.userScript	String	Virtual Machine이 생성될 때 실행하고 싶은 사용자 스크립트를 입력 - 실행할 Bash shell 문자열을 Base64 인코딩한 문자열로 입력 -`userScript`에 사용자 스크립트 입력 예시 참고

`fileUrl` `configText`에 설정 정보 주입 예시

fileUrl, configText를 통해 클러스터의 설정 정보 입력 시, JSON 문자열 혹은 Object Storage에 존재하는 파일로 입력할 수 있습니다.
예를 들어, 아래와 같은 설정 정보를 주입하고자 할 경우, 먼저 JSON 형식으로 작성한 후 설정 정보 주입을 참고하여 입력합니다.

설정 정보 예시
설정 정보 JSON 작성

core-site.xml
<configuration>
... (생략) ...
    <property>
        <name>io.file.buffer.size</name>
        <value>65536</value>
    </property>
... (생략) ...
</configuration>

hive-site.xml
<configuration>
... (생략) ...
    <property>
        <name>mapred.max.split.size</name>
        <value>128000000</value>
    </property>
... (생략) ...
</configuration>

hadoop-env.sh
... (생략) ...
export HADOOP_HEAPSIZE="3001"
export HADOOP_NAMENODE_INIT_HEAPSIZE="-Xmx3002m"
... (생략) ...

spark-defaults.conf
... (생략) ...
spark.driver.memory                     4000M
spark.network.timeout                   800s
... (생략) ...

입력하고 싶은 설정 정보를 아래와 같이 JSON 형태로 작성합니다.

config.json
{
  "configurations": [
    {
      "classification": "core-site",
      "properties": {
        "io.file.buffer.size": "65536"
      }
    },
    {
      "classification": "hive-site",
      "properties": {
        "mapred.max.split.size": "128000000"
      }
    },
    {
      "classification": "hadoop-env",
      "properties": {
        "hadoop_env_hadoop_heapsize": 3001,
        "hadoop_env_hadoop_namenode_heapsize": "-Xmx3002m"
      }
    },
    {
      "classification": "spark-defaults",
      "properties": {
        "spark.driver.memory": "4000M",
        "spark.network.timeout": "800s"
      }
    }
  ]
}

설정 정보 주입

JSON이 준비되었다면 클러스터 생성 시 설정을 주입하는 두 가지 방법이 있습니다.

첫 번째 방법

첫 번째는 JSON을 Base64 인코딩하여 configText에 주입하는 방법입니다.

JSON 설정 파일 Base64로 인코딩하기 위해 다음 명령어를 실행합니다.
```
echo | cat config.json | base64
```

Base64 문자열을 configText 필드에 입력합니다.

ewogICJjb25maWd1cmF0aW9ucyI6IFsKICAgIHsKICAgICAgImNsYXNzaWZpY2F0aW9uIjogImNvcmUtc2l0ZSIsCiAgICAgICJwcm9wZXJ0aWVzIjogewogICAgICAgICJpby5maWxlLmJ1ZmZlci5zaXplIjogIjY1NTM2IgogICAgICB9CiAgICB9LAogICAgewogICAgICAiY2xhc3NpZmljYXRpb24iOiAiaGl2ZS1zaXRlIiwKICAgICAgInByb3BlcnRpZXMiOiB7CiAgICAgICAgIm1hcHJlZC5tYXguc3BsaXQuc2l6ZSI6ICIxMjgwMDAwMDAiCiAgICAgIH0KICAgIH0sCgl7CiAgICAgICJjbGFzc2lmaWNhdGlvbiI6ICJoYWRvb3AtZW52IiwKICAgICAgInByb3BlcnRpZXMiOiB7CiAgICAgICAgImhhZG9vcF9lbnZfaGFkb29wX2hlYXBzaXplIjogMzAwMSwKICAgICAgICAiaGFkb29wX2Vudl9oYWRvb3BfbmFtZW5vZGVfaGVhcHNpemUiOiAiLVhteDMwMDJtIgogICAgICB9CiAgICB9LAogICAgewogICAgICAiY2xhc3NpZmljYXRpb24iOiAic3BhcmstZGVmYXVsdHMiLAogICAgICAicHJvcGVydGllcyI6IHsKICAgICAgICAic3BhcmsuZHJpdmVyLm1lbW9yeSI6ICI0MDAwTSIsCiAgICAgICAgInNwYXJrLm5ldHdvcmsudGltZW91dCI6ICI4MDBzIgogICAgICB9CiAgICB9CiAgXQp9Cg==

두 번째 방법

두 번째는 Object Storage에 파일 형태로 업로드 후, fileUrl에 해당 파일의 객체 URL을 주입하는 방법입니다.

Object Storage에 JSON 파일을 업로드합니다.
업로드한 파일의 [더 보기] 버튼을 누르고, '객체 URL 복사'를 클릭합니다.
올바르게 복사했다면 다음과 같은 형태의 URL을 확인하실 수 있습니다.
- https://objectstorage.{리전명}.kakaocloud.com/v1/{프로젝트 ID}/{버킷명}/{경로}/{파일명}
복사한 URL을 fileUrl에 주입합니다.

`userScript`에 사용자 스크립트 입력 예시

사용자 스크립트 파일을 준비합니다.

사용자 스크립트
#!/bin/bash

function print(){
    msg=$1
    echo "${msg}"
}

print "hello world!"

스크립트 내용을 Base64로 인코딩하기 위해 다음 명령어를 실행합니다.
```
echo | cat script.sh | base64
```

Base64 문자열을 userScript 필드에 입력합니다.

IyEvYmluL2Jhc2gKCmZ1bmN0aW9uIHByaW50KCl7CiAgICBtc2c9JDEKICAgIGVjaG8gIiR7bXNnfSIKfQoKcHJpbnQgImhlbGxvIHdvcmxkISIK

(선택) 클러스터 설치 후 작업 스케줄링을 실행하고 싶은 경우 하위에 userTask를 입력합니다.

userTask
"userTask": {
  "type": "hive|spark",
  "terminationPolicy": "never|onSuccess|always",
  "fileUrl": "string",
  "hiveQuery": "string",
  "deployMode": "cluster|client",
  "execOpts": "string",
  "execParams": "string",
  "logBucketName": "string"
}

구분	설명
type*	작업의 종류를 입력 - `hive`, `spark` 지원
terminationPolicy*	작업 스케줄링이 끝난 후 클러스터의 동작을 입력 - `never`: 클러스터를 종료하지 않음 - `onSuccess`: 작업 스케줄링이 성공했을 때만 클러스터를 종료 - `always`: 클러스터를 항상 종료함
hiveQuery	(Hive 작업의 경우) 실행할 hive 쿼리 문자열
fileUrl	(Hive 작업의 경우) 실행할 hive 쿼리 파일이 위치하는 Object Storage URL을 입력 (Spark 작업의 경우) 실행할 jar 파일이 위치하는 Object Storage URL을 입력
deployMode	(Spark 작업의 경우) spark 작업 배포 모드로 클러스터 혹은 클라이언트를 지원
execOpts	(Hive 작업의 경우) hive 작업 실행 시 사용할 hive 옵션 정보를 문자열로 입력 (Spark 작업의 경우) spark 작업 실행 시 사용할 spark 옵션 정보를 문자열로 입력
execParams	(Spark 작업의 경우) spark 작업 실행 시 넘겨줄 파라미터 정보를 문자열로 입력
logBucketName	작업 스케줄링 로그를 저장할 Object Storage 버킷 명을 입력 logBucketName을 설정하면 `<logBucketName>/HadoopEco/<클러스터 이름>` 하위에 로그 파일이 저장

(선택) Hive 메타스토어로 MySQL을 연동하고자 할 경우 하위에 hiveDbInfo 오브젝트를 같이 입력합니다.

MySQL 연동
"hiveDbInfo": {
  "objectId": "string",
  "dbName": "string",
  "userId": "string",
  "userPw": "string"
}

구분	설명
objectId*	연동할 MySQL의 오브젝트 ID 입력
dbName, userId, userPw*	각각 MySQL의 데이터베이스 이름, MySQL에 접근할 계정의 ID와 비밀번호를 입력 - 단, 비밀번호는 Base64로 인코딩된 문자열이어야 함

(선택) 데이터 카탈로그를 연동하고자 할 경우 dataCatalogInfo 오브젝트를 같이 입력합니다.

데이터 카탈로그 연동
"dataCatalogInfo": {
  "catalogId": "string"
}

구분	설명
catalogId*	연동할 데이터 카탈로그의 오브젝트 ID 입력

(선택) Redis를 연동하고자 할 경우 오브젝트 ID를 같이 입력합니다.

Redis 연동
"redisInfo": {
  "objectId": "string",
  "dbIdSupersetCelery": integer,
  "dbIdSupersetResults": integer
}

구분	설명
objectId*	연동할 Redis의 오브젝트 ID 입력
dbIdSupersetCelery	0~15의 정수 (미설정 시 기본값이 `0`,`1`로 세팅)
dbIdSupersetResults	0~15의 정수 (미설정 시 기본값이 `0`,`1`로 세팅)

Response

응답 예시
{
  "id": "48fd271f-01f8-47bd-8e42-8c872fb6bf3a",
  "name": "hive-job-cluster",
  "status": "Initializing"
}

구분	설명
id	생성한 클러스터 ID
name	생성한 클러스터 이름
status	클러스터 상태

상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청
`401`	크리덴셜 인증 실패
`403`	권한 없음
`409`	클러스터 이름 중복

클러스터 생성 예제 1

생성할 클러스터 조건

hde-2.0.1 버전의 Core Hadoop 유형
고가용성을 적용하지 않고 워커노드 개수는 3개
보안 그룹 자동 생성
클러스터 설정 정보 오버라이딩: HDFS의 core-site.xml 의 io.file.buffer.size 필드를 65536으로 설정

설정 적용을 위한 JSON을 작성합니다.

 {
   "configurations": [
     {
       "classification": "core-site",
       "properties": {
         "io.file.buffer.size": "65536"
       }
     }
   ]
 }

JSON 설정 파일을 Base64로 인코딩하기 위해 다음 명령어를 실행합니다.
```
echo | cat config.json | base64
```

Base64 문자열을 ConfigText 필드에 입력합니다.

ewogICJjb25maWd1cmF0aW9ucyI6IFsKICAgIHsKICAgICAgImNsYXNzaWZpY2F0aW9uIjogImNvcmUtc2l0ZSIsCiAgICAgICJwcm9wZXJ0aWVzIjogewogICAgICAgICJpby5maWxlLmJ1ZmZlci5zaXplIjogIjY1NTM2IgogICAgICB9CiAgICB9CiAgXQp9Cg==

Hive 작업 스케줄링 적용하고 작업이 끝나도 클러스터 유지
데이터 카탈로그 연동
- 연동할 데이터 카탈로그 ID가 필요합니다.
- 카카오클라우드 콘솔 > Analytics > Data Catalog에 진입하여 ID를 가지고 올 수 있습니다.

kr-central-1
kr-central-2

클러스터 생성 예제 1
curl -X POST 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "hive-job-cluster",
  "clusterType": "hadoop",
  "clusterVersion": "hde-2.0.1",
  "isHa": false,
  "workerCnt": 3,
  "vpcId": "3ebb3020-d416-f1a4-534c-d3ad0fa1bec0",
  "subnetId": "5c1632bf-a7da-fdbf-a594-e6a7bedb328c",
  "securityGroupName": "test-security-group1",
  "keypairName": "keypairname",
  "monitoring": true,
  "masterFlavorName": "m2a.xlarge",
  "workerFlavorName": "m2a.xlarge",
  "masterVolumeSize": 50,
  "workerVolumeSize": 100,
  "adminInfo": {
    "userId": "admin_user",
    "userPw": "<base_64_string>"
  },
  "config": {
    "hdfsReplication": 3,
    "hdfsBlockSize": 128,
    "configText": "ewogICJjb25maWd1cmF0aW9ucyI6IFsKICAgIHsKICAgICAgImNsYXNzaWZpY2F0aW9uIjogImNvcmUtc2l0ZSIsCiAgICAgICJwcm9wZXJ0aWVzIjogewogICAgICAgICJpby5maWxlLmJ1ZmZlci5zaXplIjogIjY1NTM2IgogICAgICB9CiAgICB9CiAgXQp9Cg=="
  },
  "userTask": {
    "type": "hive",
    "terminationPolicy": "never",
    "hiveQuery": "create table if not exists t1 (col1 string); insert into table t1 values ('a'), ('b'), ('c');",
    "execOpts": "--hiveconf hive.tez.container.size=1024 --hiveconf hive.tez.java.opts=-Xmx1600m",
    "logBucketName": "user-bucket"
  },
  "dataCatalog": {
    "catalogId": "e1ebae48-daba-a4c5-56da-fbb2b684ae07"
  }
}'

클러스터 생성 예제 1
curl -X POST 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "hive-job-cluster",
  "clusterType": "hadoop",
  "clusterVersion": "hde-2.0.1",
  "isHa": false,
  "workerCnt": 3,
  "vpcId": "3ebb3020-d416-f1a4-534c-d3ad0fa1bec0",
  "subnetId": "5c1632bf-a7da-fdbf-a594-e6a7bedb328c",
  "securityGroupName": "test-security-group1",
  "keypairName": "keypairname",
  "monitoring": true,
  "masterFlavorName": "m2a.xlarge",
  "workerFlavorName": "m2a.xlarge",
  "masterVolumeSize": 50,
  "workerVolumeSize": 100,
  "adminInfo": {
    "userId": "admin_user",
    "userPw": "<base_64_string>"
  },
  "config": {
    "hdfsReplication": 3,
    "hdfsBlockSize": 128,
    "configText": "ewogICJjb25maWd1cmF0aW9ucyI6IFsKICAgIHsKICAgICAgImNsYXNzaWZpY2F0aW9uIjogImNvcmUtc2l0ZSIsCiAgICAgICJwcm9wZXJ0aWVzIjogewogICAgICAgICJpby5maWxlLmJ1ZmZlci5zaXplIjogIjY1NTM2IgogICAgICB9CiAgICB9CiAgXQp9Cg=="
  },
  "userTask": {
    "type": "hive",
    "terminationPolicy": "never",
    "hiveQuery": "create table if not exists t1 (col1 string); insert into table t1 values ('a'), ('b'), ('c');",
    "execOpts": "--hiveconf hive.tez.container.size=1024 --hiveconf hive.tez.java.opts=-Xmx1600m",
    "logBucketName": "user-bucket"
  },
  "dataCatalog": {
    "catalogId": "e1ebae48-daba-a4c5-56da-fbb2b684ae07"
  }
}'

클러스터 생성 예제 2

생성할 클러스터 조건

hde-2.0.1 버전의 Core Hadoop 유형
고가용성을 적용, 워커노드 개수는 5개
사용자 스크립트를 파일로 적용
- Object Storage에 파일 형태로 업로드 후 userScriptfileUrl 에 해당 파일의 객체 URL을 주입하는 방법입니다.
- Object Storage에 사용자 스크립트 파일을 업로드합니다.
- 업로드한 파일의 [더 보기] 아이콘을 누르고, '객체 URL 복사'를 클릭합니다.
- 올바르게 복사했다면 다음과 같은 형태의 URL을 확인하실 수 있습니다.
  https://objectstorage.{리전명}.kakaocloud.com/v1/{프로젝트 ID}/{버킷명}/{경로}/{파일명}
- 복사한 URL을 userScriptfileUrl에 주입합니다.
기존 보안 그룹을 재사용
spark 작업 스케줄링 적용하고 작업이 성공하면 클러스터 자동 종료

kr-central-1
kr-central-2

클러스터 생성 예제 2
curl -X POST 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "spark-job-cluster",
  "clusterType": "hadoop",
  "clusterVersion": "hde-2.0.1",
  "isHa": true,
  "workerCnt": 5,
  "vpcId": "3ebb3020-d416-f1a4-534c-d3ad0fa1bec0",
  "subnetId": "5c1632bf-a7da-fdbf-a594-e6a7bedb328c",
  "securityGroupIds": ["56aa3028-b163-b114-baac-gg1dtfa1bec1", "76163abf-j11a-fbbd-a123-d1a4bedb123c"],
  "keypairName": "keypairname",
  "monitoring": true,
  "masterFlavorName": "m2a.xlarge",
  "workerFlavorName": "m2a.xlarge",
  "masterVolumeSize": 50,
  "workerVolumeSize": 100,
  "config": {
    "hdfsReplication": 3,
    "hdfsBlockSize": 128,
    "userScriptFileUrl": "https://objectstorage.{리전명}.kakaocloud.com/v1/111c5b646a194bf09ac123566a39d123/user-bucket/user_script.sh"
  },
  "userTask": {
    "type": "spark",
    "terminationPolicy": "onSuccess",
    "fileUrl": "https://objectstorage.{리전명}.kakaocloud.com/v1/111c5b646a194bf09ac123566a39d123/user-bucket/sparkjob/spark_example.jar",
    "deployMode": "cluster",
    "execOpts": "--class org.apache.spark.examples.SparkPi --master yarn",
    "logBucketName": "user-bucket"
  }
}'

클러스터 생성 예제 2
curl -X POST 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "spark-job-cluster",
  "clusterType": "hadoop",
  "clusterVersion": "hde-2.0.1",
  "isHa": true,
  "workerCnt": 5,
  "vpcId": "3ebb3020-d416-f1a4-534c-d3ad0fa1bec0",
  "subnetId": "5c1632bf-a7da-fdbf-a594-e6a7bedb328c",
  "securityGroupIds": ["56aa3028-b163-b114-baac-gg1dtfa1bec1", "76163abf-j11a-fbbd-a123-d1a4bedb123c"],
  "keypairName": "keypairname",
  "monitoring": true,
  "masterFlavorName": "m2a.xlarge",
  "workerFlavorName": "m2a.xlarge",
  "masterVolumeSize": 50,
  "workerVolumeSize": 100,
  "config": {
    "hdfsReplication": 3,
    "hdfsBlockSize": 128,
    "userScriptFileUrl": "https://objectstorage.{리전명}.kakaocloud.com/v1/111c5b646a194bf09ac123566a39d123/user-bucket/user_script.sh"
  },
  "userTask": {
    "type": "spark",
    "terminationPolicy": "onSuccess",
    "fileUrl": "https://objectstorage.{리전명}.kakaocloud.com/v1/111c5b646a194bf09ac123566a39d123/user-bucket/sparkjob/spark_example.jar",
    "deployMode": "cluster",
    "execOpts": "--class org.apache.spark.examples.SparkPi --master yarn",
    "logBucketName": "user-bucket"
  }
}'

클러스터 생성 예제 3

생성할 클러스터 조건

hde-2.0.1 버전의 Core Hadoop 유형
고가용성을 적용하지 않고 워커노드 개수는 3개
IAM 계정을 관리자 계정으로 사용
보안 그룹 자동 생성

사용자 스크립트를 사용

사용자 스크립트 파일 script.sh
#!/bin/bash
    
function print(){
    msg=$1
    echo "${msg}"
}

print "hello world!"

스크립트 내용을 Base64로 인코딩하기 위해 다음 명령어를 실행합니다.
```
echo | cat script.sh | base64
```

Base64 문자열을 userScript 필드에 입력합니다.

IyEvYmluL2Jhc2gKCmZ1bmN0aW9uIHByaW50KCl7CiAgICBtc2c9JDEKICAgIGVjaG8gIiR7bXNnfSIKfQoKcHJpbnQgImhlbGxvIHdvcmxkISIK

환경 변수를 Object Storage 파일에 적용
- Ubuntu 사용자에게 아래 환경 변수 적용 시
```
export JAVA_HOME=${JAVA_HOME:-/usr/lib/jdk}
export CUSTOM_HOME=/etc/custom
```
1. 환경 변수 적용을 위한 JSON을 작성합니다.
  환경 변수 적용을 위한 JSON 작성
```
{
  "configurations": [
    {
      "classification": "user-env:ubuntu",
      "properties": {
        "env": "export JAVA_HOME=${JAVA_HOME:-/usr/lib/jdk}\nexport CUSTOM_HOME=/etc/custom"
      }
    }
  ]
}
```
2. 작성한 JSON 파일 config.json을 Object Storage에 파일 형태로 업로드하여 객체 URL 복사 후 fileUrl에 입력합니다.
MySQL 연동
- 연동할 MySQL에서 메타 데이터베이스로 사용할 데이터베이스를 다음과 같이 미리 생성해 두어야 합니다.
```
CREATE DATABASE meta_db;
```
- MySQL의 오브젝트 ID를 준비해야 합니다.
  - 콘솔에서 MySQL 메뉴 진입 → 연결할 MySQL의 상세 화면으로 이동 후 개발자모드 혹은 주소창에서 UUID 형태의 오브젝트 ID를 추출할 수 있습니다.
  - MySQL 오브젝트 ID는 추후 상세 화면에서 조회할 수 있도록 개선될 예정입니다.
- MySQL에 접근 가능한 계정 정보(ID, 비밀번호)를 준비해야 합니다. (암호는 Base64로 인코딩해야 합니다.)

kr-central-1
kr-central-2

클러스터 생성 예제 3
curl -X POST 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "test-cluster",
  "clusterType": "hadoop",
  "clusterVersion": "hde-2.0.1",
  "isHa": false,
  "workerCnt": 3,
  "vpcId": "3ebb3020-d416-f1a4-534c-d3ad0fa1bec0",
  "subnetId": "5c1632bf-a7da-fdbf-a594-e6a7bedb328c",
  "securityGroupName": "security-group-test",
  "keypairName": "keypairname",
  "monitoring": true,
  "masterFlavorName": "m2a.xlarge",
  "workerFlavorName": "m2a.xlarge",
  "masterVolumeSize": 50,
  "workerVolumeSize": 100,
  "config": {
    "hdfsReplication": 3,
    "hdfsBlockSize": 128,
    "configFileUrl": "https://objectstorage.{리전명}.kakaocloud.com/v1/111c5b646a194bf09ac123566a39d123/user-bucket/config.json",
    "userScript": "IyEvYmluL2Jhc2gKCmZ1bmN0aW9uIHByaW50KCl7CiAgICBtc2c9JDEKICAgIGVjaG8gIiR7bXNnfSIKfQoKcHJpbnQgImhlbGxvIHdvcmxkISIK"
  },
  "hiveDbInfo": {
    "objectId": "cfdbd7cd-f0ce-bbfb-de5b-e73bdbbcb0cf",
    "dbName": "meta_db",
    "userId": "mysql_user",
    "userPw": "<base_64_string>"
  }
}'

클러스터 생성 예제 3
curl -X POST 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "name": "test-cluster",
  "clusterType": "hadoop",
  "clusterVersion": "hde-2.0.1",
  "isHa": false,
  "workerCnt": 3,
  "vpcId": "3ebb3020-d416-f1a4-534c-d3ad0fa1bec0",
  "subnetId": "5c1632bf-a7da-fdbf-a594-e6a7bedb328c",
  "securityGroupName": "security-group-test",
  "keypairName": "keypairname",
  "monitoring": true,
  "masterFlavorName": "m2a.xlarge",
  "workerFlavorName": "m2a.xlarge",
  "masterVolumeSize": 50,
  "workerVolumeSize": 100,
  "config": {
    "hdfsReplication": 3,
    "hdfsBlockSize": 128,
    "configFileUrl": "https://objectstorage.{리전명}.kakaocloud.com/v1/111c5b646a194bf09ac123566a39d123/user-bucket/config.json",
    "userScript": "IyEvYmluL2Jhc2gKCmZ1bmN0aW9uIHByaW50KCl7CiAgICBtc2c9JDEKICAgIGVjaG8gIiR7bXNnfSIKfQoKcHJpbnQgImhlbGxvIHdvcmxkISIK"
  },
  "hiveDbInfo": {
    "objectId": "cfdbd7cd-f0ce-bbfb-de5b-e73bdbbcb0cf",
    "dbName": "meta_db",
    "userId": "mysql_user",
    "userPw": "<base_64_string>"
  }
}'

클러스터 조회

Open API를 통해 클러스터 정보를 조회합니다. 엔드포인트는 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 조회
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터 조회
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Path Parameter

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

Request Header

키	값
`{credential-id}`*	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급 필요

Response Example

응답 예시
{
  "id": "string",
  "name": "string",
  "owner": "string",
  "clusterType": "string",
  "clusterVersion": "string",
  "isHa": true,
  "isScalable": true,
  "status": "string",
  "apiKeyStatus": "impossible|possible|applied",
  "masterCnt": integer,
  "workerCnt": integer,
  "nodeCnt": integer,
  "vpcId": "string",
  "subnetId": "string",
  "securityGroupIds": ["string"],
  "keypairName": "string",
  "monitoring": true|false,
  "imageName": "string",
  "nameNodeUrl": "string",
  "resourceManagerUrl": "string",
  "hueUrl": "string",
  "hmasterUrl": "string",
  "trinoUrl": "string",
  "druidUrl": "string",
  "supersetUrl": "string",
  "createdAt": integer,
  "runningAt": integer,
  "elapsedTime": integer,
  "totalVmUptime": integer,
  "masterInfo": [
    {
      "flavorId": "string",
      "flavorName": "string",
      "volumeSize": integer
    }
  ],
  "workerInfo": [
    {
      "flavorId": "string",
      "flavorName": "string",
      "volumeSize": integer
    }
  ],
  "adminInfo": {
    "userId": "string"
  },
  "config": {
    "hdfsBlockSize": integer,
    "hdfsReplication": integer,
    "configText": "string",
    "configFileUrl": "string"
  },
  "userTask": {
    "type": "string",
    "terminationPolicy": "string",
    "fileUrl": "string",
    "hiveQuery": "string",
    "deployMode": "string",
    "execOpts": "string",
    "execParams": "string",
    "logBucketName": "string",
    "logUrl": "string"
  },
  "hiveDbInfo": {
    "objectId": "string",
    "subnetId": "string",
    "name": "string",
    "host": "string",
    "port": integer,
    "dbName": "string",
    "userId": "string"
  },
  "dataCatalogInfo": {
    "metastoreUri": "string",
    "catalogId": "string",
    "catalogName": "string",
    "vpcId": "string",
    "vpcName": "string",
    "subnetId": "string",
    "subnetName": "string"
  },
  "redisInfo": {
    "objectId": "string",
    "name": "string",
    "subnetId": "string",
    "primaryEndpoint": "string",
    "readEndpoint": "string",
    "clusterEnabled": true,
    "port": integer,
    "dbIdSupersetCelery": integer,
    "dbIdSupersetResults": integer
  }
}

Response

상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청
`401`	크리덴셜 인증 실패
`403`	권한 없음
`404`	클러스터가 존재하지 않음

클러스터 목록 조회

Open API를 통해 클러스터 목록을 조회합니다. 엔드포인트는 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 조회
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터 조회
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Request Header

키	값
`{credential-id}`*	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급하여 확인 필요

Query Parameter

목록 조회 시 다음과 같은 조건으로 조회할 수 있습니다. 조건이 여러 개일 경우 조건들을 &로 연결합니다.

키	자료형	설명	필수 여부	기본값
size	integer	페이지 크기로, 페이지 하나에서 조회할 수 있는 클러스터 개수입니다.	선택	20
page	integer	조회할 페이지의 번호입니다. 페이지 크기에 따라서 조회할 수 있는 페이지의 번호가 달라질 수 있습니다.	선택	0
includeTerminated	boolean	응답 목록에 종료상태인 클러스터를 포함할지 여부입니다.	선택	true
sort	string	정렬을 적용할 필드명과 정렬 방법입니다. 정렬할 필드명과 정렬 방법(asc 혹은 desc)을 ","로 연결하여 작성합니다. 예를 들어, name 필드를 내림차순 정렬할 경우 sort=name,desc 로 입력하고, 정렬 조건을 여러 개 입력하는 경우 입력한 순서대로 정렬 우선순위가 적용됩니다. 정렬 적용이 가능한 필드입니다. id, name, status, owner, clusterType, clusterVersion, apiKeyStatus, masterCnt, workerCnt, createdAt, runningAt, elapsedTime	선택	createdAt,desc
name	string	like 검색할 클러스터 이름입니다. 입력하지 않은 경우 모든 값을 조회합니다.	선택
apiKeyStatus	string	like 검색할 Open API Key 상태입니다. possible, impossible, applied 값으로 검색할 수 있습니다. 각각 적용 가능, 적용 불가능, 적용 중을 의미합니다. 입력하지 않은 경우 모든 값을 조회합니다.	선택

Response

Response Example

응답 예시
{
  "content": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "owner": "string",
      "clusterType": "string",
      "clusterVersion": "string",
      "isScalable": boolean,
      "apiKeyStatus": "string",
      "masterCnt": integer,
      "workerCnt": integer,
      "nodeCnt": integer,
      "createdAt": long,
      "runningAt": long,
      "elapsedTime": long
    }
  ],
  "pageable": {
    "pageNumber": integer,
    "pageSize": integer,
    "sort": {
      "sorted": boolean,
      "unsorted": boolean,
      "empty": boolean
    },
    "offset": integer,
    "paged": boolean,
    "unpaged": boolean
  },
  "totalPages": integer,
  "totalElements": integer,
  "last": boolean,
  "numberOfElements": integer,
  "sort": {
    "sorted": boolean,
    "unsorted": boolean,
    "empty": boolean
  },
  "size": integer,
  "first": boolean,
  "number": integer,
  "empty": boolean
}

구분	설명
content	데이터가 위치하는 리스트
id	클러스터 ID
name	클러스터 이름
status	클러스터 상태
owner	클러스터 소유자
clusterType	클러스터 유형
clusterVersion	클러스터 버전
isScalable	클러스터가 스케일링 가능한지 여부
apiKeyStatus	클러스터의 Open API Key 상태
masterCnt	마스터 노드 개수
workerCnt	워커 노드 개수
nodeCnt	전체 노드 개수
createdAt	클러스터 생성 시점의 유닉스 시간
runningAt	클러스터가 `Running` 상태로 진입한 시점의 유닉스 시간
elapsedTime	가동 시간 (ms)
pageable	페이징 관련 정보
pageNumber	현재 페이지 번호
pageSize	현재 페이지 크기
sort	정렬 정보
sorted	정렬이 적용되어있는지 여부
unsorted	정렬이 적용되지 않았는지 여부
empty	정렬 조건이 비어있는지 여부
offset	페이지의 시작 지점
paged	페이징 적용 여부
unpaged	페이징이 적용되지 않았는지 여부
totalPages	총 페이지 수
totalElements	총 데이터 개수
last	현재 페이지가 마지막 페이지인지 여부
size	현재 페이지 크기
first	현재 페이지가 첫 페이지인지 여부
number	현재 페이지 번호
empty	현재 페이지가 비어있는지 여부

상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청
`401`	크리덴셜 인증 실패
`403`	권한 없음

클러스터 목록 조회 예제 1

목록 조회 조건

페이지의 크기는 3이고, 페이지 번호는 2로 설정
종료 상태의 클러스터 포함
name 내림차순, status 오름차순으로 정렬 적용

kr-central-1
kr-central-2

kr-central-1 클러스터 목록 조회 1
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters?page=0&size=3&includeTerminated=true&sort=name,desc&sort=status,asc' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터 목록 조회 1
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters?page=0&size=3&includeTerminated=true&sort=name,desc&sort=status,asc' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

예제 1 응답

클러스터 목록 조회 예제 1 응답
{
  "content": [
    {
      "id": "fa70ff9f-98a2-446c-9f33-75d7dce7c160",
      "name": "sally-kbctest",
      "status": "Terminated(User)",
      "owner": "user@kakaoenterprise.com",
      "clusterType": "hadoop",
      "clusterVersion": "hde-2.0.1",
      "isScalable": false,
      "apiKeyStatus": "impossible",
      "masterCnt": 0,
      "workerCnt": 0,
      "nodeCnt": 0,
      "createdAt": 1716359078000,
      "runningAt": 1716359422659,
      "elapsedTime": 12108694
    },
    {
      "id": "3ec42a8d-a5a3-42ef-9c34-e270db0354b1",
      "name": "sally-kbctest",
      "status": "Terminated(User)",
      "owner": "user@kakaoenterprise.com",
      "clusterType": "hadoop",
      "clusterVersion": "hde-2.0.1",
      "isScalable": false,
      "apiKeyStatus": "impossible",
      "masterCnt": 0,
      "workerCnt": 0,
      "nodeCnt": 0,
      "createdAt": 1716536420000,
      "runningAt": 1716536754352,
      "elapsedTime": 265434374
    },
    {
      "id": "d66c3ff5-29f3-4f2d-a611-4d343573cc17",
      "name": "sally-kbctest",
      "status": "Terminated(User)",
      "owner": "user@kakaoenterprise.com",
      "clusterType": "hadoop",
      "clusterVersion": "hde-2.0.1",
      "isScalable": false,
      "apiKeyStatus": "impossible",
      "masterCnt": 0,
      "workerCnt": 0,
      "nodeCnt": 0,
      "createdAt": 1717049297000,
      "runningAt": 1717049871150,
      "elapsedTime": 727811
    }
  ],
  "pageable": {
    "pageNumber": 2,
    "pageSize": 3,
    "sort": {
      "empty": false,
      "sorted": true,
      "unsorted": false
    },
    "offset": 6,
    "unpaged": false,
    "paged": true
  },
  "totalPages": 32,
  "totalElements": 96,
  "last": false,
  "size": 3,
  "number": 2,
  "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
  },
  "numberOfElements": 3,
  "first": false,
  "empty": false
}

클러스터 목록 조회 예제 2

목록 조회 조건

페이지의 크기는 5이고, 페이지 번호는 0으로 설정
종료 상태의 클러스터 제외
이름에 test가 포함된 클러스터로 필터 적용
createdAt 오름차순으로 정렬 적용
apiKeyStatus을 impossible 로 필터 적용

kr-central-1
kr-central-2

kr-central-1 클러스터 목록 조회 2
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters?page=0&size=5&includeTerminated=false&name=test&sort=createdAt,asc&apiKeyStatus=impossibl' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터 목록 조회 2
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters?page=0&size=5&includeTerminated=false&name=test&sort=createdAt,asc&apiKeyStatus=impossibl' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

예제 2 응답

클러스터 목록 조회 예제 2 응답
{
  "content": [
    {
      "id": "90878bcd-0f38-4338-810e-40d6fbfd8b45",
      "name": "andy-cluster-test-01",
      "status": "Running",
      "owner": "user@kakaoenterprise.com",
      "clusterType": "hadoop",
      "clusterVersion": "hde-2.0.1",
      "isScalable": true,
      "apiKeyStatus": "impossible",
      "masterCnt": 1,
      "workerCnt": 1,
      "nodeCnt": 2,
      "createdAt": 1720797464322,
      "runningAt": 1720797856006,
      "elapsedTime": 827416064
    },
    {
      "id": "eb9a91ad-d1b6-462c-8e20-0e8b2c0aa074",
      "name": "test",
      "status": "Running",
      "owner": "user@kakaoenterprise.com",
      "clusterType": "dataflow",
      "clusterVersion": "hde-2.0.1",
      "isScalable": true,
      "apiKeyStatus": "impossible",
      "masterCnt": 1,
      "workerCnt": 2,
      "nodeCnt": 3,
      "createdAt": 1721131126322,
      "runningAt": 1721131467376,
      "elapsedTime": 493804694
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 5,
    "sort": {
      "empty": false,
      "unsorted": false,
      "sorted": true
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 2,
  "totalPages": 1,
  "last": true,
  "size": 5,
  "number": 0,
  "sort": {
    "empty": false,
    "unsorted": false,
    "sorted": true
  },
  "numberOfElements": 2,
  "first": true,
  "empty": false
}

클러스터의 VM 목록 조회

Open API를 통해 클러스터의 VM 목록을 조회합니다. 엔드포인트는 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터의 VM 목록 조회
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}/vms' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터의 VM 목록 조회
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}/vms' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Request Header

키	값
`{credential-id}`*	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급하여 확인 필요

Query Parameter

VM 목록 조회 시 다음과 같은 조건으로 조회할 수 있습니다. 조건이 여러 개일 경우 조건들을 &로 연결합니다.

키	자료형	설명	필수 여부	기본값
size	integer	페이지 크기로, 페이지 하나에서 조회할 수 있는 클러스터 개수입니다.	선택	20
page	integer	조회할 페이지의 번호입니다. 페이지 크기에 따라서 조회할 수 있는 페이지의 번호가 달라질 수 있습니다.	선택	0
ip	boolean	like 검색할 프라이빗 IP입니다. 입력하지 않은 경우 모든 VM을 조회합니다.	선택
name	string	like 검색할 이름입니다. 입력하지 않은 경우 모든 VM을 조회합니다.	선택
instanceId	string	like 검색할 인스턴스 ID입니다. 입력하지 않은 경우 모든 VM을 조회합니다.	선택
sort	string	정렬을 적용할 필드명과 정렬 방법입니다. 정렬할 필드명과 정렬 방법(asc 혹은 desc)을 ","로 연결하여 작성합니다. 예를 들어, name 필드를 내림차순 정렬할 경우 sort=name,desc로 입력하고, 정렬 조건을 여러 개 입력하는 경우 입력한 순서대로 정렬 우선순위가 적용됩니다. 정렬 적용이 가능한 필드입니다. name, instanceId, isMaster, flavorName, ip, floatingIp, createdAt	선택	createdAt,desc

Response

Response Example

응답 예시
{
  "content": [
    {
      "name": "string",
      "instanceId": "string",
      "index": integer,
      "isMaster": boolean,
      "status": "string",
      "flavorName": "string",
      "ip": "string",
      "floatingIp": "string",
      "createdAt": long,
    }
  ],
  "pageable": {
    "pageNumber": integer,
    "pageSize": integer,
    "sort": {
      "sorted": boolean,
      "unsorted": boolean,
      "empty": boolean
    },
    "offset": integer,
    "paged": boolean,
    "unpaged": boolean
  },
  "totalPages": integer,
  "totalElements": integer,
  "last": boolean,
  "numberOfElements": integer,
  "sort": {
    "sorted": boolean,
    "unsorted": boolean,
    "empty": boolean
  },
  "size": integer,
  "first": boolean,
  "number": integer,
  "empty": boolean
}

구분	설명
content	데이터가 위치하는 리스트
name	클러스터 이름
instanceId	vm 인스턴스 ID
index	vm 의 인덱스 예를 들어, HadoopMST-test-1 인 경우 마스터 1번 VM을 의미하며, index 값은 1
isMaster	마스터 vm 여부
status	vm 상태
flavorName	vm 의 플레이버 이름
ip	vm 의 프라이빗 IP
floatingIp	vm 의 퍼블릭 IP
createdAt	마스터 노드 개수
pageable	페이징 관련 정보
pageNumber	현재 페이지 번호
pageSize	현재 페이지 크기
sort	정렬 정보
sorted	정렬이 적용되어있는지 여부
unsorted	정렬이 적용되지 않았는지 여부
empty	정렬 조건이 비어있는지 여부
offset	페이지의 시작 지점
paged	페이징 적용 여부
unpaged	페이징이 적용되지 않았는지 여부
totalPages	총 페이지 수
totalElements	총 데이터 개수
last	현재 페이지가 마지막 페이지인지 여부
size	현재 페이지 크기
first	현재 페이지가 첫 페이지인지 여부
number	현재 페이지 번호
empty	현재 페이지가 비어있는지 여부

상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청
`401`	크리덴셜 인증 실패
`403`	권한 없음

클러스터 VM 목록 조회 예제 1

VM 목록 조회 조건

클러스터 ID가 31ca7ea4-93f3-4c76-9f9e-c0b3d947c17e 인 vm 목록 조회
페이지의 크기는 10이고, 페이지 번호는 0으로 설정
name 오름차순으로 정렬 적용

kr-central-1
kr-central-2

kr-central-1 클러스터의 VM 목록 조회 1
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/bbe8ce14-3497-476e-894c-142c48c9c469/vms?sort=name,asc&page=0&size=10' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터의 VM 목록 조회 1
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/bbe8ce14-3497-476e-894c-142c48c9c469/vms?sort=name,asc&page=0&size=10' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

예제 1 응답

클러스터의 VM 목록 조회 예제 1 응답
{
    "content": [
        {
            "name": "HadoopMST-test-cluster-1",
            "instanceId": "23948ac6-86e0-42f6-acdb-d214cdd200c0",
            "index": 1,
            "isMaster": true,
            "status": "Running",
            "flavorName": "m2a.xlarge",
            "ip": "10.0.129.243",
            "createdAt": 1719452777733
        },
        {
            "name": "HadoopWRK-test-cluster-1",
            "instanceId": "8606bbb2-52bf-4154-82f5-647c9da4ac2d",
            "index": 1,
            "isMaster": false,
            "status": "Running",
            "flavorName": "m2a.xlarge",
            "ip": "10.0.132.127",
            "createdAt": 1719452777733
        },
        {
            "name": "HadoopWRK-test-cluster-2",
            "instanceId": "7db47633-5676-42ad-bf34-c6e5da5c30c7",
            "index": 2,
            "isMaster": false,
            "status": "Running",
            "flavorName": "m2a.xlarge",
            "ip": "10.0.131.196",
            "createdAt": 1719413846446
        },
        {
            "name": "HadoopWRK-test-cluster-3",
            "instanceId": "2fdda50e-cf40-4976-a394-7ead7e32f042",
            "index": 3,
            "isMaster": false,
            "status": "Running",
            "flavorName": "m2a.xlarge",
            "ip": "10.0.128.201",
            "createdAt": 1719413114832
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 10,
        "sort": {
            "empty": false,
            "sorted": true,
            "unsorted": false
        },
        "offset": 0,
        "unpaged": false,
        "paged": true
    },
    "totalPages": 1,
    "totalElements": 4,
    "last": true,
    "size": 10,
    "number": 0,
    "sort": {
        "empty": false,
        "sorted": true,
        "unsorted": false
    },
    "numberOfElements": 4,
    "first": true,
    "empty": false
}

클러스터 VM 목록 조회 예제 2

VM 목록 조회 조건

클러스터 ID가 31ca7ea4-93f3-4c76-9f9e-c0b3d947c17e 인 vm 목록 조회
페이지의 크기는 10이고, 페이지 번호는 0으로 설정
name에 WRK 포함하도록 필터 적용
name 내림차순, status 오름차순으로 정렬 적용

kr-central-1
kr-central-2

kr-central-1 클러스터의 VM 목록 조회 2
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/31ca7ea4-93f3-4c76-9f9e-c0b3d947c17e/vms?name=WRK&page=0&size=10&sort=name,desc&sort=status,asc' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터의 VM 목록 조회 2
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/31ca7ea4-93f3-4c76-9f9e-c0b3d947c17e/vms?name=WRK&page=0&size=10&sort=name,desc&sort=status,asc' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

예제 2 응답

클러스터의 VM 목록 조회 예제 2 응답
{
  "content": [
    {
      "name": "HadoopWRK-hailey13-2",
      "instanceId": "10c5dfab-cae7-4b8c-a975-7b5d285482aa",
      "index": 2,
      "isMaster": false,
      "status": "Running",
      "flavorName": "m2a.xlarge",
      "ip": "10.0.2.159",
      "createdAt": 1721202811333
    },
    {
      "name": "HadoopWRK-hailey13-1",
      "instanceId": "e204678e-bf9d-4c3b-81ce-812ca09a78c3",
      "index": 1,
      "isMaster": false,
      "status": "Running",
      "flavorName": "m2a.xlarge",
      "ip": "10.0.3.96",
      "createdAt": 1721202811333
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": {
      "empty": false,
      "sorted": true,
      "unsorted": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 2,
  "totalPages": 1,
  "last": true,
  "size": 10,
  "number": 0,
  "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
  },
  "numberOfElements": 2,
  "first": true,
  "empty": false
}

클러스터 VM 목록 조회 예제 3

VM 목록 조회 조건

클러스터 ID가 31ca7ea4-93f3-4c76-9f9e-c0b3d947c17e 인 vm 목록 조회
페이지의 크기는 5이고, 페이지 번호는 0으로 설정
name에 hailey13을 포함하며, instanceId에 -4c3b 포함하도록 필터 적용
isMaster 내림차순, ip 오름차순으로 정렬 적용

kr-central-1
kr-central-2

kr-central-1 클러스터의 VM 목록 조회 3
curl -X GET 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/31ca7ea4-93f3-4c76-9f9e-c0b3d947c17e/vms?name=hailey13&instanceId=-4c3b&page=0&size=5&sort=isMaster,desc&sort=ip,asc' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터의 VM 목록 조회 3
curl -X GET 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/31ca7ea4-93f3-4c76-9f9e-c0b3d947c17e/vms?name=hailey13&instanceId=-4c3b&page=0&size=5&sort=isMaster,desc&sort=ip,asc' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

예제 3 응답

클러스터의 VM 목록 조회 예제 3 응답
{
  "content": [
    {
      "name": "HadoopWRK-hailey13-1",
      "instanceId": "e204678e-bf9d-4c3b-81ce-812ca09a78c3",
      "index": 1,
      "isMaster": false,
      "status": "Running",
      "flavorName": "m2a.xlarge",
      "ip": "10.0.3.96",
      "createdAt": 1721202811333
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 5,
    "sort": {
      "empty": false,
      "sorted": true,
      "unsorted": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 1,
  "totalPages": 1,
  "last": true,
  "size": 5,
  "number": 0,
  "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
  },
  "numberOfElements": 1,
  "first": true,
  "empty": false
}

클러스터 삭제

Open API를 통해 클러스터를 삭제합니다. 삭제된 클러스터는 복구할 수 없습니다. 엔드포인트는 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 삭제
curl -X DELETE 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터 삭제
curl -X DELETE 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Path Parameter

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

Request Header

키	값
`{credential-id}`*	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급 필요

Response

Response Example

응답 예시
{
  "id": "string",
  "name": "string",
  "status": "string"
}

클러스터 삭제 예제

삭제 조건

ID가 90ac14f2-3837-11ef-b1da-72300678fa60인 클러스터를 삭제하고자 할 경우 다음과 같이 요청합니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 삭제 예제
curl -X DELETE 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/90ac14f2-3837-11ef-b1da-72300678fa60' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

kr-central-2 클러스터 삭제 예제
curl -X DELETE 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/90ac14f2-3837-11ef-b1da-72300678fa60' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청
`401`	크리덴셜 인증 실패
`403`	권한 없음
`404`	클러스터가 존재하지 않음

클러스터 증설

Open API를 통해 클러스터의 워커 노드를 증설합니다. 엔드포인트는 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 증설
curl -X POST 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}/scale-out' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{Body}'

kr-central-2 클러스터 증설
curl -X POST 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}/scale-out' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{Body}'

Request

Path Parameter

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

Request Header

키	값
Content-Type*	`application/json`으로 고정
`{credential-id}`*	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급 필요

Request Body

증설할 노드 개수를 입력합니다.

응답 예시
{
  "scaleCnt": integer
}

Response

Response Example

응답 예시
{
  "id": "string",
  "name": "string",
  "status": "string"
}

클러스터 증설 예제

증설 조건

ID가 90ac14f2-3837-11ef-b1da-72300678fa60인 클러스터의 노드 개수를 3개 증설하고 싶은 경우 다음과 같이 요청합니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 증설 예제
curl -X POST ‘https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/90ac14f2-3837-11ef-b1da-72300678fa60/scale-out’ \
  --header ‘Credential-ID: {credential-id}’ \
  --header ‘Credential-Secret: {credential-secret}’ \
  --header ‘Content-Type: application/json’ \
  --data-raw '
{
 “scaleCnt”: 3
}'

kr-central-2 클러스터 증설 예제
curl -X POST ‘https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/90ac14f2-3837-11ef-b1da-72300678fa60/scale-out’ \
  --header ‘Credential-ID: {credential-id}’ \
  --header ‘Credential-Secret: {credential-secret}’ \
  --header ‘Content-Type: application/json’ \
  --data-raw '
{
 “scaleCnt”: 3
}'

상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청
`401`	크리덴셜 인증 실패
`403`	권한 없음
`404`	클러스터가 존재하지 않음

클러스터 축소

Open API를 통해 클러스터의 워커 노드를 축소합니다. 엔드포인트는 다음과 같습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 축소
curl -X POST 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/{cluster-id}/scale-in' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{Body}'

kr-central-2 클러스터 축소
curl -X POST 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/{cluster-id}/scale-in' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '{Body}'

Request

Path Parameter

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

Request Header

키	설명
Content-Type*	`application/json`으로 고정
`{credential-id}`*	사용자의 액세스 키 ID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
`{credential-secret}`*	사용자의 보안 액세스 키 - 액세스 키 생성 시에만 확인 가능 - 보안 액세스 키 분실 시, 신규 액세스 키를 발급 필요

Request Body

축소할 노드 개수를 입력합니다.

축소 후 남은 노드 개수가 클러스터의 hdfs.replication보다 크거나 같아야 합니다.

Request Body
{
  "scaleCnt": integer
}

Response

Response Example

응답 예시
{
  "id": "string",
  "name": "string",
  "status": "string"
}

클러스터 축소 예제

축소 조건

ID가 90ac14f2-3837-11ef-b1da-72300678fa60인 클러스터의 노드 개수를 5개 축소하고 싶은 경우 다음과 같이 요청합니다.
축소 후의 워커 노드 개수는 클러스터 생성 시 설정한 HDFS 복제 개수보다 작을 수 없습니다.

kr-central-1
kr-central-2

kr-central-1 클러스터 축소 예제
curl -X DELETE 'https://hadoop-eco.kr-central-1.kakaoi.io/v2/hadoop-eco/clusters/90ac14f2-3837-11ef-b1da-72300678fa60/scale-in' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '
{
  "scaleCnt": 5
}'

kr-central-2 클러스터 축소 예제
curl -X DELETE 'https://hadoop-eco.kr-central-2.kakaocloud.com/v2/hadoop-eco/clusters/90ac14f2-3837-11ef-b1da-72300678fa60/scale-in' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --data-raw '
{
  "scaleCnt": 5
}'

상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청
`401`	크리덴셜 인증 실패
`403`	권한 없음
`404`	클러스터가 존재하지 않음

시작하기 전에​

API 사용 준비​

API 엔드포인트​

Base64 변환 방법​

클러스터 생성​

Request​

Request Header​

Request Body​

기본 정보 입력​

fileUrl configText에 설정 정보 주입 예시​

설정 정보 주입​

userScript에 사용자 스크립트 입력 예시​

Response​

상태 코드​

클러스터 생성 예제 1​

클러스터 생성 예제 2​

클러스터 생성 예제 3​

클러스터 조회​

Request​

Path Parameter​

Request Header​

Response Example​

Response​

상태 코드​

클러스터 목록 조회​

Request​

Request Header​

Query Parameter​

Response​

Response Example​

상태 코드​

클러스터 목록 조회 예제 1​

클러스터 목록 조회 예제 2​

클러스터의 VM 목록 조회​

Request​

Request Header​

Query Parameter​

Response​

Response Example​

상태 코드​

클러스터 VM 목록 조회 예제 1​

클러스터 VM 목록 조회 예제 2​

클러스터 VM 목록 조회 예제 3​

클러스터 삭제​

Request​

Path Parameter​

Request Header​

Response​

Response Example​

클러스터 삭제 예제​

상태 코드​

클러스터 증설​

Request​

Path Parameter​

Request Header​

Request Body​

Response​

Response Example​

클러스터 증설 예제​

상태 코드​

클러스터 축소​

Request​

Path Parameter​

Request Header​

Request Body​

Response​

Response Example​

클러스터 축소 예제​

상태 코드​

시작하기 전에

API 사용 준비

API 엔드포인트

Base64 변환 방법

클러스터 생성

Request

Request Header

Request Body

기본 정보 입력

`fileUrl` `configText`에 설정 정보 주입 예시

설정 정보 주입

`userScript`에 사용자 스크립트 입력 예시

Response

상태 코드

클러스터 생성 예제 1

클러스터 생성 예제 2

클러스터 생성 예제 3

클러스터 조회

Request

Path Parameter

Request Header

Response Example

Response

상태 코드

클러스터 목록 조회

Request

Request Header

Query Parameter

Response

Response Example

상태 코드

클러스터 목록 조회 예제 1

클러스터 목록 조회 예제 2

클러스터의 VM 목록 조회

Request

Request Header

Query Parameter

Response

Response Example

상태 코드

클러스터 VM 목록 조회 예제 1

클러스터 VM 목록 조회 예제 2

클러스터 VM 목록 조회 예제 3

클러스터 삭제

Request

Path Parameter

Request Header

Response

Response Example

클러스터 삭제 예제

상태 코드

클러스터 증설

Request

Path Parameter

Request Header

Request Body

Response

Response Example

클러스터 증설 예제

상태 코드

클러스터 축소

Request

Path Parameter

Request Header

Request Body

Response

Response Example

클러스터 축소 예제

상태 코드