Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # API REST de Slurm en PCS AWS AWS PCS proporciona soporte gestionado para la API REST nativa de Slurm mediante una interfaz HTTP para la interacción `slurmrestd` programática entre clústeres. Puede enviar trabajos, supervisar el estado del clúster y administrar los recursos mediante solicitudes HTTP estándar sin necesidad de acceder directamente a su clúster desde el shell. ## Casos de uso comunes La API REST de Slurm admite varios escenarios de integración: + **Integración de aplicaciones web**: cree interfaces y aplicaciones web personalizadas que envíen y administren trabajos directamente. + **Integración con Jupyter Notebook**: permite a los investigadores enviar trabajos desde entornos portátiles sin abandonar su flujo de trabajo de desarrollo. + **Integración de soluciones de socios**: conecte herramientas de HPC y administradores de flujo de trabajo de terceros a sus clústeres de AWS PCS. + **Gestión programática de clústeres**: automatice los flujos de trabajo de envío de trabajos, supervisión y gestión de recursos. + **Flujos de trabajo de computación de investigación**: Support entornos de investigación académicos y empresariales que requieren una gestión de trabajos basada en API. ## Requisitos y limitaciones Antes de usar la API REST de Slurm, revise estos detalles: + Su clúster debe usar la versión 25.05 o superior de Slurm. + Solo se podrá acceder al punto final de la API a través de una dirección IP privada dentro de la VPC del clúster. + El grupo de seguridad del clúster debe permitir el tráfico HTTP en el puerto 6820. + La autenticación requiere tokens JWT con declaraciones de identidad de usuario específicas. Las limitaciones actuales incluyen: + No se admiten `scontrol token` los tokens generados por. + `X-SLURM-USER-NAME`la suplantación de encabezados no está disponible. + Algunas funciones requieren que la contabilidad de Slurm esté habilitada. + No es compatible con el mecanismo del complemento de filtro CLI de Slurm. + Las conexiones al punto final de la API REST no se cifran con TLS. **Topics** + [Casos de uso comunes](#slurm-rest-api-use-cases) + [Requisitos y limitaciones](#slurm-rest-api-requirements) + [Habilitación de la API REST de Slurm en PCS AWS](slurm-rest-api-enable.md) + [Autenticación con la API REST de Slurm en PCS AWS](slurm-rest-api-authenticate.md) + [Uso de la API REST de Slurm para la gestión de trabajos en PCS AWS](slurm-rest-api-use.md) + [Preguntas frecuentes sobre la API REST de Slurm en PCS AWS](slurm-rest-api-faq.md) # Habilitación de la API REST de Slurm en PCS AWS Habilite la API REST de Slurm para acceder a la interfaz HTTP de su clúster para gestionar y supervisar los trabajos mediante programación. Puede habilitar esta función durante la creación del clúster o actualizar un clúster existente que cumpla con los requisitos. ## Requisitos previos Antes de habilitar la API REST de Slurm, asegúrate de tener: + **Versión de clúster**: Slurm, versión 25.05 o superior. + **Grupo de seguridad**: reglas que permiten el tráfico HTTP en el puerto 6820 desde las fuentes deseadas. ## Procedimiento **Para habilitar la API REST de Slurm en un clúster nuevo** ------ #### [ Consola de administración de AWS ] 1. Abra la consola AWS PCS en. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 1. Elija **Create cluster**. 1. En **Detalles del clúster**, seleccione Slurm, versión 25.05 o superior. 1. Configure los demás ajustes del clúster según sea necesario. 1. En la sección de **configuración del programador**, establece la **API REST** en **Habilitada**. 1. Configure el grupo de seguridad del clúster para permitir el tráfico HTTP en el puerto 6820 desde las fuentes que desee. 1. Complete el proceso de creación del clúster. ------ #### [ AWS CLI ] 1. Agregue una configuración REST de Slurm al crear el clúster. ``` 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. Configure el grupo de seguridad del clúster para permitir el tráfico HTTP en el puerto 6820 desde las fuentes que desee. ------ **Para habilitar la API REST de Slurm en un clúster existente** ------ #### [ Consola de administración de AWS ] 1. Abra la consola AWS PCS en. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 1. Elija su clúster de la lista. 1. Compruebe que su clúster utilice la versión 25.05 o superior de Slurm en los detalles del clúster. 1. **Seleccione Editar clúster.** 1. En la sección de **configuración del programador**, establece la **API REST** en **Habilitada**. 1. Seleccione **Actualizar clúster** para aplicar los cambios. 1. Configure el grupo de seguridad del clúster para permitir el tráfico HTTP en el puerto 6820 desde las fuentes que desee. ------ #### [ AWS CLI ] 1. Actualice el clúster con una configuración REST de Slurm, como en este ejemplo. ``` aws pcs update-cluster --cluster-identifier my-cluster \ --slurm-configuration 'slurmRest={mode=STANDARD}' ``` 1. Configure el grupo de seguridad del clúster para permitir el tráfico HTTP en el puerto 6820 desde las fuentes que desee. ------ ## ¿Qué sucede después de habilitarlo Al habilitar la API REST, AWS PCS automáticamente: + Genera una clave de firma JWT y la almacena en AWS Secrets Manager. + Expone el punto final de la API `https://:6820` dentro de su VPC. + Actualiza la configuración del clúster para mostrar los detalles del punto final de la API REST. Ahora puedes autenticar y usar la API REST para la administración de trabajos y las operaciones de clúster. # Autenticación con la API REST de Slurm en PCS AWS La API REST de Slurm en AWS PCS utiliza la autenticación por token web JSON (JWT) para garantizar el acceso seguro a los recursos del clúster. AWS PCS proporciona una clave de firma gestionada almacenada en AWS Secrets Manager, que se utiliza para generar tokens JWT que contienen declaraciones de identidad de usuario específicas. ## Requisitos previos Antes de autenticarse con la API REST de Slurm, asegúrese de tener lo siguiente: + **Configuración del clúster**: clúster de AWS PCS con Slurm 25.05\$1 y la API REST habilitadas. + **Permisos de AWS**: acceso a AWS Secrets Manager para obtener la clave de firma de JWT. + **Información de usuario**: nombre de usuario, ID de usuario de POSIX y uno o más grupos de POSIX IDs para su cuenta de clúster. + **Acceso a la red**: conectividad dentro de la VPC del clúster con un grupo de seguridad que permite el puerto 6820. ## Procedimiento **Para recuperar la dirección de punto final de la API REST de Slurm** ------ #### [ Consola de administración de AWS ] 1. Abra la consola AWS PCS en. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 1. Elija su clúster de la lista. 1. En los detalles de configuración del clúster, busque la sección **Endpoints**. 1. Anote la dirección IP privada y el puerto de la **API REST de Slurm (slurmrestd)**. 1. Puede realizar llamadas a la API enviando solicitudes HTTP con el formato correcto a esta dirección. ------ #### [ AWS CLI ] 1. Consulta el estado de tu clúster con`aws pcs get-cluster`. Busca el `SLURMRESTD` punto final en el `endpoints` campo de la respuesta. A continuación se muestra un ejemplo: ``` "endpoints": [ { "type": "SLURMCTLD", "privateIpAddress": "192.0.2.1", "port": "6817" }, { "type": "SLURMRESTD", "privateIpAddress": "192.0.2.1", "port": "6820" } ] ``` 1. Puede realizar llamadas a la API enviando solicitudes HTTP con el formato adecuado a `http://:/` ------ **Para recuperar la clave de firma de JWT** 1. Abra la consola AWS PCS en [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Elija su clúster de la lista. 1. En los detalles de configuración del clúster, busque la sección de **autenticación del programador**. 1. Anote el **ARN y la versión de la clave JSON Web Token (JWT)**. 1. Utilice el AWS CLI para recuperar la clave de firma de Secrets Manager: ``` aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version ``` **Para generar un token JWT** 1. Cree un JWT con las siguientes afirmaciones obligatorias: + `exp`— Tiempo de caducidad en segundos desde 1970 para el JWT + `iat`— Tiempo actual en segundos desde 1970 + `sun`— El nombre de usuario para la autenticación + `uid`— El seudónimo de POSIX + `gid`— El ID del grupo POSIX + `id`— Propiedades de identidad POSIX adicionales + `gecos`— Campo de comentarios de usuario, que se utiliza a menudo para almacenar un nombre legible por humanos + `dir`— Directorio de inicio del usuario + `shell`— Consola predeterminada del usuario + `gids`— Lista de grupos POSIX adicionales en los que se encuentra IDs el usuario 1. Firme el JWT con la clave de firma recuperada de Secrets Manager. 1. Establezca un tiempo de caducidad adecuado para el token. **nota** Como alternativa a la `sun` reclamación, puedes proporcionar cualquiera de los siguientes datos: `username` Un nombre de campo personalizado que se define mediante `userclaimfield` el `AuthAltParameters Slurm custom settings` Un `name` campo dentro de la `id` reclamación **Para autenticar las solicitudes de API** 1. Incluye el token JWT en tus solicitudes HTTP mediante uno de estos métodos: + **Token de portador: agrega** encabezado `Authorization: Bearer ` + Cabecera **Slurm — Añadir cabecera** `X-SLURM-USER-TOKEN: ` 1. Realice solicitudes HTTP al punto final de la API REST: Este es un ejemplo de cómo acceder a la `/ping` API mediante curl y el `Authorized: Bearer` encabezado. ``` curl -X GET -H "Authorization: Bearer " \ http://:6820/slurm/v0.0.43/ping ``` ## Ejemplo de generación de JWT Obtenga la clave de firma JWT del clúster AWS PCS y guárdela como un archivo local. Sustituya los valores de **aws-region****,** secret-arn **y secret** version por los valores adecuados para su clúster. ``` #!/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 ``` Este ejemplo de Python ilustra cómo usar la clave de firma para generar 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) ``` El script imprimirá un JWT en la pantalla. ``` abcdefgtjwttoken... ``` # Uso de la API REST de Slurm para la gestión de trabajos en PCS AWS ## Descripción general de la API REST de Slurm La API REST de Slurm proporciona acceso programático a las funciones de administración de clústeres a través de solicitudes HTTP. Comprender estas características clave le ayudará a utilizar la API con PCS de forma eficaz: AWS + **Protocolo de acceso**: la API utiliza HTTP (no HTTPS) para la comunicación dentro de la red privada del clúster. + **Detalles de la conexión**: accede a la API mediante la dirección IP privada del clúster y el `slurmrestd` puerto (normalmente el 6820). El formato de URL base completo es`http://:6820`. + **Control de versiones de la API**: la versión de la API corresponde a su instalación de Slurm. **Para Slurm 25.05, utilice la versión v0.0.43.** El número de versión cambia con cada versión de Slurm. Puede encontrar las versiones de API actualmente compatibles en las notas de la versión de [Slurm](https://slurm.schedmd.com/release_notes.html). + Estructura de **URL: La estructura** de URL de la API REST de Slurm es. `http://://` [Puede encontrar información detallada sobre el uso de los puntos finales de la API REST en la documentación de Slurm.](https://slurm.schedmd.com/rest_api.html) ## Requisitos previos Antes de usar la API REST de Slurm, asegúrese de tener: + **Configuración del clúster**: clúster de AWS PCS con Slurm 25.05\$1 y la API REST habilitadas. + **Autenticación**: token JWT válido con las declaraciones de identidad de usuario adecuadas. + **Acceso a la red**: conectividad dentro de la VPC del clúster con un grupo de seguridad que permita el puerto 6820. ## Procedimiento **Para enviar un trabajo mediante la API REST** 1. Cree una solicitud de envío de trabajos con los parámetros necesarios: ``` { "job": { "name": "my-job", "partition": "compute", "nodes": 1, "tasks": 1, "script": "#!/bin/bash\necho 'Hello from Slurm REST API'" } } ``` 1. Envíe el trabajo mediante una solicitud HTTP POST: ``` curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' \ https://:6820/slurm/v0.0.43/job/submit ``` 1. Anote el ID de trabajo que aparece en la respuesta para fines de supervisión. **Para supervisar el estado del trabajo** 1. Obtenga información sobre un trabajo específico: ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` 1. Enumere todos los trabajos del usuario autenticado: ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/jobs ``` **Para cancelar un trabajo** + Envíe una solicitud de ELIMINACIÓN para cancelar un trabajo específico: ``` curl -X DELETE -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` # Preguntas frecuentes sobre la API REST de Slurm en PCS AWS Esta sección responde a las preguntas frecuentes sobre la API REST de Slurm en AWS PCS. **¿Qué es la API REST de Slurm?** La API REST de Slurm es una interfaz HTTP que le permite interactuar con el administrador de cargas de trabajo de Slurm mediante programación. Puede usar métodos HTTP estándar, como GET, POST y DELETE, para enviar trabajos, monitorear el estado del clúster y administrar los recursos sin necesidad de acceder al clúster desde la línea de comandos. **¿Puedo usar los tokens generados por? `scontrol token`** No, la `scontrol token` salida estándar no es compatible con el AWS PCS. La API REST de PCS Slurm requiere tokens JWT enriquecidos que contengan declaraciones de identidad específicas que incluyan el nombre de usuario (`sun`), el ID de usuario POSIX (`uid`) y el grupo (). IDs `gids` Los tokens Slurm estándar carecen de estas afirmaciones obligatorias y la API los rechazará. **¿Puedo acceder a la API desde fuera de mi VPC?** No, solo se puede acceder al punto final de la API REST desde su VPC mediante la dirección IP privada del controlador Slurm. Para habilitar el acceso externo, implemente AWS servicios como Application Load Balancer with VPC Link o API Gateway, o establezca conexiones VPN o de emparejamiento de VPC para una conectividad segura. **¿Por qué la API usa HTTP en lugar de HTTPS?** La API REST de Slurm está pensada para ser un punto final interno dentro de la red privada del clúster. Para las implementaciones de producción que requieren cifrado, puedes implementar la SSL/TLS terminación en un nivel superior de tu arquitectura, por ejemplo, a través de una puerta de enlace de API, un equilibrador de carga o un proxy inverso. **¿Cómo puedo controlar el acceso a la API REST?** Configure las reglas del grupo de seguridad del clúster para restringir el acceso al puerto 6820 del controlador Slurm. Establezca reglas de entrada para permitir conexiones solo desde rangos de IP confiables o fuentes específicas dentro de su VPC, bloqueando el acceso no autorizado al punto final de la API. **¿Cómo se rota la clave de firma de JWT?** Pon tu clúster en modo de mantenimiento sin instancias activas y, a continuación, inicia la rotación de claves a través de AWS Secrets Manager. Cuando se complete la rotación, vuelva a activar las colas. Todos los tokens JWT existentes dejarán de ser válidos y deberán regenerarse con la nueva clave de firma de Secrets Manager. **¿Necesito activar la contabilidad de Slurm para usar la API REST?** No, la contabilidad de Slurm no es necesaria para las operaciones básicas de la API REST, como el envío y la supervisión de los trabajos. Sin embargo, todo el `/slurmdb` punto final requiere que la contabilidad esté activa. **¿Qué herramientas de terceros funcionan con la API REST de AWS PCS?** Muchos de los clientes de la API REST de Slurm existentes deberían funcionar con AWS PCS, incluido Slurm Exporter para Prometheus, y las aplicaciones personalizadas que siguen el formato estándar de la API REST de Slurm. SlurmWeb Sin embargo, las herramientas que se basan en la autenticación deberán modificarse `scontrol token` para que funcionen con los requisitos del PCS JWT. AWS **¿El uso de la API REST conlleva algún coste adicional?** No, no hay cargos adicionales por habilitar o usar la función de la API REST de Slurm. Como de costumbre, solo paga por los recursos del clúster subyacentes. **¿Cómo puedo solucionar los problemas de la API REST?** + **Problemas de conectividad de red** Si no puede acceder al punto final de la API, verá que se agota el tiempo de espera de la conexión o se produce un error de «conexión rechazada» al realizar solicitudes HTTP al controlador de clúster. **Qué hacer**: compruebe que su cliente esté en la misma VPC o que tenga el enrutamiento de red adecuado y confirme que su grupo de seguridad permita el tráfico HTTP en el puerto 6820 desde su IP o subred de origen. + **Problemas de autenticación REST de Slurm** Si tu token JWT no es válido, ha caducado o está mal firmado, las solicitudes de API mostrarán el mensaje «Error de autenticación de protocolo» en el campo de errores de la respuesta. Ejemplos de mensajes de error: ``` { "errors": [ { "description": "Batch job submission failed", "error_number": 1007, "error": "Protocol authentication error", "source": "slurm_submit_batch_job()" } ] } ``` **Qué hacer**: Comprueba que tu token JWT esté formateado correctamente, no haya caducado y esté firmado con la clave correcta de Secrets Manager. Comprueba que el token esté correctamente formado e incluya las afirmaciones necesarias y que utilices el formato de encabezado de autenticación correcto. + **Job no se ejecuta después de enviarlo** Si su token JWT es válido pero tiene una estructura interna o un contenido incorrectos, es posible que los trabajos hayan entrado en un estado de pausa (`PD`) con el código de motivo. `JobAdminHead` `scontrol show job `Úselo para inspeccionar el trabajo; verá`JobState=PENDING, Reason=JobHeldAdmin`, y. `SystemComment=slurm_cred_create failure, holding job` **Qué hacer**: La causa principal puede ser un error en los valores de JWT. Verifique que el token esté estructurado correctamente e incluya las afirmaciones requeridas según la documentación del PCS. + **Problemas con los permisos del directorio de trabajo** Si la identidad de usuario especificada en su JWT carece de permisos de escritura en el directorio de trabajo del trabajo, el trabajo fallará y generará errores de permiso, algo similar a lo que ocurre `sbatch --chdir` con un directorio inaccesible. **Qué hacer**: Asegúrese de que el usuario especificado en su token de JWT tenga los permisos adecuados para el directorio de trabajo del trabajo.