Szybki start

1. Utworzenie klucza API

Proszę zalogować się w panelu klienta w sekcji "KernelHost API" i utworzyć klucz. Należy wybrać tylko te zakresy uprawnień, które są rzeczywiście potrzebne (domyślnie: tylko odczyt). Tajny klucz jest wyświetlany tylko raz, dlatego proszę bezpiecznie przechować go w menedżerze sekretów.

2. Zapisanie danych dostępowych

Klucz i tajny klucz należy zapisać jako zmienne środowiskowe. Nigdy w kodzie, nigdy w repozytorium.

# .env lub profil powłoki
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Wysłanie pierwszego żądania

Pobieranie listy dostępnych produktów. Podpis jest tworzony na podstawie metody, ścieżki, znacznika czasu, nonce oraz skrótu treści.

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. Złożenie zamówienia

Ważne: POST /v1/orders wymaga nagłówka Idempotency-Key oraz nazwy hosta. Jeśli po błędzie sieci ponowią Państwo żądanie z tym samym kluczem, otrzymają tę samą odpowiedź zamiast drugiego zamówienia. Pominięte opcje konfiguracyjne (na przykład lokalizacja lub system operacyjny) otrzymują pierwszą wartość oferowaną w sklepie.

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. Sprawdzenie statusu i odczytanie danych dostępowych

W odpowiedzi na zamówienie znajduje się lista service_ids. Proszę cyklicznie wywoływać GET /v1/services/{id}, aż status zmieni się na active i zostanie przypisany adres IP; udostępnienie usługi trwa zwykle od kilku sekund do kilku minut. Następnie GET /v1/services/{id}/credentials (zakres read:credentials) zwraca nazwę hosta, adresy IP, nazwę użytkownika i hasło, na przykład do Państwa inwentarza 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. Zapisanie URL webhooka (opcjonalnie)

Już teraz mogą Państwo zapisać adres URL HTTPS dla każdego klucza. Dostarczanie zdarzeń jest w przygotowaniu; do tego czasu proszę korzystać z zapytań o status opisanych w kroku 5.