기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # AWS PCS의 Slurm REST API AWS PCS는를 통해 Slurm의 기본 REST API에 대한 관리형 지원을 제공하여 프로그래밍 방식의 클러스터 상호 작용을 위한 HTTP 인터페이스를 `slurmrestd`제공합니다. 클러스터에 대한 직접 쉘 액세스 없이 표준 HTTP 요청을 통해 작업을 제출하고 클러스터 상태를 모니터링하며 리소스를 관리할 수 있습니다. ## 일반 사용 사례 Slurm REST API는 다양한 통합 시나리오를 지원합니다. + **웹 애플리케이션 통합**: 작업을 직접 제출하고 관리하는 사용자 지정 프런트엔드와 웹 애플리케이션을 구축합니다. + **Jupyter Notebook Integration**: 연구원이 개발 워크플로를 벗어나지 않고 노트북 환경에서 작업을 제출할 수 있습니다. + **파트너 솔루션 통합**: 타사 HPC 도구 및 워크플로 관리자를 AWS PCS 클러스터에 연결합니다. + **프로그래밍 방식 클러스터 관리**: 작업 제출, 모니터링 및 리소스 관리 워크플로를 자동화합니다. + **연구 컴퓨팅 워크플로**: API 기반 작업 관리가 필요한 학술 및 엔터프라이즈 연구 환경을 지원합니다. ## 요구 사항 및 제한 사항 Slurm REST API를 사용하기 전에 다음 세부 정보를 검토합니다. + 클러스터는 Slurm 버전 25.05 이상을 사용해야 합니다. + API 엔드포인트는 클러스터의 VPC 내의 프라이빗 IP 주소를 통해서만 액세스할 수 있습니다. + 클러스터 보안 그룹은 포트 6820에서 HTTP 트래픽을 허용해야 합니다. + 인증에는 특정 사용자 자격 증명 클레임이 있는 JWT 토큰이 필요합니다. 현재 제한 사항은 다음과 같습니다. + 에서 생성된 토큰`scontrol token`은 지원되지 않습니다. + `X-SLURM-USER-NAME` 헤더 가장은 사용할 수 없습니다. + 일부 기능을 사용하려면 Slurm 회계를 활성화해야 합니다. + Slurm CLI 필터 플러그인 메커니즘과 호환되지 않습니다. + REST API 엔드포인트에 대한 연결은 TLS로 암호화되지 않습니다. **Topics** + [일반 사용 사례](#slurm-rest-api-use-cases) + [요구 사항 및 제한 사항](#slurm-rest-api-requirements) + [AWS PCS에서 Slurm REST API 활성화](slurm-rest-api-enable.md) + [AWS PCS에서 Slurm REST API로 인증](slurm-rest-api-authenticate.md) + [AWS PCS에서 작업 관리에 Slurm REST API 사용](slurm-rest-api-use.md) + [AWS PCS의 Slurm REST API FAQ](slurm-rest-api-faq.md) # AWS PCS에서 Slurm REST API 활성화 Slurm REST API를 활성화하여 프로그래밍 방식 작업 관리 및 모니터링을 위해 클러스터의 HTTP 인터페이스에 액세스합니다. 클러스터 생성 중에이 기능을 활성화하거나 요구 사항을 충족하는 기존 클러스터를 업데이트할 수 있습니다. ## 사전 조건 Slurm REST API를 활성화하기 전에 다음을 확인해야 합니다. + **클러스터 버전**: Slurm 버전 25.05 이상. + **보안 그룹**: 원하는 소스의 포트 6820에서 HTTP 트래픽을 허용하는 규칙입니다. ## 절차 **새 클러스터에서 Slurm REST API를 활성화하려면** ------ #### [ AWS Management Console ] 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) AWS PCS 콘솔을 엽니다. 1. **클러스터 생성**을 선택합니다. 1. **클러스터 세부 정보**에서 Slurm 버전 25.05 이상을 선택합니다. 1. 필요에 따라 다른 클러스터 설정을 구성합니다. 1. **스케줄러 구성** 섹션에서 **REST API**를 **활성화됨**으로 설정합니다. 1. 원하는 소스의 포트 6820에서 HTTP 트래픽을 허용하도록 클러스터 보안 그룹을 구성합니다. 1. 클러스터 생성 프로세스를 완료합니다. ------ #### [ AWS CLI ] 1. 클러스터를 생성할 때 Slurm REST 구성을 추가합니다. ``` 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. 원하는 소스의 포트 6820에서 HTTP 트래픽을 허용하도록 클러스터 보안 그룹을 구성합니다. ------ **기존 클러스터에서 Slurm REST API를 활성화하려면** ------ #### [ AWS Management Console ] 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) AWS PCS 콘솔을 엽니다. 1. 목록에서 클러스터를 선택합니다. 1. 클러스터 세부 정보에서 클러스터가 Slurm 버전 25.05 이상을 사용하는지 확인합니다. 1. **클러스터 편집**을 선택합니다. 1. **스케줄러 구성** 섹션에서 **REST API**를 **활성화됨**으로 설정합니다. 1. **클러스터 업데이트를** 선택하여 변경 사항을 적용합니다. 1. 원하는 소스의 포트 6820에서 HTTP 트래픽을 허용하도록 클러스터 보안 그룹을 구성합니다. ------ #### [ AWS CLI ] 1. 이 예제와 같이 클러스터를 Slurm REST 구성으로 업데이트합니다. ``` aws pcs update-cluster --cluster-identifier my-cluster \ --slurm-configuration 'slurmRest={mode=STANDARD}' ``` 1. 원하는 소스의 포트 6820에서 HTTP 트래픽을 허용하도록 클러스터 보안 그룹을 구성합니다. ------ ## 활성화 후 발생하는 일 REST API를 활성화하면 AWS PCS가 자동으로 다음을 수행합니다. + JWT 서명 키를 생성하여 AWS Secrets Manager에 저장합니다. + VPC `https://:6820` 내의에서 API 엔드포인트를 노출합니다. + 클러스터 구성을 업데이트하여 REST API 엔드포인트 세부 정보를 표시합니다. 이제 작업 관리 및 클러스터 작업에 REST API를 인증하고 사용할 수 있습니다. # AWS PCS에서 Slurm REST API로 인증 AWS PCS의 Slurm REST API는 JSON 웹 토큰(JWT) 인증을 사용하여 클러스터 리소스에 대한 보안 액세스를 보장합니다. AWS PCS는 AWS Secrets Manager에 저장된 관리형 서명 키를 제공하며, 이를 사용하여 특정 사용자 자격 증명 클레임이 포함된 JWT 토큰을 생성합니다. ## 사전 조건 Slurm REST API로 인증하기 전에 다음을 확인하세요. + **클러스터 구성**: Slurm 25.05 이상 및 REST API가 활성화된 AWS PCS 클러스터. + **AWS 권한**: JWT 서명 키에 대한 AWS Secrets Manager에 대한 액세스입니다. + **사용자 정보**: 클러스터 계정의 사용자 이름, POSIX 사용자 ID 및 하나 이상의 POSIX 그룹 IDs. + **네트워크 액세스**: 포트 6820을 허용하는 보안 그룹을 사용한 클러스터의 VPC 내 연결. ## 절차 **Slurm REST API 엔드포인트 주소를 검색하려면** ------ #### [ AWS Management Console ] 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) AWS PCS 콘솔을 엽니다. 1. 목록에서 클러스터를 선택합니다. 1. 클러스터 구성 세부 정보에서 **엔드포인트** 섹션을 찾습니다. 1. **Slurm REST API(slurmrestd)**의 프라이빗 IP 주소와 포트를 기록해 둡니다. 1. 올바른 형식의 HTTP 요청을이 주소로 전송하여 API를 호출할 수 있습니다. ------ #### [ AWS CLI ] 1. 를 사용하여 클러스터 상태를 쿼리합니다`aws pcs get-cluster`. 응답의 `endpoints` 필드에서 `SLURMRESTD` 엔드포인트를 찾습니다. 다음 예를 참고하세요 ``` "endpoints": [ { "type": "SLURMCTLD", "privateIpAddress": "192.0.2.1", "port": "6817" }, { "type": "SLURMRESTD", "privateIpAddress": "192.0.2.1", "port": "6820" } ] ``` 1. 올바른 형식의 HTTP 요청을 로 전송하여 API 호출을 수행할 수 있습니다. `http://:/` ------ **JWT 서명 키를 검색하려면** 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) AWS PCS 콘솔을 엽니다. 1. 목록에서 클러스터를 선택합니다. 1. 클러스터 구성 세부 정보에서 **스케줄러 인증** 섹션을 찾습니다. 1. **JSON 웹 토큰(JWT) 키** ARN 및 버전을 기록해 둡니다. 1. AWS CLI 를 사용하여 Secrets Manager에서 서명 키를 검색합니다. ``` aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version ``` **JWT 토큰을 생성하려면** 1. 다음과 같은 필수 클레임을 사용하여 JWT를 생성합니다. + `exp` - JWT의 1970년 이후 초 단위 만료 시간 + `iat` - 1970년 이후 현재 초 단위 시간 + `sun` - 인증을 위한 사용자 이름 + `uid` - POSIX 사용자 ID + `gid` - POSIX 그룹 ID + `id` - 추가 POSIX 자격 증명 속성 + `gecos` - 사람이 읽을 수 있는 이름을 저장하는 데 자주 사용되는 사용자 설명 필드 + `dir` - 사용자의 홈 디렉터리 + `shell` - 사용자의 기본 셸 + `gids` - 사용자가 있는 추가 POSIX 그룹 IDs 목록 1. Secrets Manager에서 검색한 서명 키를 사용하여 JWT에 서명합니다. 1. 토큰의 적절한 만료 시간을 설정합니다. **참고** `sun` 클레임의 대안으로 다음 중 하나를 제공할 수 있습니다. `username` `userclaimfield`에서를 통해 정의하는 사용자 지정 필드 이름 `AuthAltParameters Slurm custom settings` `id` 클레임 내의 `name` 필드 **API 요청을 인증하려면** 1. 다음 방법 중 하나를 사용하여 HTTP 요청에 JWT 토큰을 포함합니다. + **베어러 토큰** - `Authorization: Bearer ` 헤더 추가 + **Slurm 헤더** - `X-SLURM-USER-TOKEN: ` 헤더 추가 1. REST API 엔드포인트에 HTTP 요청을 수행합니다. 다음은 curl과 `Authorized: Bearer` 헤더를 사용하여 `/ping` API에 액세스하는 예입니다. ``` curl -X GET -H "Authorization: Bearer " \ http://:6820/slurm/v0.0.43/ping ``` ## JWT 생성 예 AWS PCS 클러스터 JWT 서명 키를 가져와 로컬 파일로 저장합니다. **aws-region**, **secret-arn** 및 **secret 버전의** 값을 클러스터에 적합한 값으로 바꿉니다. ``` #!/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 ``` 이 Python 예제에서는 서명 키를 사용하여 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) ``` 스크립트는 화면에 JWT를 인쇄합니다. ``` abcdefgtjwttoken... ``` # AWS PCS에서 작업 관리에 Slurm REST API 사용 ## Slurm REST API 개요 Slurm REST API는 HTTP 요청을 통해 클러스터 관리 함수에 프로그래밍 방식으로 액세스할 수 있습니다. 이러한 주요 특성을 이해하면 API를 AWS PCS와 함께 효과적으로 사용하는 데 도움이 됩니다. + **액세스 프로토콜**: API는 클러스터의 프라이빗 네트워크 내에서 통신하기 위해 HTTP(HTTPS 아님)를 사용합니다. + **연결 세부 정보**: 클러스터의 프라이빗 IP 주소와 `slurmrestd` 포트(일반적으로 6820)를 사용하여 API에 액세스합니다. 전체 기본 URL 형식은 입니다`http://:6820`. + **API 버전 관리**: API 버전은 Slurm 설치에 해당합니다. Slurm 25.05의 경우 버전 **v0.0.43**을 사용합니다. 버전 번호는 각 Slurm 릴리스에 따라 변경됩니다. [Slurm 릴리스 정보](https://slurm.schedmd.com/release_notes.html)에서 현재 지원되는 API 버전을 찾을 수 있습니다. + **URL 구조**: Slurm REST API의 URL 구조는 입니다`http://://`. REST API 엔드포인트에 대한 자세한 사용 정보는 [Slurm 설명서](https://slurm.schedmd.com/rest_api.html)에서 확인할 수 있습니다. ## 사전 조건 Slurm REST API를 사용하기 전에 다음을 확인해야 합니다. + **클러스터 구성**: Slurm 25.05 이상 및 REST API가 활성화된 AWS PCS 클러스터. + **인증**: 적절한 사용자 자격 증명 클레임이 있는 유효한 JWT 토큰입니다. + **네트워크 액세스**: 포트 6820을 허용하는 보안 그룹을 사용한 클러스터의 VPC 내 연결. ## 절차 **REST API를 사용하여 작업을 제출하려면** 1. 필요한 파라미터를 사용하여 작업 제출 요청을 생성합니다. ``` { "job": { "name": "my-job", "partition": "compute", "nodes": 1, "tasks": 1, "script": "#!/bin/bash\necho 'Hello from Slurm REST API'" } } ``` 1. HTTP POST 요청을 사용하여 작업을 제출합니다. ``` curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' \ https://:6820/slurm/v0.0.43/job/submit ``` 1. 모니터링 목적으로 응답에 반환된 작업 ID를 기록해 둡니다. **작업 상태를 모니터링하려면** 1. 특정 작업에 대한 정보를 가져옵니다. ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` 1. 인증된 사용자의 모든 작업을 나열합니다. ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/jobs ``` **작업 취소** + DELETE 요청을 보내 특정 작업을 취소합니다. ``` curl -X DELETE -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` # AWS PCS의 Slurm REST API FAQ 이 섹션에서는 AWS PCS의 Slurm REST API에 대해 자주 묻는 질문에 답변합니다. **Slurm REST API란 무엇입니까?** Slurm REST API는 Slurm 워크로드 관리자와 프로그래밍 방식으로 상호 작용할 수 있는 HTTP 인터페이스입니다. GET, POST 및 DELETE와 같은 표준 HTTP 메서드를 사용하여 클러스터에 대한 명령줄 액세스 없이 작업을 제출하고 클러스터 상태를 모니터링하며 리소스를 관리할 수 있습니다. **에서 생성한 토큰을 사용할 수 있습니까`scontrol token`?** 아니요, 표준 `scontrol token` 출력은 AWS PCS와 호환되지 않습니다. PCS Slurm REST API에는 username(`sun`), POSIX 사용자 ID() 및 group ID(`uid`)를 포함하는 특정 자격 증명 클레임이 포함된 보강된 JWT 토큰이 필요합니다`gids`. IDs 표준 Slurm 토큰에는 이러한 필수 클레임이 없으며 API에서 거부됩니다. **VPC 외부에서 API에 액세스할 수 있나요?** 아니요. REST API 엔드포인트는 Slurm 컨트롤러의 프라이빗 IP 주소를 사용하여 VPC 내에서만 액세스할 수 있습니다. 외부 액세스를 활성화하려면 VPC Link, API Gateway를 사용하여 Application Load Balancer와 같은 AWS 서비스를 구현하거나 보안 연결을 위해 VPC 피어링 또는 VPN 연결을 설정합니다. **API가 HTTPS 대신 HTTP를 사용하는 이유는 무엇입니까?** Slurm REST API는 클러스터의 프라이빗 네트워크 내에서 내부 엔드포인트가 되도록 설계되었습니다. 암호화가 필요한 프로덕션 배포의 경우 API 게이트웨이, 로드 밸런서 또는 역방향 프록시를 통해 아키텍처에서 더 높은 수준에서 SSL/TLS 종료를 구현할 수 있습니다. **REST API에 대한 액세스를 제어하려면 어떻게 해야 합니까?** 클러스터의 보안 그룹 규칙을 구성하여 Slurm 컨트롤러의 포트 6820에 대한 액세스를 제한합니다. 신뢰할 수 있는 IP 범위 또는 VPC 내의 특정 소스로부터의 연결만 허용하도록 인바운드 규칙을 설정하여 API 엔드포인트에 대한 무단 액세스를 차단합니다. **JWT 서명 키를 교체하려면 어떻게 해야 합니까?** 활성 인스턴스 없이 클러스터를 유지 관리 모드로 전환한 다음 AWS Secrets Manager를 통해 키 교체를 시작합니다. 교체가 완료되면 대기열을 다시 활성화합니다. 기존 JWT 토큰은 모두 유효하지 않으므로 Secrets Manager의 새 서명 키를 사용하여 다시 생성해야 합니다. **REST API를 사용하려면 Slurm 회계를 활성화해야 합니까?** 아니요, Slurm 회계는 작업 제출 및 모니터링과 같은 기본 REST API 작업에 필요하지 않습니다. 그러나 전체 `/slurmdb` 엔드포인트를 활성화하려면 회계가 필요합니다. ** AWS PCS REST API에서 작동하는 타사 도구는 무엇입니까?** Prometheus용 Slurm Exporter, SlurmWeb 및 표준 Slurm REST API 형식을 따르는 사용자 지정 애플리케이션을 포함하여 많은 기존 Slurm REST API 클라이언트가 AWS PCS와 함께 작동해야 합니다. 그러나 인증을 `scontrol token` 위해에 의존하는 도구는 AWS PCS JWT 요구 사항에 맞게 수정해야 합니다. **REST API를 사용하는 데 추가 비용이 발생하나요?** 아니요. Slurm REST API 기능을 활성화하거나 사용하는 데 따르는 추가 요금은 없습니다. 기본 클러스터 리소스에 대한 비용만 평소와 같이 지불하면 됩니다. **REST API 문제를 해결하려면 어떻게 해야 합니까?** + **네트워크 연결 문제** API 엔드포인트에 연결할 수 없는 경우 클러스터 컨트롤러에 HTTP 요청을 할 때 연결 제한 시간 또는 "연결 거부" 오류가 표시됩니다. **조치**: 클라이언트가 동일한 VPC에 있거나 적절한 네트워크 라우팅이 있는지 확인하고 보안 그룹이 소스 IP 또는 서브넷에서 포트 6820의 HTTP 트래픽을 허용하는지 확인합니다. + **Slurm REST 인증 문제** JWT 토큰이 유효하지 않거나 만료되었거나 잘못 서명된 경우 API 요청은 응답의 오류 필드에 "프로토콜 인증 오류"를 반환합니다. 오류 메시지 예: ``` { "errors": [ { "description": "Batch job submission failed", "error_number": 1007, "error": "Protocol authentication error", "source": "slurm_submit_batch_job()" } ] } ``` **조치**: JWT 토큰의 형식이 올바른지, 만료되지 않았는지, Secrets Manager의 올바른 키로 서명되었는지 확인합니다. 토큰이 올바르게 구성되었고 필요한 클레임이 포함되어 있으며 올바른 인증 헤더 형식을 사용하고 있는지 확인합니다. + **제출 후 작업이 실행되지 않음** JWT 토큰이 유효하지만 내부 구조나 콘텐츠가 잘못된 경우 작업이 사유 코드와 함께 일시 중지(`PD`) 상태로 전환되었을 수 있습니다`JobAdminHead`. `scontrol show job `를 사용하여 작업을 검사합니다. `JobState=PENDING, Reason=JobHeldAdmin`, 및가 표시됩니다`SystemComment=slurm_cred_create failure, holding job`. 해야 **할 일**: 근본 원인은 JWT의 잘못된 값일 수 있습니다. 토큰이 적절하게 구성되어 있고 PCS 설명서에 따라 필요한 클레임이 포함되어 있는지 확인합니다. + **작업 디렉터리 권한 문제** JWT에 지정된 사용자 자격 증명에 작업의 작업 디렉터리에 대한 쓰기 권한이 없는 경우 액세스할 수 없는 디렉터리에서를 사용하는 것과 마찬가지로 권한 오류와 `sbatch --chdir` 함께 작업이 실패합니다. **조치**: JWT 토큰에 지정된 사용자에게 작업의 작업 디렉터리에 대한 적절한 권한이 있는지 확인합니다.