PyFirecREST

PyFirecREST on Python SDK -kirjasto FirecREST API:n sekä API:n kautta käytettävissä olevien HPC-resurssien käyttöön.

Paketti on saatavilla PyPI:ssä. Sen voi asentaa yksinkertaisella pip-komennolla:

python3 -m pip install pyfirecrest

Katso ohjeita ja API-viite CSCS:n PyFirecREST-dokumentaatiosta. Roihun FirecREST HPC API tukee vain PyFirecREST API v2:ta.

Käyttö henkilökohtaisilla käyttöoikeustokeneilla

PyFirecREST-kirjaston mukana tulee yksi sisäänrakennettu valtuutusluokka, ClientCredentialsAuth, joka soveltuu robottitilien käyttöön.

Jotta kirjastoa voidaan käyttää henkilökohtaisella käyttöoikeustokenilla, firecrest.v2.Firecrest-asiakkaalle täytyy luoda erillinen Authorization-olio. Tässä esimerkissä luomme "läpivienti"-valtuutusluokan, joka lukee tokenin FIRECREST_TOKEN-ympäristömuuttujasta, varmistaa ettei se ole vanhentunut, ja välittää sen sellaisenaan firecrest.v2.Firecrest-asiakkaalle:

import os
import time
import jwt

class TokenAuth:
  def __init__(self):
    pass

  # Use PyJWT to decode the token and verify expiration time.
  # Return False if decoding fails (input is not valid JWT) or if the token has expired
  def _is_token_valid(self, token: str) -> bool:
    try:
      payload = jwt.decode(token, options={"verify_signature": False, "verify_exp": False, "verify_aud": False})
      return time.time() <= payload["exp"]
    except Exception:
      return False

  # A PyFirecREST Authorization object is required to have method get_access_token(),
  # which, when called, will return a valid JWT access token.
  def get_access_token(self):
    token = os.getenv('FIRECREST_TOKEN', None)
    if not token:
      raise RuntimeError("Environment variable FIRECREST_TOKEN is not defined.")
    if not self._is_token_valid(token):
      raise RuntimeError("Token is invalid or has expired.")
    return token

import firecrest as fc
firecrest = fc.v2.Firecrest(firecrest_url="https://api.roihu.csc.fi/v1", authorization=TokenAuth())

# Example: Call the userinfo endpoint on Roihu CPU subsystem to verify FirecREST API connection
try:
    userinfo = firecrest.userinfo(system_name="cpu")
    print(f"Userinfo endpoint returned:\n{userinfo}")
except fc.FirecrestException as e:
    print(f"FirecREST error: {e}")
except Exception as e:
    print(f"System error: {e}")

Käyttö robottitilien kanssa

Voit käyttää sisäänrakennettua ClientCredentialsAuth-luokkaa robottitilin kanssa määrityksillä, jotka on kuvattu kohdassa yhdistäminen Roihun FirecREST API:in, esimerkiksi:

import firecrest as fc
authorization = fc.ClientCredentialsAuth(
  client_id="my_robot_username",
  client_secret="my_robot_password",
  token_uri="https://user-auth.csc.fi/idp/profile/oidc/token"
)
firecrest = fc.v2.Firecrest(firecrest_url="https://api.roihu.csc.fi/v1", authorization=authorization)

Katso kaikki sisäänrakennetun ClientCredentialsAuth-luokan määritysvaihtoehdot PyFirecREST Authorization -viitteestä.

FirecREST CLI

PyFirecRESTin mukana tulee myös kätevä komentorivikäyttöliittymätyökalu firecrest FirecREST APIen käyttöön. Se tukee OIDC client credentials -pohjaista tunnistautumista, jota voidaan käyttää robottitilien kanssa, sekä versiosta v3.8.0 alkaen myös käyttöoikeustokenin hakemista tai asettamista mielivaltaisella shell-komennolla.

CLI:n käyttö henkilökohtaisella käyttöoikeustokenilla

Voimme käyttää firecrest-CLI:n --token-command-valintaa (env FIRECREST_TOKEN_COMMAND) välittääksemme henkilökohtaisen käyttöoikeustokenin työkalulle:

# Copied and pasted access token from MyCSC
access_token="<JWT>"

# Set up URL and token command using environment variables.
export FIRECREST_URL=https://api.roihu.csc.fi/v1
export FIRECREST_TOKEN_COMMAND="echo ${access_token}"

# Example: query the userinfo endpoint on Roihu-CPU
firecrest id -s cpu