Yhdistäminen Roihu FirecREST HPC API:in

Pääsytunnukset ovat salaisuuksia

FirecREST HPC API:lle myönnetyt pääsytunnukset antavat tunnuksen haltijalle mahdollisuuden olla vuorovaikutuksessa Slurm-töiden kanssa sekä lukea, käsitellä ja siirtää dataa sinun käyttöoikeuksillasi. Älä jaa pääsytunnustasi kenellekään.

Roihu FirecREST HPC API:n päätepisteet löytyvät URL-osoitteesta https://api.roihu.csc.fi. Palvelu käyttää versioitua URL-rakennetta, jossa URL-polun ensimmäinen osa edustaa API-sukupolvea. Nykyinen ja uusin API-sukupolvi on v1. Se perustuu FirecREST v2:n uusimpaan julkaisuun.

Mahdolliset suuret tai rikkovat muutokset API:in julkaistaan uutena API-sukupolvena. Oletuksena uusi julkaisu ei korvaa olemassa olevia API-versioita. Aiemmat sukupolvet ylläpidetään ja pidetään saatavilla.

Alijärjestelmät

FirecREST HPC API tukee useita alijärjestelmiä, joilla on erilaiset konfigurointivaihtoehdot ja jotka tunnistetaan alijärjestelmätunnisteella API-päätepisteiden URL-osoitteissa (esim. /v1/compute/<subsystem>/jobs).

API:n ja alijärjestelmien konfiguraatio palvelussa api.roihu.csc.fi:

API-sukupolvi	API-alijärjestelmä	Osiot	Datan siirto
`v1`	`cpu`	Kaikki CPU-osiot	S3 Allaksen kautta, esiallekirjoitetut URL-osoitteet
`v1`	`gpu`	Kaikki GPU-osiot	S3 Allaksen kautta, esiallekirjoitetut URL-osoitteet

API-dokumentaatio

Ajantasainen v1-version API-määritys on saatavilla OpenAPI-muodossa osoitteessa https://api.roihu.csc.fi/v1/openapi.json, ja sitä voi tarkastella FirecRESTin Swagger UI:ssa osoitteessa https://api.roihu.csc.fi/v1/docs/.

Yhdistäminen API:in

FirecREST HPC API käyttää valtuutusmenetelmänä JWT bearer -tunnuksia. Hyväksytyt tunnukset myöntää CSC:n tunnistus- ja valtuutusinfrastruktuurin (AAI) identiteetintarjoaja (IdP). API hyväksyy vain ne tunnukset, jotka on erikseen myönnetty käytettäväksi FirecREST HPC API:n kanssa (tämä ilmaistaan JWT:n aud-jäsenellä).

Jotta voit yhdistää API-päätepisteeseen, tunnukset lähetetään FirecRESTille tavallisella Authorization-otsakkeella, esimerkiksi:

access_token="<JWT>"
curl -X GET https://api.roihu.csc.fi/v1/compute/cpu/jobs \
  -H "Authorization: Bearer ${access_token}"

Authorization-otsakkeen on oltava mukana jokaisessa FirecRESTille lähetettävässä API-pyynnössä. Tunnuksen voimassaolo tarkistetaan palvelinpuolella jokaisen pyynnön yhteydessä. Yritys käyttää virheellistä pääsytunnusta johtaa HTTP 401 Unauthorized -paluukoodiin, ja tarkempi virheilmoitus tallennetaan vastauksen runkona olevaan JSON-dokumenttiin.

Kaikki API:lle lähetetyt pyynnöt suoritetaan Roihussa samalla käyttäjätilillä, jota käytettiin pääsytunnuksen hakemiseen. Esimerkiksi henkilökohtaisella pääsytunnuksella kaikki FirecRESTin kautta ajettavat komennot suoritetaan kohdejärjestelmässä sinun käyttäjänäsi.

Yhdistäminen henkilökohtaisella pääsytunnuksella

FirecREST HPC API:a voidaan käyttää henkilökohtaisilla pääsytunnuksilla, jotka mahdollistavat pääsyn samoihin laskentaresursseihin ja projekteihin kuin suora pääsysi komentoriville. Henkilökohtaiset pääsytunnukset ovat hyödyllisiä työpöytäsovellusten tai automaatiotyökalujen ajamiseen interaktiivisissa päätteissä, kun ne integroituvat HPC-resursseihin esimerkiksi PyFirecREST Python SDK:n avulla.

Kuten nimi kertoo, henkilökohtaiset pääsytunnukset on tarkoitettu henkilökohtaiseen käyttöön. Projektikohtaista robottitiliä tulisi käyttää toteutettaessa koneelta koneelle -HPC API -integraatiota päättömissä ei-interaktiivisissa järjestelmissä.

Henkilökohtaisen pääsytunnuksen voi hakea MyCSC-portaalista. Huomaa, että portaalissa ei vielä ole suoraa linkkiä tähän. Henkilökohtaiset pääsytunnukset ovat voimassa 24 tuntia kerrallaan.

Voit tarkastella ja peruuttaa aktiiviset tunnuksesi CSC IdP:n federoidulla henkilökohtaisen profiilin sivulla kohdassa Connected organizations -> Firecrest-access-tokens.

Yhdistäminen robottitilillä

Koneelta koneelle -robottitilit voivat käyttää Roihun laskentaresursseja FirecREST HPC API:n kautta.

Samoin kuin henkilökohtaisilla pääsytunnuksilla, myös robottitilillä API:in yhdistäminen edellyttää JWT bearer -tunnuksen toimittamista valtuutustietona. Robottitilit voivat pyytää sopivan JWT:n CSC IdP:n tunnuspäätepisteestä käyttäen tavallista OAuth 2.0 Client Credentials Grant -menetelmää.

Asiakasvaltuuksien konfiguroinnissa tyypillisesti tarvittavat asetukset:

Asetus	Arvo
Client ID	Robottitilisi käyttäjätunnus
Client Secret	Robottitilisi salasana
Token URL	`https://user-auth.csc.fi/idp/profile/oidc/token`
Scope	`openid`

Voit esimerkiksi hakea robottitilin pääsytunnuksen yksinkertaisella curl-kutsulla:

curl -X POST https://user-auth.csc.fi/idp/profile/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "client_id=${my_robot_username}&client_secret=${my_robot_password}&scope=openid&grant_type=client_credentials"

Onnistunut kutsu palauttaa JSON-dokumentin, joka sisältää pääsytunnuksen ja siihen liittyvät metatiedot (tunnuksen tyyppi, scope ja voimassaoloaika).