Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # API REST Slurm in PCS AWS AWS PCS fornisce supporto gestito per l'API REST nativa di Slurm tramite un'interfaccia HTTP per l'`slurmrestd`interazione programmatica dei cluster. È possibile inviare lavori, monitorare lo stato del cluster e gestire le risorse tramite richieste HTTP standard senza richiedere l'accesso diretto dalla shell al cluster. ## Casi di utilizzo comune L'API REST di Slurm supporta vari scenari di integrazione: + **Integrazione di applicazioni Web**: crea frontend e applicazioni Web personalizzati che inviano e gestiscono direttamente i lavori. + **Jupyter Notebook Integration**: consente ai ricercatori di inviare lavori da ambienti notebook senza abbandonare il flusso di lavoro di sviluppo. + **Integrazione delle soluzioni partner**: Collega strumenti HPC e gestori di flussi di lavoro di terze parti ai tuoi cluster AWS PCS. + **Gestione programmatica dei cluster**: automatizza i flussi di lavoro per l'invio dei lavori, il monitoraggio e la gestione delle risorse. + **Flussi di lavoro di Research Computing**: Supporta ambienti di ricerca accademici e aziendali che richiedono una gestione del lavoro basata sulle API. ## Requisiti e limitazioni Prima di utilizzare l'API REST di Slurm, esamina questi dettagli: + Il tuo cluster deve utilizzare la versione Slurm 25.05 o successiva. + L'endpoint dell'API sarà accessibile solo tramite un indirizzo IP privato all'interno del VPC del cluster. + Il gruppo di sicurezza del cluster deve consentire il traffico HTTP sulla porta 6820. + L'autenticazione richiede token JWT con dichiarazioni di identità utente specifiche. Le limitazioni attuali includono: + I token generati da non `scontrol token` sono supportati. + `X-SLURM-USER-NAME`la rappresentazione dell'intestazione non è disponibile. + Alcune funzionalità richiedono l'abilitazione della contabilità Slurm. + Non compatibile con il meccanismo del plugin di filtro Slurm CLI. + Le connessioni all'endpoint dell'API REST non sono crittografate con TLS. **Topics** + [Casi di utilizzo comune](#slurm-rest-api-use-cases) + [Requisiti e limitazioni](#slurm-rest-api-requirements) + [Abilitazione dell'API REST Slurm nei PCS AWS](slurm-rest-api-enable.md) + [Autenticazione con l'API REST di Slurm in PCS AWS](slurm-rest-api-authenticate.md) + [Utilizzo dell'API REST Slurm per la gestione dei lavori in PCS AWS](slurm-rest-api-use.md) + [Domande frequenti sull'API REST di Slurm in PCS AWS](slurm-rest-api-faq.md) # Abilitazione dell'API REST Slurm nei PCS AWS Abilita l'API REST Slurm per accedere all'interfaccia HTTP del cluster per la gestione e il monitoraggio programmatici dei lavori. È possibile abilitare questa funzionalità durante la creazione del cluster o aggiornare un cluster esistente che soddisfi i requisiti. ## Prerequisiti Prima di abilitare l'API REST di Slurm, assicurati di avere: + **Versione cluster**: Slurm versione 25.05 o successiva. + **Gruppo di sicurezza**: regole che consentono il traffico HTTP sulla porta 6820 dalle sorgenti desiderate. ## Procedura **Per abilitare l'API REST di Slurm su un nuovo cluster** ------ #### [ Console di gestione AWS ] 1. Apri la console AWS PCS all'indirizzo. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 1. Scegli **Crea cluster**. 1. In **Dettagli del cluster**, scegli Slurm versione 25.05 o successiva. 1. Configura le altre impostazioni del cluster secondo necessità. 1. Nella sezione di **configurazione Scheduler**, imposta l'**API REST** su **Enabled**. 1. Configura il gruppo di sicurezza del cluster per consentire il traffico HTTP sulla porta 6820 dalle sorgenti desiderate. 1. Completa il processo di creazione del cluster. ------ #### [ AWS CLI ] 1. Aggiungi una configurazione Slurm REST durante la creazione del cluster. ``` aws pcs create-cluster --region region \ --cluster-name my-cluster \ --scheduler type=SLURM, version=25.05 \ --size SMALL \ --networking subnetIds=subnet-ExampleId1,securityGroupIds=sg-ExampleId1 \ --slurm-configuration slurmRest='{mode=STANDARD}' ``` 1. Configura il gruppo di sicurezza del cluster per consentire il traffico HTTP sulla porta 6820 dalle sorgenti desiderate. ------ **Per abilitare l'API REST di Slurm su un cluster esistente** ------ #### [ Console di gestione AWS ] 1. Apri la console AWS PCS all'indirizzo. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 1. Scegli il tuo cluster dall'elenco. 1. Verifica che il tuo cluster utilizzi Slurm versione 25.05 o successiva nei dettagli del cluster. 1. **Scegli Modifica cluster.** 1. Nella sezione di **configurazione Scheduler**, imposta l'**API REST** su **Enabled**. 1. Scegli **Aggiorna cluster** per applicare le modifiche. 1. Configura il gruppo di sicurezza del cluster per consentire il traffico HTTP sulla porta 6820 dalle sorgenti desiderate. ------ #### [ AWS CLI ] 1. Aggiorna il tuo cluster con una configurazione Slurm REST, come in questo esempio. ``` aws pcs update-cluster --cluster-identifier my-cluster \ --slurm-configuration 'slurmRest={mode=STANDARD}' ``` 1. Configura il gruppo di sicurezza del cluster per consentire il traffico HTTP sulla porta 6820 dalle sorgenti desiderate. ------ ## Cosa succede dopo l'attivazione Quando abiliti l'API REST, AWS PCS automaticamente: + Genera una chiave di firma JWT e la memorizza in AWS Secrets Manager. + Espone l'endpoint dell'API all'`https://:6820`interno del tuo VPC. + Aggiorna la configurazione del cluster per mostrare i dettagli dell'endpoint dell'API REST. Ora puoi autenticare e utilizzare l'API REST per la gestione dei lavori e le operazioni del cluster. # Autenticazione con l'API REST di Slurm in PCS AWS L'API Slurm REST in AWS PCS utilizza l'autenticazione JSON Web Token (JWT) per garantire un accesso sicuro alle risorse del cluster. AWS PCS fornisce una chiave di firma gestita archiviata in AWS Secrets Manager, che viene utilizzata per generare token JWT contenenti dichiarazioni di identità utente specifiche. ## Prerequisiti Prima di autenticarti con l'API REST di Slurm, assicurati di avere: + **Configurazione del cluster**: cluster AWS PCS con Slurm 25.05\$1 e API REST abilitate. + **Autorizzazioni AWS**: accesso a AWS Secrets Manager per la chiave di firma JWT. + **Informazioni utente**: nome utente, ID utente POSIX e uno o più gruppi POSIX IDs per l'account del cluster. + **Accesso alla rete**: connettività all'interno del VPC del cluster con gruppo di sicurezza che consente la porta 6820. ## Procedura **Per recuperare l'indirizzo dell'endpoint dell'API REST di Slurm** ------ #### [ Console di gestione AWS ] 1. Apri la console PCS all'indirizzo. AWS [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 1. Scegli il tuo cluster dall'elenco. 1. Nei dettagli della configurazione del cluster, individua la sezione **Endpoints**. 1. Annota l'indirizzo IP e la porta privati per l'**API REST di Slurm (slurmrestd)**. 1. È possibile effettuare chiamate API inviando richieste HTTP formattate correttamente a questo indirizzo. ------ #### [ AWS CLI ] 1. Interroga lo stato del cluster con`aws pcs get-cluster`. Cerca l'`SLURMRESTD`endpoint nel `endpoints` campo della risposta. Ecco un esempio: ``` "endpoints": [ { "type": "SLURMCTLD", "privateIpAddress": "192.0.2.1", "port": "6817" }, { "type": "SLURMRESTD", "privateIpAddress": "192.0.2.1", "port": "6820" } ] ``` 1. Puoi effettuare chiamate API inviando richieste HTTP formattate correttamente a `http://:/` ------ **Per recuperare la chiave di firma JWT** 1. Apri la console AWS PCS all'indirizzo. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 1. Scegli il tuo cluster dall'elenco. 1. Nei dettagli di configurazione del cluster, individua la sezione **Scheduler Authentication**. 1. Nota l'**ARN e la versione della chiave JSON Web Token (JWT)**. 1. Usa AWS CLI per recuperare la chiave di firma da Secrets Manager: ``` aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version ``` **Per generare un token JWT** 1. Crea un JWT con le seguenti attestazioni obbligatorie: + `exp`— Tempo di scadenza in secondi dal 1970 per il JWT + `iat`— Ora attuale in secondi dal 1970 + `sun`— Il nome utente per l'autenticazione + `uid`— L'ID utente POSIX + `gid`— L'ID del gruppo POSIX + `id`— Proprietà di identità POSIX aggiuntive + `gecos`— Campo di commento dell'utente, spesso utilizzato per memorizzare un nome leggibile dall'uomo + `dir`— La home directory dell'utente + `shell`— shell predefinita dell'utente + `gids`— Elenco dei gruppi POSIX aggiuntivi in cui si trova IDs l'utente 1. Firma il JWT utilizzando la chiave di firma recuperata da Secrets Manager. 1. Imposta un orario di scadenza appropriato per il token. **Nota** In alternativa al `sun` reclamo, puoi fornire una delle seguenti informazioni: `username` Un nome di campo personalizzato che definisci tramite `userclaimfield` in `AuthAltParameters Slurm custom settings` Un `name` campo all'interno del `id` claim **Per autenticare le richieste API** 1. Includi il token JWT nelle tue richieste HTTP utilizzando uno di questi metodi: + **Token Bearer**: aggiungi un'intestazione `Authorization: Bearer ` + **Slurm** header: aggiunge un'intestazione `X-SLURM-USER-TOKEN: ` 1. Effettua richieste HTTP all'endpoint dell'API REST: Ecco un esempio di accesso all'`/ping`API utilizzando curl e l'`Authorized: Bearer`header. ``` curl -X GET -H "Authorization: Bearer " \ http://:6820/slurm/v0.0.43/ping ``` ## Esempio di generazione JWT Recupera la chiave di firma JWT del cluster AWS PCS e memorizzala come file locale. Sostituisci i valori per **aws-region****,** secret-arn **e secret** version con valori appropriati per il tuo cluster. ``` #!/bin/bash SECRET_KEY=$(aws secretsmanager get-secret-value \ --region aws-region \ --secret-id secret-arn \ --version-stage secret-version \ --query 'SecretString' \ --output text) echo "$SECRET_KEY" | base64 --decode > jwt.key ``` Questo esempio in Python illustra come utilizzare la chiave di firma per generare un token JWT: ``` #!/usr/bin/env python3 import sys import os import pprint import json import time from datetime import datetime, timedelta, timezone from jwt import JWT from jwt.jwa import HS256 from jwt.jwk import jwk_from_dict from jwt.utils import b64decode,b64encode if len(sys.argv) != 3: sys.exit("Usage: gen_jwt.py [jwt_key_file] [expiration_time_seconds]") SIGNING_KEY = sys.argv[1] EXPIRATION_TIME = int(sys.argv[2]) with open(SIGNING_KEY, "rb") as f: priv_key = f.read() signing_key = jwk_from_dict({ 'kty': 'oct', 'k': b64encode(priv_key) }) message = { "exp": int(time.time() + EXPIRATION_TIME), "iat": int(time.time()), "sun": "ec2-user", "uid": 1000, "gid": 1000, "id": { "gecos": "EC2 User", "dir": "/home/ec2-user", "gids": [1000], "shell": "/bin/bash" } } a = JWT() compact_jws = a.encode(message, signing_key, alg='HS256') print(compact_jws) ``` Lo script stamperà un JWT sullo schermo. ``` abcdefgtjwttoken... ``` # Utilizzo dell'API REST Slurm per la gestione dei lavori in PCS AWS ## Panoramica dell'API REST Slurm L'API REST di Slurm fornisce l'accesso programmatico alle funzioni di gestione dei cluster tramite richieste HTTP. La comprensione di queste caratteristiche chiave ti aiuterà a utilizzare efficacemente l'API con PCS: AWS + **Protocollo di accesso**: l'API utilizza HTTP (non HTTPS) per la comunicazione all'interno della rete privata del cluster. + **Dettagli di connessione**: accedi all'API utilizzando l'indirizzo IP privato del cluster e la `slurmrestd` porta (in genere 6820). Il formato URL di base completo è`http://:6820`. + Controllo **delle versioni dell'API**: La versione dell'API corrisponde all'installazione di Slurm. **Per Slurm 25.05, usa la versione v0.0.43.** Il numero di versione cambia con ogni versione di Slurm. Puoi trovare le versioni delle API attualmente supportate nelle note di rilascio di [Slurm](https://slurm.schedmd.com/release_notes.html). + **Struttura dell'URL**: La struttura dell'URL per l'API REST di Slurm è. `http://://` [Informazioni dettagliate sull'utilizzo degli endpoint dell'API REST sono disponibili nella documentazione di Slurm.](https://slurm.schedmd.com/rest_api.html) ## Prerequisiti Prima di utilizzare l'API REST di Slurm, assicurati di avere: + **Configurazione del cluster**: cluster AWS PCS con Slurm 25.05\$1 e API REST abilitate. + **Autenticazione**: token JWT valido con affermazioni di identità utente corrette. + **Accesso alla rete**: connettività all'interno del VPC del cluster con un gruppo di sicurezza che consente la porta 6820. ## Procedura **Per inviare un lavoro utilizzando l'API REST** 1. Crea una richiesta di invio di lavoro con i parametri richiesti: ``` { "job": { "name": "my-job", "partition": "compute", "nodes": 1, "tasks": 1, "script": "#!/bin/bash\necho 'Hello from Slurm REST API'" } } ``` 1. Invia il lavoro utilizzando una richiesta HTTP POST: ``` curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' \ https://:6820/slurm/v0.0.43/job/submit ``` 1. Annota l'ID del lavoro restituito nella risposta a scopo di monitoraggio. **Per monitorare lo stato del lavoro** 1. Ottieni informazioni su un lavoro specifico: ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` 1. Elenca tutti i lavori per l'utente autenticato: ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/jobs ``` **Come annullare un processo** + Invia una richiesta DELETE per annullare un lavoro specifico: ``` curl -X DELETE -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` # Domande frequenti sull'API REST di Slurm in PCS AWS Questa sezione risponde alle domande frequenti sull'API REST di Slurm in AWS PCS. **Cos'è l'API REST di Slurm?** L'API Slurm REST è un'interfaccia HTTP che consente di interagire con il gestore del carico di lavoro Slurm a livello di codice. È possibile utilizzare metodi HTTP standard come GET, POST e DELETE per inviare lavori, monitorare lo stato del cluster e gestire le risorse senza richiedere l'accesso da riga di comando al cluster. **Posso usare i token generati da? `scontrol token`** No, lo standard `scontrol token` output non è compatibile con AWS PCS. L'API REST PCS Slurm richiede token JWT arricchiti contenenti affermazioni di identità specifiche che includono username (`sun`), ID utente POSIX () e group (`uid`). IDs `gids` I token Slurm standard non dispongono di queste affermazioni obbligatorie e verranno rifiutati dall'API. **Posso accedere all'API dall'esterno del mio VPC?** No, l'endpoint dell'API REST è accessibile solo dall'interno del tuo VPC utilizzando l'indirizzo IP privato del controller Slurm. Per abilitare l'accesso esterno, implementa AWS servizi come Application Load Balancer with VPC Link, API Gateway o stabilisci connessioni VPC peering o VPN per una connettività sicura. **Perché l'API utilizza HTTP anziché HTTPS?** L'API REST di Slurm è pensata per essere un endpoint interno all'interno della rete privata del cluster. Per le implementazioni di produzione che richiedono la crittografia, è possibile implementare la SSL/TLS terminazione a un livello superiore nell'architettura, ad esempio tramite un gateway API, un sistema di bilanciamento del carico o un proxy inverso. **Come posso controllare l'accesso all'API REST?** Configura le regole del gruppo di sicurezza del cluster per limitare l'accesso alla porta 6820 sul controller Slurm. Imposta regole in entrata per consentire le connessioni solo da intervalli IP affidabili o fonti specifiche all'interno del tuo VPC, bloccando l'accesso non autorizzato all'endpoint API. **Come faccio a ruotare la chiave di firma JWT?** Metti il cluster in modalità di manutenzione senza istanze attive, quindi avvia la rotazione delle chiavi tramite AWS Secrets Manager. Al termine della rotazione, riattiva le code. Tutti i token JWT esistenti non saranno più validi e dovranno essere rigenerati utilizzando la nuova chiave di firma di Secrets Manager. **Ho bisogno che la contabilità Slurm sia abilitata per utilizzare l'API REST?** No, la contabilità Slurm non è richiesta per le operazioni di base dell'API REST come l'invio e il monitoraggio dei lavori. Tuttavia, l'intero `/slurmdb` endpoint richiede che la contabilità sia attiva. **Quali strumenti di terze parti funzionano con l'API REST AWS PCS?** Molti client Slurm REST API esistenti dovrebbero funzionare con AWS PCS, tra cui Slurm Exporter for Prometheus, e applicazioni personalizzate che seguono il formato API REST standard di Slurm. SlurmWeb Tuttavia, gli strumenti che si basano sull'autenticazione dovranno essere modificati `scontrol token` per funzionare con i requisiti PCS JWT. AWS **Sono previsti costi aggiuntivi per l'utilizzo dell'API REST?** No, non ci sono costi aggiuntivi per l'attivazione o l'utilizzo della funzionalità API REST di Slurm. Come di consueto, paghi solo per le risorse del cluster sottostanti. **Come posso risolvere i problemi relativi all'API REST?** + **Problemi di connettività di rete** Se non riesci a raggiungere l'endpoint dell'API, vedrai dei timeout di connessione o degli errori di «connessione rifiutata» quando effettui richieste HTTP al controller del cluster. **Cosa fare**: verifica che il client si trovi nello stesso VPC o disponga del routing di rete corretto e conferma che il gruppo di sicurezza consenta il traffico HTTP sulla porta 6820 dall'IP o dalla sottorete di origine. + **Problemi di autenticazione Slurm REST** Se il token JWT non è valido, è scaduto o firmato in modo errato, le richieste API restituiranno «Errore di autenticazione del protocollo» nel campo degli errori della risposta. Esempio di messaggio di errore: ``` { "errors": [ { "description": "Batch job submission failed", "error_number": 1007, "error": "Protocol authentication error", "source": "slurm_submit_batch_job()" } ] } ``` **Cosa fare**: verifica che il token JWT sia formattato correttamente, non scaduto e firmato con la chiave corretta di Secrets Manager. Verifica che il token sia formato correttamente e includa le attestazioni richieste e che stia utilizzando il formato di intestazione di autenticazione corretto. + **Job non riuscito a eseguire dopo l'invio** Se il token JWT è valido ma contiene una struttura o un contenuto interni errati, è possibile che i job abbiano inserito uno stato paused (`PD`) con codice motivo. `JobAdminHead` `scontrol show job `Usalo per ispezionare il lavoro: vedrai`JobState=PENDING, Reason=JobHeldAdmin`, e. `SystemComment=slurm_cred_create failure, holding job` **Cosa fare**: la causa principale potrebbe essere rappresentata da valori errati in JWT. Verifica che il token sia strutturato correttamente e includa le attestazioni richieste secondo la documentazione PCS. + **Problemi di autorizzazione alla directory di lavoro** Se l'identità utente specificata nel JWT non dispone dei permessi di scrittura nella directory di lavoro del lavoro, il lavoro avrà esito negativo con errori di autorizzazione, simili all'utilizzo `sbatch --chdir` con una directory inaccessibile. **Cosa fare**: assicurati che l'utente specificato nel tuo token JWT disponga delle autorizzazioni appropriate per la directory di lavoro del lavoro.