빠른 시작

1. API 키 생성

고객 포털의 "KernelHost API"에 접속해 로그인하신 후 키를 생성하십시오. 실제로 필요한 권한 범위만 선택하시기 바랍니다(기본값: 읽기 전용). 시크릿은 단 한 번만 표시되므로 시크릿 관리 도구에 안전하게 보관하십시오.

2. 자격증명 저장

키와 시크릿을 환경 변수로 저장해 주세요. 코드 안이나 저장소에는 절대로 두지 마세요.

# .env 또는 셸 프로필
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. 첫 요청 전송

사용 가능한 제품 목록을 조회해 주세요. 서명은 메서드, 경로, 타임스탬프, 논스, 본문 해시를 기반으로 생성돼요.

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
SIG_INPUT=$(printf 'GET\n/v1/products\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')

curl https://www.kernelhost.com/cp/kernelhost_api/v1/products \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

4. 주문 처리

중요: POST /v1/orders에는 Idempotency-Key와 호스트 이름이 필요합니다. 네트워크 오류 후 같은 키로 요청을 재시도하면 두 번째 주문이 생성되는 대신 동일한 응답이 반환됩니다. 지정하지 않은 구성 옵션(예: 서버 위치나 운영체제)에는 스토어에서 제공하는 첫 번째 값이 적용됩니다.

BODY='{"product_id":42,"billing_cycle":"monthly","hostname":"web01.example.com"}'
IDEM="order-web01-$(date +%Y%m%d)"
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIG_INPUT=$(printf 'POST\n/v1/orders\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')

curl -X POST https://www.kernelhost.com/cp/kernelhost_api/v1/orders \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  --data "$BODY"

5. 상태 확인 및 자격증명 조회

주문 응답에는 service_ids가 포함되어 있습니다. status가 active가 되고 IP 주소가 할당될 때까지 GET /v1/services/{id}를 반복해서 호출하십시오. 프로비저닝에는 보통 몇 초에서 몇 분 정도 걸립니다. 그다음 GET /v1/services/{id}/credentials(권한 범위 read:credentials)를 호출하면 호스트 이름, IP 주소, 사용자 이름, 비밀번호가 반환되며, 예를 들어 Ansible 인벤토리에 활용하실 수 있습니다.

kh_get() {
  TS=$(date +%s)
  NONCE=$(openssl rand -hex 16)
  BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
  SIG_INPUT=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$TS" "$NONCE" "$BODY_SHA256")
  SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')
  curl -s "https://www.kernelhost.com/cp/kernelhost_api$1" \
    -H "KH-Key: $KH_KEY" \
    -H "KH-Timestamp: $TS" \
    -H "KH-Nonce: $NONCE" \
    -H "KH-Signature: $SIG"
}

kh_get /v1/services/1234
kh_get /v1/services/1234/credentials

6. 웹훅 URL 등록 (선택)

키마다 HTTPS URL을 미리 등록해 두실 수 있습니다. 이벤트 전송은 준비 중이며, 그때까지는 5단계의 상태 조회를 이용하십시오.