Yhdistäminen FirecREST HPC APIin

Pääsytunnukset ovat salaisuuksia

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

Jos epäilet, että henkilökohtainen pääsytunnuksesi on voinut vaarantua, tunnus tulee perua mahdollisimman pian.

FirecREST HPC API:n päätepisteet löytyvät seuraavista URL-osoitteista:

LUMI: https://api.lumi.csc.fi.
Roihu: https://api.roihu.csc.fi.

HPC API -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 API-päätepisteiden URL-osoitteissa alijärjestelmätunnisteella (esim. /v1/compute/<subsystem>/jobs).

LUMI API:n määritystiedot

API- ja alijärjestelmämääritykset osoitteessa api.lumi.csc.fi:

API generation	API subsystem	Partitions	Data transfer
`v1`	`lumi`	LUMI-C, LUMI-G, LUMI-D	S3 via LUMI-O, pre-signed URLs

Roihu API:n määritystiedot

API- ja alijärjestelmämääritykset osoitteessa api.roihu.csc.fi:

API generation	API subsystem	Partitions	Data transfer
`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 API-määritys versiolle v1 on saatavilla OpenAPI-muodossa /v1/openapi.json -päätepisteestä kaikissa FirecREST API -instansseissa (esimerkiksi https://api.roihu.csc.fi/v1/openapi.json). API-dokumentaatiota voi tarkastella FirecRESTin Swagger UI:n kautta osoitteessa /v1/docs/ (esimerkiksi https://api.roihu.csc.fi/v1/docs/).

Yhdistäminen APIin

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 -paluuarvoon, ja tarkempi virheilmoitus tallennetaan vastauksen runkona olevaan JSON-dokumenttiin.

Kaikki APIlle lähetetyt pyynnöt suoritetaan kohdejärjestelmässä samalla käyttäjätilillä, jota käytettiin pääsytunnuksen hakemiseen. Esimerkiksi henkilökohtaisella pääsytunnuksella kaikki FirecRESTin kautta ajettavat komennot suoritetaan omalla käyttäjätililläsi ja käyttöoikeuksillasi.

Yhdistäminen henkilökohtaisella pääsytunnuksella

FirecREST HPC APIa voidaan käyttää henkilökohtaisilla pääsytunnuksilla, jotka antavat pääsyn samoihin laskentaresursseihin ja projekteihin kuin suora pääsysi komentoriville. Henkilökohtaiset pääsytunnukset ovat hyödyllisiä esimerkiksi 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ä tulee käyttää toteutettaessa koneelta koneelle -integraatiota HPC APIin ilman käyttöliittymää toimivissa ei-interaktiivisissa järjestelmissä.

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

Henkilökohtaisen pääsytunnuksen peruuttaminen

Jos epäillään, että henkilökohtainen pääsytunnus on vaarantunut (esimerkiksi se on vahingossa commitattu julkiseen lähdekoodirepositorioon tai liitetty chattiin tai sähköpostiin), sinun tulee perua mahdollisesti vaarantunut tunnus ja luoda uusi.

Voit tarkastella ja perua aktiiviset tunnuksesi CSC IdP:n federoidulla henkilökohtaisen profiilin sivulla kohdassa Connected organizations -> Firecrest-access-tokens. Kaikissa voimassa olevissa peruttavissa tunnuksissa näkyy punainen Revoke now -painike, kun Firecrest-access-tokens -näkymä on laajennettu.

Yhdistäminen robottitilillä

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

Samoin kuin henkilökohtaisten pääsytunnusten tapauksessa, APIin yhdistäminen robottitilillä edellyttää myös 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 määrityksessä tyypillisesti tarvittavat asetukset:

Setting	Value
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 (tunnustyyppi, scope ja voimassaoloaika).