EDB Hybrid Manager API 활용: Bash와 Curl로 Postgres 클러스터 배포 자동화하기
Manni Wood
2025년 12월 12일
EDB Hybrid Manager의 가장 강력한 기능 중 하나는 바로 API입니다. “REST를 말할 수 있는” 모든 도구는 이 API를 통해 Hybrid Manager를 제어할 수 있습니다.
GUI(그래픽 사용자 인터페이스)는 직관적이지만, 반복적인 운영 업무나 대규모 배포 환경에서는 스크립트를 통한 자동화가 필수적입니다. 이번 포스팅에서는 bash와 curl만을 사용하여 EDB Hybrid Manager에서 Postgres 클러스터를 생성하는 전체 과정을 단계별로 소개합니다.
1. 보안 설정: 머신 유저(Machine User) 및 API 키 생성
API를 사용하기 위해서는 먼저 인증 체계를 갖춰야 합니다. 이는 1회성 작업이지만 보안을 위해 반드시 거쳐야 할 단계입니다.
- 액세스 키 생성: Hybrid Manager UI 우측 상단의 드롭다운 메뉴에서 **[Users]**를 클릭합니다.
- 머신 유저 설정: ‘Create Access Key’ 체크박스를 선택하고 만료일(Expiry date)을 설정합니다.
- 키 저장: 생성된 API Key는 다시 조회할 수 없으므로 안전한 곳에 반드시 저장하십시오.
2. 프로젝트 권한 할당
생성한 머신 유저(API Key)가 특정 프로젝트에 접근하여 리소스를 생성할 수 있도록 권한을 부여해야 합니다.
- 좌측 네비게이션 상단에서 대상 프로젝트를 선택합니다.
- [Users] 메뉴로 이동하여 목록에 있는 머신 유저를 확인합니다.
- 연필 아이콘(수정)을 클릭하고 [Assign Roles] 버튼을 누릅니다.
- 권한 부여: 클러스터 생성이 가능한 권한을 부여합니다.
- 참고: 보안상 ‘최소 권한의 원칙(Principle of Least Privilege)’을 따르는 것이 좋으나, 본 데모에서는 편의상
Project Owner권한을 부여했습니다.
- 참고: 보안상 ‘최소 권한의 원칙(Principle of Least Privilege)’을 따르는 것이 좋으나, 본 데모에서는 편의상
3. 환경 변수 파일 구성 (env.sh)
스크립트의 재사용성을 높이기 위해 주요 정보를 변수로 관리합니다. env.sh 파일을 생성하여 다음 정보를 입력합니다.
- HM_API_ACCESS_KEY: 앞서 저장한 API 키.
- HM_PROJECT_ID: 브라우저 URL에서 확인 가능한 프로젝트 ID.
- HM_API_URL_PREFIX: Hybrid Manager 엔드포인트 URL.
Bash
# env.sh 예시 export HM_API_ACCESS_KEY="baak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" export HM_PROJECT_ID="prj_jJbUkkVsxiY8RdAM" export HM_API_URL_PREFIX="https://portal.somehostname.org"
4. 배포 위치 및 이미지 정보 확인 (GET /locations)
클러스터를 생성하려면 배포할 ‘위치(Location)’와 사용할 ‘Postgres 이미지(Image)’의 정확한 정보(URL, Digest)가 필요합니다. 이를 API로 조회합니다.
get-locations.sh 작성:
Bash
#!/bin/bash
set -e
set -u
set -o pipefail
HERE=$(dirname ${BASH_SOURCE[0]})
source ${HERE}/env.sh
# 위치 정보 조회 API 호출
curl \
--header "Content-Type: Application/JSON" \
--header "x-access-key: ${HM_API_ACCESS_KEY}" \
--request GET \
"${HM_API_URL_PREFIX}/api/v1/projects/${HM_PROJECT_ID}/locations" \
| jq
위 스크립트를 실행(chmod +x 후 실행)하여 출력된 JSON 결과에서 원하는 스펙의 locationId와 imageRef (url, digest) 정보를 확인합니다.
5. 클러스터 생성 요청 (POST /clusters)
이제 실제 클러스터를 생성합니다. 여기서 envsubst 명령어를 활용하면 JSON 템플릿에 환경변수를 동적으로 주입할 수 있어 매우 효율적입니다.
입력 JSON 템플릿 (create-cluster.json): 프로젝트 ID 부분에 변수(${HM_PROJECT_ID})가 사용된 것을 확인하십시오.
JSON
{
"projectId": "${HM_PROJECT_ID}",
"psr": {
"clusterName": "Basic Cluster",
"password": "사용할_패스워드_입력",
"locationId": "managed-primary",
"clusterData": {
"instances": 1,
"storageConfiguration": {
"primaryStorage": {
"size": "1"
}
},
"image": {
"url": "url.to.private.docker.repository.org/postgresql:17.7-xxx",
"digest": "sha256:636f1d1c9865e95e43c593d26b35214df533af977605c084395f4a20e9dbde67"
}
}
}
}
최종 생성 스크립트 (create-cluster.sh):
Bash
#!/bin/bash
set -e
set -u
set -o pipefail
HERE=$(dirname ${BASH_SOURCE[0]})
source ${HERE}/env.sh
# 템플릿에 환경변수를 주입하여 임시 JSON 생성
cat create-cluster.json | envsubst > /tmp/create-cluster.json
# 클러스터 생성 API 호출
curl \
--header "Content-Type: Application/JSON" \
--header "x-access-key: ${HM_API_ACCESS_KEY}" \
--data-binary "@/tmp/create-cluster.json" \
--request POST \
"${HM_API_URL_PREFIX}/api/v1/projects/${HM_PROJECT_ID}/clusters"
6. 결과 확인
스크립트를 실행하면 다음과 같이 생성된 클러스터의 ID가 반환됩니다.
Bash
$ chmod +x ./create-cluster.sh
$ ./create-cluster.sh
{"clusterId":"p-b9pgze95as"}
Hybrid Manager UI에서 해당 클러스터가 ‘Creating’ 상태를 거쳐 정상적으로 배포되는 것을 확인할 수 있습니다.
마치며
초기 보안 설정(API 키 생성) 과정이 다소 번거로울 수 있지만, 이는 1회성 작업입니다. 이 설정이 완료되면, API 문서와 간단한 bash 스크립트만으로 Hybrid Manager의 모든 기능을 코드 레벨에서 제어하고 자동화할 수 있습니다. 이는 DevOps 파이프라인 구축 및 대규모 인프라 운영에 있어 필수적인 역량입니다.
메일: salesinquiry@enterprisedb.com
