Wolkra

Dokumentaatio

API-tunnisteet

Näin luot Wolkran API-tunnisteita wk_-etuliitteellä, valitset luku- tai luku- ja kirjoitusoikeuden, IP-sallittujen listan ja vanhenemisen sekä kutsut REST API:a Bearer-otsakkeella.

Päivitetty 2 min lukuaika

Wolkran API-tunnisteet ovat projektikohtaisia avaimia, jotka alkavat merkkijonolla wk_. Lähetä tunniste Authorization: Bearer -otsakkeessa kutsuessasi REST API:a osoitteessa https://api.wolkra.com/v1. Tunnisteella voi olla luku- tai luku- ja kirjoitusoikeus, valinnainen IP-sallittujen lista ja valinnainen vanhenemispäivä.

Luo tunniste

  1. Vaihda konsolissa siihen projektiin, johon tunnisteen tulee antaa pääsy.
  2. Avaa API-tunnisteet ja valitse Luo tunniste.
  3. Anna sille nimi, joka kertoo käyttökohteen, esimerkiksi ci-deploy tai monitoring-readonly.
  4. Valitse käyttöoikeustaso:
    • Luku: vain resurssien listaus ja tarkastelu.
    • Luku ja kirjoitus: lisäksi resurssien luonti, muuttaminen ja poisto.
  5. Lisää halutessasi IP-sallittujen lista: vain näistä osoitteista tai osoitealueilta tulevat pyynnöt hyväksytään.
  6. Aseta halutessasi vanhenemispäivä.
  7. Luo tunniste ja kopioi se heti. Säilytä sitä kuin salasanaa, esimerkiksi salaisuuksien hallintatyökalussa tai CI-järjestelmäsi salaisissa muuttujissa.

Tee ensimmäinen pyyntö

Listaa projektin palvelimet:

bash
curl -H "Authorization: Bearer wk_…" https://api.wolkra.com/v1/servers

Skripteissä tunniste kannattaa pitää ympäristömuuttujassa eikä itse komennossa:

bash
export WOLKRA_TOKEN='wk_…'
curl -s -H "Authorization: Bearer $WOLKRA_TOKEN" https://api.wolkra.com/v1/servers | jq .

jq (asennus komennolla sudo apt install -y jq) muotoilee JSON-vastauksen luettavaksi.

Resurssit

API kattaa samat resurssit kuin konsoli:

Polku Resurssi
/servers pilvipalvelimet
/ssh_keys tallennetut SSH-avaimet
/volumes lohkotallennuslevyt
/networks yksityisverkot
/firewalls palomuurit
/load_balancers kuormantasaajat
/floating_ips kelluvat IP-osoitteet
/actions toiminnot, kuten virtatilan muutokset, tiloineen

Kaikki polut ovat suhteessa osoitteeseen https://api.wolkra.com/v1. Esimerkiksi levyjen listaus:

bash
curl -s -H "Authorization: Bearer $WOLKRA_TOKEN" https://api.wolkra.com/v1/volumes

Toiminnot

Aikaa vievät muutokset, kuten palvelimen käynnistäminen tai levyn liittäminen, suoritetaan toimintoina. Tarkista niiden eteneminen polusta /actions ennen kuin jatkat skriptiä, sen sijaan että olettaisit muutoksen valmistuneen.

Virheet

API vastaa tavallisilla HTTP-tilakoodeilla. Tyypilliset merkitykset:

Tila Merkitys
401 Tunniste puuttuu, on väärä tai vanhentunut
403 Ei sallittu, esimerkiksi kirjoitus pelkällä lukutunnisteella tai pyyntö sallittujen listan ulkopuolelta
404 Resurssia ei ole tässä projektissa
429 Liikaa pyyntöjä; odota ja yritä uudelleen
5xx Tilapäinen ongelma; yritä uudelleen viiveellä

Tulosta tilakoodi vianetsinnän aikana:

bash
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $WOLKRA_TOKEN" https://api.wolkra.com/v1/servers

Hyvät käytännöt

  • Yksi tunniste käyttökohdetta kohden. Yksi tunniste CI:lle, toinen valvonnalle, kolmas kannettavallesi. Voit mitätöidä yhden rikkomatta muita.
  • Vähimmät oikeudet. Käytä lukutunnisteita kojelaudoissa ja valvonnassa.
  • Rajaa osoitteen mukaan. Lisää IP-sallittujen lista tunnisteille, joita käytetään kiinteiltä palvelimilta tai CI-ajureilta.
  • Aseta vanhenemispäivä tunnisteille, jotka on tarkoitettu tilapäiseen projektiin tai henkilölle, joka on lähdössä.
  • Älä koskaan tallenna tunnisteita gitiin. Jos tunniste vuotaa, poista se konsolissa heti ja luo uusi.
  • Käy läpi tunnisteluettelo ja organisaation tapahtumaloki aika ajoin.

Mitätöi tunniste

Avaa API-tunnisteet, etsi tunniste ja poista se. Sitä käyttävät pyynnöt epäonnistuvat siitä lähtien.

Automaatio

Skriptit kutsuvat API:a suoraan HTTPS:n yli. curl, Pythonin requests, Gon net/http tai mikä tahansa HTTP-asiakas toimii. Yhdistä API ja cloud-init-käyttäjädata, niin palvelimet määrittyvät kokonaan jo ensimmäisellä käynnistyksellä.

Lisää tuotesivulla: API. Tilin oman suojauksen ohjeet löydät sivulta tilin tietoturva.

Usein kysytyt kysymykset

Missä Wolkran API on?

Osoitteessa https://api.wolkra.com/v1. Se on REST API, joka käyttää JSONia ja Bearer-tunnistetodennusta.

Mihin tunniste antaa pääsyn?

Yhteen projektiin. Jokainen tunniste kuuluu siihen projektiin, jossa se luotiin, ja sillä on joko luku- tai luku- ja kirjoitusoikeus projektin resursseihin.

Voinko rajata tunnisteen palvelimieni osoitteisiin?

Kyllä. Lisää IP-sallittujen lista tunnistetta luodessasi, niin kaikista muista osoitteista tulevat pyynnöt hylätään.

Millä työkaluilla API:a voi kutsua?

Millä tahansa HTTP-asiakkaalla: curl, Python requests, Go net/http, JavaScript fetch tai CI-järjestelmäsi HTTP-vaiheet.