Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # API REST Slurm sur PCS AWS AWS PCS fournit un support géré pour l'API REST native de Slurm via `slurmrestd` une interface HTTP pour l'interaction programmatique avec les clusters. Vous pouvez soumettre des tâches, surveiller l'état du cluster et gérer les ressources par le biais de requêtes HTTP standard sans avoir besoin d'un accès shell direct à votre cluster. ## Cas d’utilisation courants L'API REST de Slurm prend en charge différents scénarios d'intégration : + **Intégration d'applications Web** : créez des interfaces personnalisées et des applications Web qui soumettent et gèrent directement les tâches. + **Intégration à Jupyter Notebook** : permet aux chercheurs de soumettre des tâches à partir d'environnements de blocs-notes sans quitter leur flux de travail de développement. + **Intégration de solutions partenaires** : connectez des outils HPC et des gestionnaires de flux de travail tiers à vos clusters AWS PCS. + **Gestion programmatique des clusters** : automatisez les flux de travail de soumission des tâches, de surveillance et de gestion des ressources. + **Flux de travail informatiques pour la recherche** : Supportez les environnements de recherche universitaires et d'entreprise qui nécessitent une gestion des tâches basée sur des API. ## Exigences et limitations Avant d'utiliser l'API REST de Slurm, consultez les informations suivantes : + Votre cluster doit utiliser la version 25.05 ou supérieure de Slurm. + Le point de terminaison de l'API ne sera accessible que via une adresse IP privée au sein du VPC de votre cluster. + Le groupe de sécurité de votre cluster doit autoriser le trafic HTTP sur le port 6820. + L'authentification nécessite des jetons JWT avec des revendications d'identité utilisateur spécifiques. Les limites actuelles incluent : + Les jetons générés par ne `scontrol token` sont pas pris en charge. + `X-SLURM-USER-NAME`l'usurpation d'identité d'en-tête n'est pas disponible. + Certaines fonctionnalités nécessitent l'activation de la comptabilité Slurm. + Non compatible avec le mécanisme du plugin de filtre Slurm CLI. + Les connexions au point de terminaison de l'API REST ne sont pas chiffrées avec TLS. **Topics** + [Cas d’utilisation courants](#slurm-rest-api-use-cases) + [Exigences et limitations](#slurm-rest-api-requirements) + [Activation de l'API REST Slurm sur PCS AWS](slurm-rest-api-enable.md) + [Authentification avec l'API REST de Slurm sur PCS AWS](slurm-rest-api-authenticate.md) + [Utilisation de l'API REST de Slurm pour la gestion des tâches sur PCS AWS](slurm-rest-api-use.md) + [Questions fréquemment posées sur l'API REST de Slurm sur PCS AWS](slurm-rest-api-faq.md) # Activation de l'API REST Slurm sur PCS AWS Activez l'API REST de Slurm pour accéder à l'interface HTTP de votre cluster pour la gestion et la surveillance programmatiques des tâches. Vous pouvez activer cette fonctionnalité lors de la création du cluster ou mettre à jour un cluster existant qui répond aux exigences. ## Conditions préalables Avant d'activer l'API REST de Slurm, assurez-vous d'avoir : + **Version du cluster** : Slurm version 25.05 ou supérieure. + **Groupe de sécurité** : règles autorisant le trafic HTTP sur le port 6820 à partir des sources souhaitées. ## Procédure **Pour activer l'API REST de Slurm sur un nouveau cluster** ------ #### [ AWS Management Console ] 1. Ouvrez la console AWS PCS à l'adresse [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Choisissez **Créer un cluster**. 1. Sous **Détails du cluster**, choisissez Slurm version 25.05 ou supérieure. 1. Configurez les autres paramètres du cluster selon vos besoins. 1. **Dans la section **Configuration du planificateur**, définissez l'**API REST** sur Activé.** 1. Configurez le groupe de sécurité de votre cluster pour autoriser le trafic HTTP sur le port 6820 à partir des sources souhaitées. 1. Terminez le processus de création du cluster. ------ #### [ AWS CLI ] 1. Ajoutez une configuration Slurm REST lors de la création de votre 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. Configurez le groupe de sécurité de votre cluster pour autoriser le trafic HTTP sur le port 6820 à partir des sources souhaitées. ------ **Pour activer l'API REST de Slurm sur un cluster existant** ------ #### [ AWS Management Console ] 1. Ouvrez la console AWS PCS à l'adresse [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Choisissez votre cluster dans la liste. 1. Vérifiez que votre cluster utilise la version 25.05 ou supérieure de Slurm dans les détails du cluster. 1. Choisissez **Modifier le cluster**. 1. **Dans la section **Configuration du planificateur**, définissez l'**API REST** sur Activé.** 1. Choisissez **Mettre à jour le cluster** pour appliquer les modifications. 1. Configurez le groupe de sécurité de votre cluster pour autoriser le trafic HTTP sur le port 6820 à partir des sources souhaitées. ------ #### [ AWS CLI ] 1. Mettez à jour votre cluster avec une configuration Slurm REST, comme dans cet exemple. ``` aws pcs update-cluster --cluster-identifier my-cluster \ --slurm-configuration 'slurmRest={mode=STANDARD}' ``` 1. Configurez le groupe de sécurité de votre cluster pour autoriser le trafic HTTP sur le port 6820 à partir des sources souhaitées. ------ ## Que se passe-t-il après l'activation Lorsque vous activez l'API REST, AWS PCS effectue automatiquement les opérations suivantes : + Génère une clé de signature JWT et la stocke dans AWS Secrets Manager. + Expose le point de terminaison de l'API au `https://:6820` sein de votre VPC. + Met à jour la configuration de votre cluster pour afficher les détails du point de terminaison de l'API REST. Vous pouvez désormais vous authentifier et utiliser l'API REST pour la gestion des tâches et les opérations de cluster. # Authentification avec l'API REST de Slurm sur PCS AWS L'API REST de Slurm dans AWS PCS utilise l'authentification JSON Web Token (JWT) pour garantir un accès sécurisé aux ressources de votre cluster. AWS PCS fournit une clé de signature gérée stockée dans AWS Secrets Manager, que vous utilisez pour générer des jetons JWT contenant des revendications d'identité utilisateur spécifiques. ## Conditions préalables Avant de vous authentifier avec l'API REST de Slurm, assurez-vous d'avoir : + **Configuration du cluster** : cluster AWS PCS avec Slurm 25.05\$1 et API REST activée. + **Autorisations AWS** : accès à AWS Secrets Manager pour la clé de signature JWT. + **Informations utilisateur** : nom d'utilisateur, ID utilisateur POSIX et un ou plusieurs groupes POSIX IDs pour votre compte de cluster. + **Accès réseau** : connectivité au sein du VPC de votre cluster avec le groupe de sécurité autorisant le port 6820. ## Procédure **Pour récupérer l'adresse du point de terminaison de l'API REST Slurm** ------ #### [ AWS Management Console ] 1. Ouvrez la console AWS PCS à l'adresse [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Choisissez votre cluster dans la liste. 1. Dans les détails de configuration du cluster, recherchez la section **Endpoints**. 1. Notez l'adresse IP privée et le port de l'**API REST de Slurm (slurmrestd**). 1. Vous pouvez effectuer des appels d'API en envoyant des requêtes HTTP correctement formatées à cette adresse. ------ #### [ AWS CLI ] 1. Demandez l'état de votre cluster avec`aws pcs get-cluster`. Recherchez le `SLURMRESTD` point final dans le `endpoints` champ de la réponse. Voici un exemple : ``` "endpoints": [ { "type": "SLURMCTLD", "privateIpAddress": "192.0.2.1", "port": "6817" }, { "type": "SLURMRESTD", "privateIpAddress": "192.0.2.1", "port": "6820" } ] ``` 1. Vous pouvez effectuer des appels d'API en envoyant des requêtes HTTP correctement formatées à `http://:/` ------ **Pour récupérer la clé de signature JWT** 1. Ouvrez la console AWS PCS à l'adresse [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Choisissez votre cluster dans la liste. 1. Dans les détails de configuration du cluster, recherchez la section **Authentification du planificateur**. 1. Notez l'ARN et la version de la **clé JSON Web Token (JWT)**. 1. Utilisez le AWS CLI pour récupérer la clé de signature depuis Secrets Manager : ``` aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version ``` **Pour générer un jeton JWT** 1. Créez un JWT avec les revendications requises suivantes : + `exp`— Délai d'expiration en secondes depuis 1970 pour le JWT + `iat`— Heure actuelle en secondes depuis 1970 + `sun`— Le nom d'utilisateur pour l'authentification + `uid`— L'ID utilisateur POSIX + `gid`— L'identifiant du groupe POSIX + `id`— Propriétés d'identité POSIX supplémentaires + `gecos`— Champ de commentaire utilisateur, souvent utilisé pour stocker un nom lisible par l'homme + `dir`— Répertoire personnel de l'utilisateur + `shell`— Shell par défaut de l'utilisateur + `gids`— Liste des groupes POSIX supplémentaires auxquels IDs appartient l'utilisateur 1. Signez le JWT à l'aide de la clé de signature récupérée dans Secrets Manager. 1. Définissez une date d'expiration appropriée pour le jeton. **Note** Comme alternative à la `sun` réclamation, vous pouvez fournir l'un des documents suivants : `username` Un nom de champ personnalisé que vous définissez via `userclaimfield` le `AuthAltParameters Slurm custom settings` Un `name` champ dans la `id` réclamation **Pour authentifier les demandes d'API** 1. Incluez le jeton JWT dans vos requêtes HTTP en utilisant l'une des méthodes suivantes : + **jeton porteur** — Ajouter un en-tête `Authorization: Bearer ` + En-tête **Slurm — Ajouter un en-tête** `X-SLURM-USER-TOKEN: ` 1. Envoyez des requêtes HTTP au point de terminaison de l'API REST : Voici un exemple d'accès à l'`/ping`API à l'aide de curl et de l'`Authorized: Bearer`en-tête. ``` curl -X GET -H "Authorization: Bearer " \ http://:6820/slurm/v0.0.43/ping ``` ## Exemple de génération JWT Récupérez la clé de signature JWT du cluster AWS PCS et stockez-la dans un fichier local. Remplacez les valeurs pour **aws-region****,** secret-arn **et secret** version par des valeurs adaptées à votre 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 ``` Cet exemple Python illustre comment utiliser la clé de signature pour générer un jeton 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) ``` Le script imprimera un JWT à l'écran. ``` abcdefgtjwttoken... ``` # Utilisation de l'API REST de Slurm pour la gestion des tâches sur PCS AWS ## Présentation de l'API REST de Slurm L'API REST de Slurm fournit un accès programmatique aux fonctions de gestion des clusters par le biais de requêtes HTTP. La compréhension de ces caractéristiques clés vous aidera à utiliser efficacement l'API avec AWS PCS : + **Protocole d'accès** : L'API utilise le protocole HTTP (et non HTTPS) pour les communications au sein du réseau privé de votre cluster. + **Détails de connexion** : accédez à l'API à l'aide de l'adresse IP privée de votre cluster et du `slurmrestd` port (généralement 6820). Le format d'URL de base complet est`http://:6820`. + **Versionnage de l'API** : La version de l'API correspond à votre installation de Slurm. **Pour Slurm 25.05, utilisez la version v0.0.43.** Le numéro de version change à chaque sortie de Slurm. Vous trouverez les versions d'API actuellement prises en charge dans les notes de [mise à jour de Slurm](https://slurm.schedmd.com/release_notes.html). + **Structure d'URL** : La structure d'URL de l'API REST de Slurm est. `http://://` Vous trouverez des informations détaillées sur l'utilisation des points de terminaison de l'API REST dans la documentation de [Slurm](https://slurm.schedmd.com/rest_api.html). ## Conditions préalables Avant d'utiliser l'API REST de Slurm, assurez-vous d'avoir : + **Configuration du cluster** : cluster AWS PCS avec Slurm 25.05\$1 et API REST activée. + **Authentification** : jeton JWT valide avec des demandes d'identité utilisateur appropriées. + **Accès réseau** : connectivité au sein du VPC de votre cluster avec un groupe de sécurité autorisant le port 6820. ## Procédure **Pour soumettre une tâche à l'aide de l'API REST** 1. Créez une demande de soumission de travail avec les paramètres requis : ``` { "job": { "name": "my-job", "partition": "compute", "nodes": 1, "tasks": 1, "script": "#!/bin/bash\necho 'Hello from Slurm REST API'" } } ``` 1. Soumettez la tâche à l'aide d'une requête HTTP POST : ``` curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' \ https://:6820/slurm/v0.0.43/job/submit ``` 1. Notez l'ID de tâche renvoyé dans la réponse à des fins de surveillance. **Pour surveiller l'état du travail** 1. Obtenez des informations sur un poste spécifique : ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` 1. Répertoriez toutes les tâches pour l'utilisateur authentifié : ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/jobs ``` **Pour annuler une tâche** + Envoyez une demande DELETE pour annuler une tâche spécifique : ``` curl -X DELETE -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` # Questions fréquemment posées sur l'API REST de Slurm sur PCS AWS Cette section répond aux questions fréquemment posées sur l'API REST de Slurm dans AWS PCS. **Qu'est-ce que l'API REST de Slurm ?** L'API REST de Slurm est une interface HTTP qui vous permet d'interagir avec le gestionnaire de charge de travail Slurm par programmation. Vous pouvez utiliser des méthodes HTTP standard telles que GET, POST et DELETE pour soumettre des tâches, surveiller l'état du cluster et gérer les ressources sans avoir besoin d'un accès par ligne de commande au cluster. **Puis-je utiliser des jetons générés par `scontrol token` ?** Non, la `scontrol token` sortie standard n'est pas compatible avec le AWS PCS. L'API REST PCS Slurm nécessite des jetons JWT enrichis contenant des revendications d'identité spécifiques, notamment le nom d'utilisateur (`sun`), l'ID utilisateur POSIX (`uid`) et le groupe (). IDs `gids` Les jetons Slurm standard ne présentent pas ces réclamations requises et seront rejetés par l'API. **Puis-je accéder à l'API depuis l'extérieur de mon VPC ?** Non, le point de terminaison de l'API REST n'est accessible que depuis votre VPC à l'aide de l'adresse IP privée du contrôleur Slurm. Pour activer l'accès externe, implémentez AWS des services tels que Application Load Balancer avec VPC Link, API Gateway, ou établissez un peering VPC ou des connexions VPN pour une connectivité sécurisée. **Pourquoi l'API utilise-t-elle le protocole HTTP au lieu du protocole HTTPS ?** L'API REST de Slurm est destinée à être un point de terminaison interne au sein du réseau privé de votre cluster. Pour les déploiements de production nécessitant un chiffrement, vous pouvez implémenter la SSL/TLS terminaison à un niveau supérieur dans votre architecture, par exemple via une passerelle API, un équilibreur de charge ou un proxy inverse. **Comment contrôler l'accès à l'API REST ?** Configurez les règles du groupe de sécurité de votre cluster pour restreindre l'accès au port 6820 sur le contrôleur Slurm. Définissez des règles entrantes pour autoriser les connexions uniquement à partir de plages d'adresses IP fiables ou de sources spécifiques au sein de votre VPC, bloquant ainsi tout accès non autorisé au point de terminaison de l'API. **Comment puis-je faire pivoter la clé de signature JWT ?** Mettez votre cluster en mode maintenance sans aucune instance active, puis lancez la rotation des clés via AWS Secrets Manager. Une fois la rotation terminée, réactivez les files d'attente. Tous les jetons JWT existants deviendront invalides et devront être régénérés à l'aide de la nouvelle clé de signature de Secrets Manager. **Dois-je activer la comptabilité Slurm pour utiliser l'API REST ?** Non, la comptabilité Slurm n'est pas requise pour les opérations de base de l'API REST telles que la soumission et la surveillance des tâches. Cependant, l'ensemble du point de `/slurmdb` terminaison nécessite que la comptabilité soit active. **Quels outils tiers fonctionnent avec l'API REST du AWS PCS ?** De nombreux clients d'API REST Slurm existants devraient fonctionner avec des AWS PCS, notamment Slurm Exporter pour Prometheus, et des applications personnalisées qui suivent le format standard de l'API REST de Slurm. SlurmWeb Cependant, les outils qui reposent sur l'authentification devront être modifiés `scontrol token` pour fonctionner avec les exigences du AWS PCS JWT. **L'utilisation de l'API REST entraîne-t-elle des coûts supplémentaires ?** Non, l'activation ou l'utilisation de la fonctionnalité API REST de Slurm sont gratuites. Vous ne payez que pour les ressources du cluster sous-jacent comme d'habitude. **Comment puis-je résoudre les problèmes liés à l'API REST ?** + **Problèmes de connectivité réseau** Si vous ne pouvez pas atteindre le point de terminaison de l'API, des délais de connexion ou des erreurs de « connexion refusée » s'afficheront lorsque vous envoyez des requêtes HTTP au contrôleur de cluster. **Que faire** : Vérifiez que votre client se trouve dans le même VPC ou dispose d'un routage réseau approprié, et vérifiez que votre groupe de sécurité autorise le trafic HTTP sur le port 6820 à partir de votre adresse IP source ou de votre sous-réseau. + **Problèmes d'authentification REST avec Slurm** Si votre jeton JWT n'est pas valide, a expiré ou n'est pas correctement signé, les demandes d'API renverront « Erreur d'authentification du protocole » dans le champ des erreurs de la réponse. Exemple de message d'erreur : ``` { "errors": [ { "description": "Batch job submission failed", "error_number": 1007, "error": "Protocol authentication error", "source": "slurm_submit_batch_job()" } ] } ``` **Que faire** : Vérifiez que votre jeton JWT est correctement formaté, qu'il n'a pas expiré et qu'il est signé avec la bonne clé dans Secrets Manager. Vérifiez que le jeton est correctement formé, qu'il inclut les revendications requises et que vous utilisez le format d'en-tête d'authentification correct. + **Le Job ne s'exécute pas après sa soumission** Si votre jeton JWT est valide mais contient une structure ou un contenu interne incorrect, les tâches sont peut-être entrées dans un état suspendu (`PD`) avec un code de raison. `JobAdminHead` `scontrol show job `À utiliser pour inspecter le travail, vous verrez`JobState=PENDING, Reason=JobHeldAdmin`, et`SystemComment=slurm_cred_create failure, holding job`. **Que faire** : La cause première peut être des valeurs erronées dans JWT. Vérifiez que le jeton est correctement structuré et inclut les allégations requises conformément à la documentation du PCS. + **Problèmes d'autorisation liés au répertoire de travail** Si l'identité utilisateur spécifiée dans votre JWT ne dispose pas d'autorisations d'écriture dans le répertoire de travail de la tâche, celle-ci échouera avec des erreurs d'autorisation, comme si vous `sbatch --chdir` utilisiez un répertoire inaccessible. **Que faire** : assurez-vous que l'utilisateur spécifié dans votre jeton JWT dispose des autorisations appropriées pour le répertoire de travail de la tâche.