Yhdistäminen Roihun FirecREST HPC APIin

Pääsytunnisteet ovat salaisuuksia

FirecREST HPC APIa varten myönnetyt pääsytunnisteet antavat tunnisteen haltijalle mahdollisuuden käsitellä Slurm-töitä sekä lukea, muokata ja siirtää dataa sinun käyttöoikeuksillasi. Älä jaa pääsytunnistettasi kenellekään.

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

Mahdolliset suuret tai rikkovat muutokset APIin 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 erilaisia määritysasetuksia. Ne tunnistetaan alijärjestelmätunnisteella API-päätepisteiden URL-osoitteissa (esim. /v1/compute/<subsystem>/jobs).

API- ja alijärjestelmäasetukset osoitteessa 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 APIin

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

Jotta voit yhdistää API-päätepisteeseen, tokenit lähetetään FirecRESTille tavallisessa Authorization-otsakkeessa, 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ä. Tokenin voimassaolo tarkistetaan palvelinpuolella jokaisen pyynnön yhteydessä. Yritys käyttää virheellistä pääsytunnistetta johtaa HTTP 401 Unauthorized -paluuarvoon, ja tarkempi virheilmoitus tallennetaan vastauksen runkona olevaan JSON-dokumenttiin.

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

Yhdistäminen henkilökohtaisella pääsytunnisteella

FirecREST HPC APIa voidaan käyttää henkilökohtaisilla pääsytunnisteilla, jotka antavat pääsyn samoihin laskentaresursseihin ja projekteihin kuin suora pääsysi komentoriville. Henkilökohtaiset pääsytunnisteet ovat hyödyllisiä työpöytäsovelluksissa tai automaatiotyökaluissa interaktiivisissa päätteissä, jotka integroituvat HPC-resursseihin esimerkiksi PyFirecREST Python SDK:n avulla.

Kuten nimi kertoo, henkilökohtaiset pääsytunnisteet on tarkoitettu henkilökohtaiseen käyttöön. Projektikohtaista robottitiliä tulee käyttää toteutettaessa koneelta koneelle -HPC API -integraatiota päätteettömiin ei-interaktiivisiin järjestelmiin.

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

Voit tarkastella aktiivisia tunnisteitasi ja peruuttaa ne CSC IdP:n yhdistetyllä henkilökohtaisen profiilin sivulla kohdassa Connected organizations -> Firecrest-access-tokens.

Yhdistäminen robottitilillä

Note

Robottitilejä ei vielä tueta; tuki on tulossa vuoden 2026 kolmannella neljänneksellä.

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

Samoin kuin henkilökohtaisissa pääsytunnisteissa, myös APIin yhdistäminen robottitilillä edellyttää JWT bearer -tokenin toimittamista valtuutustietona. Robottitilit voivat pyytää sopivan JWT:n CSC IdP:n token-päätepisteestä käyttäen tavallista OAuth 2.0 Client Credentials Grant -menetelmää.

Asiakasvaltuusmäärityksessä 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ääsytunnisteen 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ääsytunnisteen ja siihen liittyvät metatiedot (tokenin tyyppi, scope ja voimassaoloaika).