翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # PCS の Slurm AWS REST API AWS PCS は、 を通じて Slurm のネイティブ REST API のマネージドサポートを提供し`slurmrestd`、プログラムによるクラスター操作のための HTTP インターフェイスを提供します。クラスターへの直接シェルアクセスを必要とせずに、標準 HTTP リクエストを通じてジョブの送信、クラスターステータスのモニタリング、リソースの管理を行うことができます。 ## 一般的なユースケース Slurm REST API は、さまざまな統合シナリオをサポートしています。 + **ウェブアプリケーション統合**: ジョブを直接送信および管理するためのカスタムフロントエンドとウェブアプリケーションを構築します。 + **Jupyter Notebook Integration**: 開発ワークフローを離れることなく、ノートブック環境からジョブを送信できます。 + **パートナーソリューションの統合**: サードパーティーの HPC ツールとワークフローマネージャーを PCS AWS クラスターに接続します。 + **プログラムによるクラスター管理**: ジョブの送信、モニタリング、リソース管理のワークフローを自動化します。 + **Research Computing Workflows**: API 主導のジョブ管理を必要とする学術的および企業の研究環境をサポートします。 ## 要件と制限 Slurm REST API を使用する前に、以下の詳細を確認してください。 + クラスターは Slurm バージョン 25.05 以降を使用する必要があります。 + API エンドポイントには、クラスターの VPC 内のプライベート IP アドレスを介してのみアクセスできます。 + クラスターセキュリティグループは、ポート 6820 で HTTP トラフィックを許可する必要があります。 + 認証には、特定のユーザー ID クレームを持つ JWT トークンが必要です。 現在の制限は次のとおりです。 + によって生成されたトークン`scontrol token`はサポートされていません。 + `X-SLURM-USER-NAME` ヘッダー偽装は使用できません。 + 一部の機能では、Slurm アカウンティングを有効にする必要があります。 + Slurm CLI フィルタープラグインメカニズムと互換性がありません。 + REST API エンドポイントへの接続は TLS で暗号化されません。 **Topics** + [一般的なユースケース](#slurm-rest-api-use-cases) + [要件と制限](#slurm-rest-api-requirements) + [PCS での Slurm REST API AWS の有効化](slurm-rest-api-enable.md) + [AWS PCS での Slurm REST API を使用した認証](slurm-rest-api-authenticate.md) + [PCS でのジョブ管理に Slurm REST API AWS を使用する](slurm-rest-api-use.md) + [PCS での Slurm REST API AWS のよくある質問](slurm-rest-api-faq.md) # PCS での Slurm REST API AWS の有効化 Slurm REST API を有効にして、プログラムによるジョブ管理とモニタリングのためにクラスターの HTTP インターフェイスにアクセスします。この機能は、クラスターの作成時に有効にすることも、要件を満たす既存のクラスターを更新することもできます。 ## 前提条件 Slurm REST API を有効にする前に、以下を確認してください。 + **クラスターバージョン**: Slurm バージョン 25.05 以降。 + **セキュリティグループ**: 目的のソースからのポート 6820 での HTTP トラフィックを許可するルール。 ## 手順 **新しいクラスターで Slurm REST API を有効にするには** ------ #### [ AWS マネジメントコンソール ] 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) で AWS PCS コンソールを開きます。 1. **[クラスターを作成]** を選択します。 1. **クラスターの詳細**で、Slurm バージョン 25.05 以降を選択します。 1. 必要に応じて、他のクラスター設定を構成します。 1. ス**ケジューラ設定**セクションで、**REST API** を **Enabled** に設定します。 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 マネジメントコンソール ] 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) で AWS PCS コンソールを開きます。 1. リストからクラスターを選択します。 1. クラスターがクラスターの詳細で Slurm バージョン 25.05 以降を使用していることを確認します。 1. **クラスターの編集** を選択します。 1. ス**ケジューラ設定**セクションで、**REST API** を **Enabled** に設定します。 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 に保存されているマネージド署名キーを提供します。これは、特定のユーザー ID クレームを含む JWT トークンを生成するために使用されます。 ## 前提条件 Slurm REST API で認証する前に、以下を確認してください。 + **クラスター設定**: Slurm 25.05 以降と REST API が有効になっている AWS PCS クラスター。 + **AWS アクセス許可**: JWT 署名キーの AWS Secrets Manager へのアクセス。 + **ユーザー情報**: クラスターアカウントのユーザー名、POSIX ユーザー ID、および 1 つ以上の POSIX グループ IDs。 + **ネットワークアクセス**: ポート 6820 を許可するセキュリティグループとのクラスターの VPC 内の接続。 ## 手順 **Slurm REST API エンドポイントアドレスを取得するには** ------ #### [ AWS マネジメントコンソール ] 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) で AWS PCS コンソールを開きます。 1. リストからクラスターを選択します。 1. クラスター設定の詳細で、**エンドポイント**セクションを見つけます。 1. **Slurm REST API (slurmrestd)** のプライベート IP アドレスとポートを書き留めます。 1. API コールを行うには、適切にフォーマットされた HTTP リクエストをこのアドレスに送信します。 ------ #### [ 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. API コールを行うには、適切にフォーマットされた HTTP リクエストを に送信します。 `http://:/` ------ **JWT 署名キーを取得するには** 1. [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) で AWS PCS コンソールを開きます。 1. リストからクラスターを選択します。 1. クラスター設定の詳細で、ス**ケジューラ認証**セクションを見つけます。 1. **JSON ウェブトークン (JWT) キー**の ARN とバージョンを書き留めます。 1. を使用して Secrets Manager から署名キー AWS CLI を取得します。 ``` 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 ID プロパティ + `gecos` – ユーザーコメントフィールド。多くの場合、人間が読める名前を保存するために使用されます。 + `dir` – ユーザーのホームディレクトリ + `shell` – ユーザーのデフォルトシェル + `gids` – ユーザーが属する追加の POSIX グループ IDsのリスト 1. Secrets Manager から取得した署名キーを使用して JWT に署名します。 1. トークンの適切な有効期限を設定します。 **注記** `sun` クレームの代わりに、次のいずれかを指定できます。 `username` `userclaimfield` の を介して定義するカスタムフィールド名 `AuthAltParameters Slurm custom settings` `id` クレーム内の`name`フィールド **API リクエストを認証するには** 1. 次のいずれかの方法を使用して、JWT トークンを HTTP リクエストに含めます。 + **ベアラートークン** – `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 生成の例 PCS AWS クラスター JWT 署名キーを取得し、ローカルファイルとして保存します。**aws-region**、**secret-arn**、シー**クレットバージョンの**値を、クラスターに適した値に置き換えます。 ``` #!/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... ``` # PCS でのジョブ管理に Slurm REST API AWS を使用する ## Slurm REST API の概要 Slurm REST API は、HTTP リクエストを通じてクラスター管理関数へのプログラムによるアクセスを提供します。これらの主要な特性を理解することは、PCS で API AWS を効果的に使用するのに役立ちます。 + **アクセスプロトコル**: API は、クラスターのプライベートネットワーク内の通信に HTTP (HTTPS ではなく) を使用します。 + **接続の詳細**: クラスターのプライベート IP アドレスと`slurmrestd`ポート (通常は 6820) を使用して API にアクセスします。完全なベース URL 形式は です`http://:6820`。 + **API バージョニング**: API バージョンは Slurm のインストールに対応します。Slurm 25.05 の場合は、バージョン **v0.0.43** を使用します。バージョン番号は Slurm リリースごとに変わります。現在サポートされている API バージョンは、[Slurm リリースノート](https://slurm.schedmd.com/release_notes.html)に記載されています。 + **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 クラスター。 + **認証**: 適切なユーザー ID クレームを持つ有効な 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/ ``` # PCS での Slurm REST API AWS のよくある質問 このセクションでは、PCS の Slurm REST API に関するよくある質問 AWS に回答します。 **Slurm REST API とは** Slurm REST API は、Slurm ワークロードマネージャーをプログラムで操作できる HTTP インターフェイスです。GET、POST、DELETE などの標準 HTTP メソッドを使用して、クラスターへのコマンドラインアクセスを必要とせずに、ジョブの送信、クラスターのステータスのモニタリング、リソースの管理を行うことができます。 **によって生成されたトークンを使用できますか`scontrol token`?** いいえ。標準`scontrol token`出力は PCS AWS と互換性がありません。PCS Slurm REST API には、username(`sun`)、POSIX ユーザー ID()、グループ IDs(`uid`) を含む特定の ID クレームを含む強化 JWT トークンが必要です`gids`。標準 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 アカウンティングを有効にする必要がありますか?** いいえ。ジョブの送信やモニタリングなどの基本的な REST API オペレーションに Slurm アカウンティングは必要ありません。ただし、`/slurmdb`エンドポイント全体では、アカウンティングをアクティブにする必要があります。 **PCS AWS REST API では、どのようなサードパーティー製ツールを使用できますか?** Slurm Exporter for Prometheus、SlurmWeb、標準 Slurm REST API AWS 形式に従うカスタムアプリケーションなど、既存の Slurm REST API クライアントの多くは PCS と連携する必要があります。ただし、認証`scontrol token`に に依存するツールは、PCS JWT AWS の要件に合わせて変更する必要があります。 **REST API の使用には追加料金がかかりますか?** いいえ。Slurm REST API 機能を有効化または使用しても追加料金はかかりません。通常どおり、基盤となるクラスターリソースに対してのみ料金が発生します。 **REST API のトラブルシューティング方法を教えてください。** + **ネットワーク接続の問題** API エンドポイントに到達できない場合、クラスターコントローラーに HTTP リクエストを行うと、接続タイムアウトまたは「接続拒否」エラーが表示されます。 **対処方法**: クライアントが同じ VPC にあるか、適切なネットワークルーティングがあることを確認し、セキュリティグループがソース IP またはサブネットからの HTTP トラフィックをポート 6820 で許可していることを確認します。 + **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 で指定されたユーザー ID にジョブの作業ディレクトリへの書き込みアクセス許可がない場合、アクセスできないディレクトリで を使用する場合と同様に、ジョブはアクセス許可エラー`sbatch --chdir`で失敗します。 **対処方法**: JWT トークンで指定されたユーザーに、ジョブの作業ディレクトリに対する適切なアクセス許可があることを確認します。