macOS에서 OCI HeatWave MySQL 접속하기: Bastion SSH 터널 설정 가이드

들어가며

Oracle Cloud의 HeatWave MySQL은 Private Subnet에 위치해서 직접 접속이 불가능합니다. 로컬 개발 환경에서 연결하려면 Bastion 서비스를 통한 SSH 터널이 필요한데, 처음 설정할 때 생각보다 많은 단계가 있어서 당황했습니다. OCI CLI 설치부터 API 키 등록, 터널 스크립트 작성까지 전체 과정을 정리해봤습니다.

사전 준비 사항

시작하기 전에 다음이 준비되어 있어야 합니다:

• Oracle Cloud 계정 및 HeatWave MySQL 인스턴스
• Bastion 서비스 생성 완료
• SSH 키 쌍 (~/.ssh/id_rsa, id_rsa.pub)

1. OCI CLI 설치

macOS에서는 Homebrew로 간단하게 설치할 수 있습니다.

brew install oci-cli

2. OCI CLI 초기 설정

설치 후 설정 마법사를 실행합니다.

oci setup config

설정 과정에서 입력해야 할 항목들입니다:

Config 파일 위치

기본값 /Users/사용자명/.oci/config를 그대로 사용하면 됩니다. Enter를 누르세요.

User OCID

OCI 콘솔에서 확인합니다:

프로필 아이콘 → User settings → OCID 복사

ocid1.user.oc1..aaaaaaaxxxxxxxxx 형식의 문자열입니다.

Tenancy OCID

마찬가지로 OCI 콘솔에서:

프로필 아이콘 → Tenancy: [이름] 클릭 → OCID 복사

Region

HeatWave가 위치한 리전을 선택합니다. 저는 South Korea North(Chuncheon)를 사용해서 ap-chuncheon-1을 선택했습니다.

API 키 생성

새 API 키를 생성할지 묻는 질문에 Y를 입력합니다. 키 저장 위치와 이름은 기본값(Enter)으로 진행하고, passphrase는 N/A를 입력하면 비밀번호 없이 사용할 수 있습니다.

3. API 공개키를 OCI 콘솔에 등록

생성된 공개키를 OCI에 등록해야 CLI가 인증됩니다.

cat ~/.oci/oci_api_key_public.pem

출력된 키 전체(-----BEGIN PUBLIC KEY----- 부터 -----END PUBLIC KEY----- 까지)를 복사합니다.

OCI 콘솔에서:

프로필 → User settings → API keys → Add API key
→ Paste a public key 선택 → 키 붙여넣기 → Add

연결 테스트

설정이 제대로 됐는지 확인합니다:

oci iam region list --output table

리전 목록이 출력되면 성공입니다.

4. Bastion 터널 스크립트 작성

매번 긴 명령어를 입력하기 번거로워서 스크립트로 만들었습니다.

#!/bin/bash

# ===== 설정 (본인 값으로 변경) =====
BASTION_OCID="ocid1.bastion.oc1.ap-chuncheon-1.xxxxx"
TARGET_IP="10.0.1.xxx"
TARGET_PORT="3306"
LOCAL_PORT="3306"
SSH_KEY_PATH="$HOME/.ssh/id_rsa"
SESSION_TTL="10800"

echo "🔄 Bastion 세션 생성 중..."

# 세션 생성
SESSION_RESULT=$(oci bastion session create-port-forwarding \
    --bastion-id "$BASTION_OCID" \
    --display-name "heatwave-tunnel-$(date +%Y%m%d-%H%M%S)" \
    --ssh-public-key-file "${SSH_KEY_PATH}.pub" \
    --target-private-ip "$TARGET_IP" \
    --target-port "$TARGET_PORT" \
    --session-ttl "$SESSION_TTL" \
    --wait-for-state SUCCEEDED \
    --wait-for-state FAILED \
    2>&1)

# JSON만 추출 (텍스트 메시지 제거)
SESSION_JSON=$(echo "$SESSION_RESULT" | sed -n '/{/,$p')

# 세션 ID 추출
SESSION_ID=$(echo "$SESSION_JSON" | jq -r '.data.resources[0].identifier')

BASTION_HOST="host.bastion.ap-chuncheon-1.oci.oraclecloud.com"

echo "✅ 세션 생성 완료"
echo "🚀 SSH 터널 연결 시작"
echo "접속 정보: localhost:${LOCAL_PORT}"

# SSH 터널 실행
ssh -i "$SSH_KEY_PATH" \
    -N \
    -L "${LOCAL_PORT}:${TARGET_IP}:${TARGET_PORT}" \
    -p 22 \
    "${SESSION_ID}@${BASTION_HOST}"

스크립트 설정값 확인

• BASTION_OCID: OCI 콘솔 → Identity & Security → Bastion에서 확인
• TARGET_IP: HeatWave MySQL의 Private IP (Databases → DB Systems에서 확인)
• BASTION_HOST: 리전에 맞게 수정 (ap-seoul-1, ap-chuncheon-1 등)

실행 권한 부여 및 실행

chmod +x heatwave-tunnel.sh
./heatwave-tunnel.sh

5. MySQL 접속

터널이 연결된 상태에서 새 터미널을 열고:

mysql -h 127.0.0.1 -P 3306 -u 사용자명 -p

또는 TablePlus, DBeaver 같은 GUI 클라이언트에서:

Host: 127.0.0.1
Port: 3306
Username: HeatWave 생성 시 설정한 사용자명
Password: HeatWave 생성 시 설정한 비밀번호

트러블슈팅

jq parse error

OCI CLI 출력에 텍스트 메시지와 JSON이 섞여 있어서 발생합니다. sed -n '/{/,$p'로 JSON 부분만 추출하면 해결됩니다.

세션 생성은 성공했는데 실패로 표시

OCI CLI가 대기 상태 메시지에 'FAILED' 문자열을 포함해서 단순 grep으로 판별하면 오탐이 발생합니다. jq로 .data.status 필드를 직접 확인하는 방식으로 수정해야 합니다.

Permission denied

스크립트에 실행 권한이 없으면 발생합니다. chmod +x 스크립트명.sh로 해결합니다.

보안 고려사항

스크립트에 BASTION_OCID, TARGET_IP 같은 인프라 정보가 포함되어 있으므로 .gitignore에 추가하는 것이 좋습니다. 환경변수로 분리하는 방법도 있지만, 로컬 개발용이라면 gitignore로 충분하다는 생각이 들었습니다.

마치며

처음에는 2차 인증이나 복잡한 절차가 필요할 것 같아 걱정했는데, API 키 기반 인증을 사용하면 한 번 설정해두고 편하게 쓸 수 있었습니다. Bastion 세션은 최대 3시간(10800초)까지 유지되고, 만료되면 스크립트를 다시 실행하면 됩니다. 로컬에서 HeatWave를 활용한 개발이 한결 수월해졌습니다.