As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # API REST do Slurm em PCS AWS AWS O PCS fornece suporte gerenciado para a API REST nativa do Slurm`slurmrestd`, fornecendo uma interface HTTP para interação programática com clusters. Você pode enviar trabalhos, monitorar o status do cluster e gerenciar recursos por meio de solicitações HTTP padrão sem precisar de acesso direto ao shell ao seu cluster. ## Casos de uso comuns A API REST do Slurm oferece suporte a vários cenários de integração: + **Integração de aplicativos da Web**: crie front-ends e aplicativos da web personalizados que enviam e gerenciam trabalhos diretamente. + **Integração com o Jupyter Notebook**: permite que os pesquisadores enviem trabalhos de ambientes de notebook sem sair do fluxo de trabalho de desenvolvimento. + **Integração de soluções de parceiros**: conecte ferramentas de HPC e gerenciadores de fluxo de trabalho de terceiros aos seus clusters de AWS PCS. + **Gerenciamento programático de clusters**: automatize os fluxos de trabalho de envio, monitoramento e gerenciamento de recursos de tarefas. + **Fluxos de trabalho de computação de pesquisa**: Support ambientes de pesquisa acadêmica e empresarial que exigem gerenciamento de tarefas orientado por API. ## Requisitos e limitações Antes de usar a API REST do Slurm, revise estes detalhes: + Seu cluster deve usar a versão 25.05 ou superior do Slurm. + O endpoint da API só poderá ser acessado por meio de um endereço IP privado na VPC do seu cluster. + Seu grupo de segurança do cluster deve permitir tráfego HTTP na porta 6820. + A autenticação requer tokens JWT com declarações de identidade de usuário específicas. As limitações atuais incluem: + Os tokens gerados por não `scontrol token` são suportados. + `X-SLURM-USER-NAME`a representação do cabeçalho não está disponível. + Algumas funcionalidades exigem que a contabilidade do Slurm esteja ativada. + Não é compatível com o mecanismo do plug-in de filtro CLI do Slurm. + As conexões com o endpoint da API REST não são criptografadas com TLS. **Topics** + [Casos de uso comuns](#slurm-rest-api-use-cases) + [Requisitos e limitações](#slurm-rest-api-requirements) + [Habilitando a API REST do Slurm no PCS AWS](slurm-rest-api-enable.md) + [Autenticação com a API REST do Slurm no PCS AWS](slurm-rest-api-authenticate.md) + [Usando a API REST do Slurm para gerenciamento de tarefas no PCS AWS](slurm-rest-api-use.md) + [Perguntas frequentes sobre a API REST do Slurm no PCS AWS](slurm-rest-api-faq.md) # Habilitando a API REST do Slurm no PCS AWS Ative a API REST do Slurm para acessar a interface HTTP do seu cluster para gerenciamento e monitoramento programáticos de tarefas. Você pode ativar esse recurso durante a criação do cluster ou atualizar um cluster existente que atenda aos requisitos. ## Pré-requisitos Antes de ativar a API REST do Slurm, verifique se você tem: + **Versão do cluster**: Slurm versão 25.05 ou superior. + **Grupo de segurança**: regras que permitem o tráfego HTTP na porta 6820 a partir das fontes desejadas. ## Procedimento **Para habilitar a API REST do Slurm em um novo cluster** ------ #### [ Console de gerenciamento da AWS ] 1. Abra o console AWS PCS em [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Selecione **Criar cluster**. 1. Em **Detalhes do cluster**, escolha Slurm versão 25.05 ou superior. 1. Defina as outras configurações do cluster conforme necessário. 1. Na seção **Configuração do Agendador**, defina a **API REST** como **Ativada**. 1. Configure seu grupo de segurança de cluster para permitir tráfego HTTP na porta 6820 a partir das fontes desejadas. 1. Conclua o processo de criação do cluster. ------ #### [ AWS CLI ] 1. Adicione uma configuração REST do Slurm ao criar seu 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. Configure seu grupo de segurança de cluster para permitir tráfego HTTP na porta 6820 a partir das fontes desejadas. ------ **Para habilitar a API REST do Slurm em um cluster existente** ------ #### [ Console de gerenciamento da AWS ] 1. Abra o console AWS PCS em [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Escolha seu cluster na lista. 1. Verifique se seu cluster usa a versão 25.05 ou superior do Slurm nos detalhes do cluster. 1. Escolha **Editar cluster**. 1. Na seção **Configuração do Agendador**, defina a **API REST** como **Ativada**. 1. Escolha **Atualizar cluster** para aplicar as alterações. 1. Configure seu grupo de segurança de cluster para permitir tráfego HTTP na porta 6820 a partir das fontes desejadas. ------ #### [ AWS CLI ] 1. Atualize seu cluster com uma configuração REST do Slurm, como neste exemplo. ``` aws pcs update-cluster --cluster-identifier my-cluster \ --slurm-configuration 'slurmRest={mode=STANDARD}' ``` 1. Configure seu grupo de segurança de cluster para permitir tráfego HTTP na porta 6820 a partir das fontes desejadas. ------ ## O que acontece depois de ativar Quando você ativa a API REST, o AWS PCS automaticamente: + Gera uma chave de assinatura do JWT e a armazena no AWS Secrets Manager. + Expõe o endpoint da API `https://:6820` em sua VPC. + Atualiza a configuração do cluster para mostrar os detalhes do endpoint da API REST. Agora você pode autenticar e usar a API REST para gerenciamento de tarefas e operações de cluster. # Autenticação com a API REST do Slurm no PCS AWS A API REST do Slurm no AWS PCS usa a autenticação JSON Web Token (JWT) para garantir acesso seguro aos recursos do cluster. AWS O PCS fornece uma chave de assinatura gerenciada armazenada no AWS Secrets Manager, que você usa para gerar tokens JWT contendo declarações de identidade de usuário específicas. ## Pré-requisitos Antes de se autenticar com a API REST do Slurm, verifique se você tem: + **Configuração de cluster**: cluster AWS PCS com Slurm 25.05\$1 e API REST habilitada. + **Permissões da AWS**: acesso ao AWS Secrets Manager para a chave de assinatura do JWT. + **Informações do usuário**: nome de usuário, ID de usuário POSIX e um ou mais grupos POSIX IDs para sua conta de cluster. + **Acesso à rede**: conectividade na VPC do seu cluster com o grupo de segurança que permite a porta 6820. ## Procedimento **Para recuperar o endereço do endpoint da API Slurm REST** ------ #### [ Console de gerenciamento da AWS ] 1. Abra o console AWS PCS em [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Escolha seu cluster na lista. 1. Nos detalhes da configuração do cluster, localize a seção **Endpoints**. 1. Observe o endereço IP privado e a porta da **API REST do Slurm (slurmrestd**). 1. Você pode fazer chamadas de API enviando solicitações HTTP formatadas corretamente para esse endereço. ------ #### [ AWS CLI ] 1. Consulte o status do seu cluster com`aws pcs get-cluster`. Procure o `SLURMRESTD` endpoint no `endpoints` campo na resposta. Exemplo: ``` "endpoints": [ { "type": "SLURMCTLD", "privateIpAddress": "192.0.2.1", "port": "6817" }, { "type": "SLURMRESTD", "privateIpAddress": "192.0.2.1", "port": "6820" } ] ``` 1. Você pode fazer chamadas de API enviando solicitações HTTP formatadas corretamente para `http://:/` ------ **Para recuperar a chave de assinatura do JWT** 1. Abra o console AWS PCS em [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/). 1. Escolha seu cluster na lista. 1. Nos detalhes da configuração do cluster, localize a seção **Autenticação do Agendador**. 1. Observe o **ARN e a versão da chave JSON Web Token (JWT)**. 1. Use o AWS CLI para recuperar a chave de assinatura do Secrets Manager: ``` aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version ``` **Para gerar um token JWT** 1. Crie um JWT com as seguintes reivindicações obrigatórias: + `exp`— Tempo de expiração em segundos desde 1970 para o JWT + `iat`— Tempo atual em segundos desde 1970 + `sun`— O nome de usuário para autenticação + `uid`— O ID de usuário POSIX + `gid`— O ID do grupo POSIX + `id`— Propriedades adicionais de identidade POSIX + `gecos`— Campo de comentário do usuário, geralmente usado para armazenar um nome legível por humanos + `dir`— Diretório inicial do usuário + `shell`— Shell padrão do usuário + `gids`— Lista de grupos POSIX adicionais em IDs que o usuário está 1. Assine o JWT usando a chave de assinatura recuperada do Secrets Manager. 1. Defina um prazo de expiração apropriado para o token. **nota** Como alternativa à `sun` reivindicação, você pode fornecer qualquer um dos seguintes: `username` Um nome de campo personalizado que você define por `userclaimfield` meio do `AuthAltParameters Slurm custom settings` Um `name` campo dentro da `id` reivindicação **Para autenticar solicitações de API** 1. Inclua o token JWT em suas solicitações HTTP usando um destes métodos: + **Token do portador** — Adicionar `Authorization: Bearer ` cabeçalho + Cabeçalho **do Slurm — Adicionar cabeçalho** `X-SLURM-USER-TOKEN: ` 1. Faça solicitações HTTP para o endpoint da API REST: Aqui está um exemplo de como acessar a `/ping` API usando curl e o `Authorized: Bearer` cabeçalho. ``` curl -X GET -H "Authorization: Bearer " \ http://:6820/slurm/v0.0.43/ping ``` ## Exemplo de geração de JWT Obtenha a chave de assinatura JWT do cluster AWS PCS e armazene-a como um arquivo local. Substitua os valores de **aws-region****,** secret-arn **e secret** version por valores apropriados para seu 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 ``` Este exemplo em Python ilustra como usar a chave de assinatura para gerar um 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) ``` O script imprimirá um JWT na tela. ``` abcdefgtjwttoken... ``` # Usando a API REST do Slurm para gerenciamento de tarefas no PCS AWS ## Visão geral da API Slurm REST A API REST do Slurm fornece acesso programático às funções de gerenciamento de cluster por meio de solicitações HTTP. A compreensão dessas características principais ajudará você a usar a API com o AWS PCS de forma eficaz: + **Protocolo de acesso**: a API usa HTTP (não HTTPS) para comunicação na rede privada do seu cluster. + **Detalhes da conexão**: acesse a API usando o endereço IP privado do seu cluster e a `slurmrestd` porta (normalmente 6820). O formato completo do URL base é`http://:6820`. + Controle de **versão da API: a** versão da API corresponde à sua instalação do Slurm. **Para o Slurm 25.05, use a versão v0.0.43.** O número da versão muda a cada lançamento do Slurm. Você pode encontrar as versões da API atualmente suportadas nas notas de [lançamento do Slurm](https://slurm.schedmd.com/release_notes.html). + **Estrutura de URL**: A estrutura de URL para a API REST do Slurm é. `http://://` Informações detalhadas de uso dos endpoints da API REST podem ser encontradas na documentação do [Slurm](https://slurm.schedmd.com/rest_api.html). ## Pré-requisitos Antes de usar a API REST do Slurm, certifique-se de ter: + **Configuração de cluster**: cluster AWS PCS com Slurm 25.05\$1 e API REST habilitada. + **Autenticação**: token JWT válido com declarações de identidade de usuário adequadas. + **Acesso à rede**: conectividade na VPC do seu cluster com um grupo de segurança que permite a porta 6820. ## Procedimento **Para enviar um trabalho usando a API REST** 1. Crie uma solicitação de envio de trabalho com os parâmetros necessários: ``` { "job": { "name": "my-job", "partition": "compute", "nodes": 1, "tasks": 1, "script": "#!/bin/bash\necho 'Hello from Slurm REST API'" } } ``` 1. Envie o trabalho usando uma solicitação HTTP POST: ``` curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' \ https://:6820/slurm/v0.0.43/job/submit ``` 1. Anote o ID do trabalho retornado na resposta para fins de monitoramento. **Para monitorar o status do trabalho** 1. Obtenha informações sobre um trabalho específico: ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` 1. Liste todos os trabalhos do usuário autenticado: ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/jobs ``` **Para cancelar um trabalho** + Envie uma solicitação DELETE para cancelar um trabalho específico: ``` curl -X DELETE -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` # Perguntas frequentes sobre a API REST do Slurm no PCS AWS Esta seção responde às perguntas mais frequentes sobre a API REST do Slurm no AWS PCS. **O que é a API REST do Slurm?** A API REST do Slurm é uma interface HTTP que permite interagir programaticamente com o gerenciador de carga de trabalho do Slurm. Você pode usar métodos HTTP padrão, como GET, POST e DELETE, para enviar trabalhos, monitorar o status do cluster e gerenciar recursos sem exigir acesso à linha de comando ao cluster. **Posso usar tokens gerados por`scontrol token`?** Não, a `scontrol token` saída padrão não é compatível com o AWS PCS. A API REST do PCS Slurm requer tokens JWT enriquecidos contendo declarações de identidade específicas que incluem nome de usuário (`sun`), ID de usuário POSIX () e grupo (`uid`). IDs `gids` Os tokens Standard Slurm não possuem essas reivindicações obrigatórias e serão rejeitados pela API. **Posso acessar a API de fora da minha VPC?** Não, o endpoint da API REST só pode ser acessado de dentro da sua VPC usando o endereço IP privado do controlador Slurm. Para habilitar o acesso externo, implemente AWS serviços como o Application Load Balancer com VPC Link, API Gateway ou estabeleça conexões VPN ou emparelhamento de VPC para conectividade segura. **Por que a API usa HTTP em vez de HTTPS?** A API REST do Slurm foi projetada para ser um endpoint interno na rede privada do seu cluster. Para implantações de produção que exigem criptografia, você pode implementar a SSL/TLS terminação em um nível mais alto em sua arquitetura, como por meio de um gateway de API, balanceador de carga ou proxy reverso. **Como faço para controlar o acesso à API REST?** Configure as regras do grupo de segurança do seu cluster para restringir o acesso à porta 6820 no controlador Slurm. Defina regras de entrada para permitir conexões somente de intervalos de IP confiáveis ou fontes específicas em sua VPC, bloqueando o acesso não autorizado ao endpoint da API. **Como faço para girar a chave de assinatura do JWT?** Coloque seu cluster em modo de manutenção sem instâncias ativas e, em seguida, inicie a rotação de chaves por meio do AWS Secrets Manager. Após a conclusão da rotação, reative as filas. Todos os tokens JWT existentes se tornarão inválidos e deverão ser regenerados usando a nova chave de assinatura do Secrets Manager. **Preciso habilitar a contabilidade do Slurm para usar a API REST?** Não, a contabilidade do Slurm não é necessária para operações básicas da API REST, como envio e monitoramento de trabalhos. No entanto, todo o `/slurmdb` endpoint exige que a contabilidade esteja ativa. **Quais ferramentas de terceiros funcionam com a API REST do AWS PCS?** Muitos clientes existentes da API REST do Slurm devem trabalhar com AWS PCS, incluindo o Slurm Exporter for Prometheus, e aplicativos personalizados que sigam o formato padrão da API REST do Slurm. SlurmWeb No entanto, as ferramentas que dependem `scontrol token` da autenticação precisarão ser modificadas para funcionar com os requisitos do AWS PCS JWT. **Há algum custo adicional para usar a API REST?** Não, não há cobranças adicionais para ativar ou usar o recurso da API REST do Slurm. Você paga apenas pelos recursos do cluster subjacente, como de costume. **Como posso solucionar problemas com a API REST?** + **Problemas de conectividade de rede** Se você não conseguir acessar o endpoint da API, verá tempos limite de conexão ou erros de “conexão recusada” ao fazer solicitações HTTP ao controlador de cluster. **O que fazer**: verifique se seu cliente está na mesma VPC ou tem roteamento de rede adequado e confirme se seu grupo de segurança permite tráfego HTTP na porta 6820 do seu IP ou sub-rede de origem. + **Problemas de autenticação REST do Slurm** Se seu token JWT for inválido, expirado ou assinado incorretamente, as solicitações de API retornarão “Erro de autenticação de protocolo” no campo de erros da resposta. Exemplo de mensagem de erro: ``` { "errors": [ { "description": "Batch job submission failed", "error_number": 1007, "error": "Protocol authentication error", "source": "slurm_submit_batch_job()" } ] } ``` **O que fazer**: verifique se seu token JWT está formatado corretamente, não está expirado e assinado com a chave correta do Secrets Manager. Verifique se o token está formado corretamente e inclui as declarações necessárias e se você está usando o formato correto do cabeçalho de autenticação. + **Falha na execução do trabalho após o envio** Se seu token JWT for válido, mas contiver conteúdo ou estrutura interna incorretos, os trabalhos podem ter entrado no estado paused (`PD`) com o código do motivo. `JobAdminHead` Use `scontrol show job ` para inspecionar o trabalho — você verá `JobState=PENDING, Reason=JobHeldAdmin` e. `SystemComment=slurm_cred_create failure, holding job` **O que fazer**: a causa raiz pode ser valores errados no JWT. Verifique se o token está estruturado adequadamente e inclui as declarações necessárias de acordo com a documentação do PCS. + **Problemas de permissão do diretório de trabalho** Se a identidade do usuário especificada em seu JWT não tiver permissões de gravação no diretório de trabalho do trabalho, o trabalho falhará com erros de permissão, semelhantes ao uso `sbatch --chdir` com um diretório inacessível. **O que fazer**: certifique-se de que o usuário especificado em seu token JWT tenha as permissões apropriadas para o diretório de trabalho do trabalho.