Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Slurm REST API di PCS AWS
AWS PCS menyediakan dukungan terkelola untuk REST API asli Slurm melalui`slurmrestd`, memberikan antarmuka HTTP untuk interaksi cluster terprogram. Anda dapat mengirimkan pekerjaan, memantau status klaster, dan mengelola sumber daya melalui permintaan HTTP standar tanpa memerlukan akses shell langsung ke klaster Anda.
## Kasus penggunaan umum
Slurm REST API mendukung berbagai skenario integrasi:
+ **Integrasi Aplikasi Web**: Membangun frontend kustom dan aplikasi web yang mengirimkan dan mengelola pekerjaan secara langsung.
+ **Integrasi Notebook Jupyter**: Memungkinkan peneliti mengirimkan pekerjaan dari lingkungan notebook tanpa meninggalkan alur kerja pengembangan mereka.
+ **Integrasi Solusi Mitra**: Hubungkan alat HPC pihak ketiga dan manajer alur kerja ke kluster AWS PCS Anda.
+ **Manajemen Cluster Terprogram**: Mengotomatiskan alur kerja pengajuan pekerjaan, pemantauan, dan manajemen sumber daya.
+ **Alur Kerja Komputasi Penelitian**: Mendukung lingkungan penelitian akademis dan perusahaan yang membutuhkan manajemen pekerjaan berbasis API.
## Persyaratan dan pembatasan
Sebelum menggunakan Slurm REST API, tinjau detail berikut:
+ Cluster Anda harus menggunakan Slurm versi 25.05 atau lebih tinggi.
+ Titik akhir API hanya akan dapat diakses melalui alamat IP pribadi dalam VPC klaster Anda.
+ Grup keamanan cluster Anda harus mengizinkan lalu lintas HTTP pada port 6820.
+ Otentikasi membutuhkan token JWT dengan klaim identitas pengguna tertentu.
Keterbatasan saat ini meliputi:
+ Token yang dihasilkan `scontrol token` oleh tidak didukung.
+ `X-SLURM-USER-NAME`peniruan header tidak tersedia.
+ Beberapa fungsi memerlukan akuntansi Slurm untuk diaktifkan.
+ Tidak kompatibel dengan mekanisme plugin filter Slurm CLI.
+ Koneksi ke titik akhir REST API tidak dienkripsi dengan TLS.
**Topics**
+ [Kasus penggunaan umum](#slurm-rest-api-use-cases)
+ [Persyaratan dan pembatasan](#slurm-rest-api-requirements)
+ [Mengaktifkan Slurm REST API di PCS AWS](slurm-rest-api-enable.md)
+ [Mengautentikasi dengan Slurm REST API di PCS AWS](slurm-rest-api-authenticate.md)
+ [Menggunakan Slurm REST API untuk manajemen pekerjaan di PCS AWS](slurm-rest-api-use.md)
+ [Slurm REST API pertanyaan yang sering diajukan di PCS AWS](slurm-rest-api-faq.md)
# Mengaktifkan Slurm REST API di PCS AWS
Aktifkan Slurm REST API untuk mengakses antarmuka HTTP cluster Anda untuk manajemen dan pemantauan pekerjaan terprogram. Anda dapat mengaktifkan fitur ini selama pembuatan klaster atau memperbarui cluster yang ada yang memenuhi persyaratan.
## Prasyarat
Sebelum mengaktifkan Slurm REST API, pastikan Anda memiliki:
+ **Versi cluster**: Slurm versi 25.05 atau lebih tinggi.
+ **Grup keamanan**: Aturan yang memungkinkan lalu lintas HTTP pada port 6820 dari sumber yang Anda inginkan.
## Prosedur
**Untuk mengaktifkan Slurm REST API di cluster baru**
------
#### [ Konsol Manajemen AWS ]
1. Buka konsol AWS PCS di [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/).
1. Pilih **Buat klaster**.
1. Di bawah **detail Cluster**, pilih Slurm versi 25.05 atau lebih tinggi.
1. Konfigurasikan pengaturan cluster lainnya sesuai kebutuhan.
1. Di bagian **konfigurasi Scheduler**, atur **REST API ke** **Enabled**.
1. Konfigurasikan grup keamanan klaster Anda untuk memungkinkan lalu lintas HTTP pada port 6820 dari sumber yang Anda inginkan.
1. Selesaikan proses pembuatan cluster.
------
#### [ AWS CLI ]
1. Tambahkan konfigurasi Slurm REST saat membuat cluster Anda.
```
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. Konfigurasikan grup keamanan klaster Anda untuk memungkinkan lalu lintas HTTP pada port 6820 dari sumber yang Anda inginkan.
------
**Untuk mengaktifkan Slurm REST API pada cluster yang ada**
------
#### [ Konsol Manajemen AWS ]
1. Buka konsol AWS PCS di [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/).
1. Pilih klaster Anda dari daftar.
1. Verifikasi bahwa klaster Anda menggunakan Slurm versi 25.05 atau lebih tinggi dalam detail klaster.
1. Pilih **Edit cluster**.
1. Di bagian **konfigurasi Scheduler**, atur **REST API ke** **Enabled**.
1. Pilih **Perbarui klaster** untuk menerapkan perubahan.
1. Konfigurasikan grup keamanan klaster Anda untuk memungkinkan lalu lintas HTTP pada port 6820 dari sumber yang Anda inginkan.
------
#### [ AWS CLI ]
1. Perbarui cluster Anda dengan konfigurasi Slurm REST, seperti dalam contoh ini.
```
aws pcs update-cluster --cluster-identifier my-cluster \
--slurm-configuration 'slurmRest={mode=STANDARD}'
```
1. Konfigurasikan grup keamanan klaster Anda untuk memungkinkan lalu lintas HTTP pada port 6820 dari sumber yang Anda inginkan.
------
## Apa yang terjadi setelah mengaktifkan
Saat Anda mengaktifkan REST API, AWS PCS secara otomatis:
+ Menghasilkan kunci penandatanganan JWT dan menyimpannya di AWS Secrets Manager.
+ Mengekspos titik akhir API di `https://:6820` dalam VPC Anda.
+ Memperbarui konfigurasi klaster Anda untuk menampilkan detail titik akhir REST API.
Anda sekarang dapat mengautentikasi dan menggunakan REST API untuk manajemen pekerjaan dan operasi klaster.
# Mengautentikasi dengan Slurm REST API di PCS AWS
Slurm REST API di AWS PCS menggunakan otentikasi JSON Web Token (JWT) untuk memastikan akses aman ke sumber daya cluster Anda. AWS PCS menyediakan kunci penandatanganan terkelola yang disimpan di AWS Secrets Manager, yang Anda gunakan untuk menghasilkan token JWT yang berisi klaim identitas pengguna tertentu.
## Prasyarat
Sebelum mengautentikasi dengan Slurm REST API, pastikan Anda memiliki:
+ **Konfigurasi cluster**: Cluster AWS PCS dengan Slurm 25.05\$1 dan REST API diaktifkan.
+ **Izin AWS**: Akses ke AWS Secrets Manager untuk kunci penandatanganan JWT.
+ **Informasi pengguna**: Nama pengguna, ID pengguna POSIX, dan satu atau lebih grup POSIX IDs untuk akun cluster Anda.
+ **Akses jaringan**: Konektivitas dalam VPC cluster Anda dengan grup keamanan yang memungkinkan port 6820.
## Prosedur
**Untuk mengambil alamat titik akhir Slurm REST API**
------
#### [ Konsol Manajemen AWS ]
1. Buka konsol AWS PCS di [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/).
1. Pilih klaster Anda dari daftar.
1. Dalam detail konfigurasi cluster, cari bagian **Endpoints**.
1. Perhatikan alamat IP pribadi dan port untuk **Slurm REST API (slurmrestd**).
1. Anda dapat melakukan panggilan API dengan mengirimkan permintaan HTTP yang diformat dengan benar ke alamat ini.
------
#### [ AWS CLI ]
1. Kueri status klaster Anda dengan`aws pcs get-cluster`. Cari `SLURMRESTD` titik akhir di `endpoints` bidang dalam respons. Inilah contohnya:
```
"endpoints": [
{
"type": "SLURMCTLD",
"privateIpAddress": "192.0.2.1",
"port": "6817"
},
{
"type": "SLURMRESTD",
"privateIpAddress": "192.0.2.1",
"port": "6820"
}
]
```
1. Anda dapat melakukan panggilan API dengan mengirimkan permintaan HTTP yang diformat dengan benar `http://:/`
------
**Untuk mengambil kunci penandatanganan JWT**
1. Buka konsol AWS PCS di [https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/).
1. Pilih klaster Anda dari daftar.
1. Dalam detail konfigurasi cluster, cari bagian **Authentication Scheduler**.
1. Perhatikan **ARN dan versi kunci JSON Web Token (JWT)**.
1. Gunakan tombol AWS CLI untuk mengambil kunci penandatanganan dari Secrets Manager:
```
aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version
```
**Untuk menghasilkan token JWT**
1. Buat JWT dengan klaim wajib berikut:
+ `exp`— Waktu kedaluwarsa dalam hitungan detik sejak 1970 untuk JWT
+ `iat`— Waktu saat ini dalam hitungan detik sejak 1970
+ `sun`— Nama pengguna untuk otentikasi
+ `uid`— ID pengguna POSIX
+ `gid`— ID grup POSIX
+ `id`— Properti identitas POSIX tambahan
+ `gecos`— Kolom komentar pengguna, sering digunakan untuk menyimpan nama yang dapat dibaca manusia
+ `dir`— Direktori home pengguna
+ `shell`— Shell default pengguna
+ `gids`— Daftar grup POSIX tambahan IDs tempat pengguna berada
1. Tanda tangani JWT menggunakan kunci penandatanganan yang diambil dari Secrets Manager.
1. Tetapkan waktu kedaluwarsa yang sesuai untuk token.
**catatan**
Sebagai alternatif untuk `sun` klaim, Anda dapat memberikan salah satu dari yang berikut:
`username`
Nama bidang kustom yang Anda tentukan melalui `userclaimfield` di `AuthAltParameters Slurm custom settings`
`name`Bidang dalam `id` klaim
**Untuk mengautentikasi permintaan API**
1. Sertakan token JWT dalam permintaan HTTP Anda menggunakan salah satu metode berikut:
+ **Token pembawa** - Tambahkan header `Authorization: Bearer `
+ **Slurm header - Tambahkan header** `X-SLURM-USER-TOKEN: `
1. Buat permintaan HTTP ke titik akhir REST API:
Berikut adalah contoh mengakses `/ping` API menggunakan curl dan header. `Authorized: Bearer`
```
curl -X GET -H "Authorization: Bearer " \
http://:6820/slurm/v0.0.43/ping
```
## Contoh generasi JWT
Ambil kunci penandatanganan JWT cluster AWS PCS dan simpan sebagai file lokal. Ganti nilai untuk **aws-region****, secret-arn,** **dan versi rahasia** dengan nilai yang sesuai untuk klaster Anda.
```
#!/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
```
Contoh Python ini menggambarkan cara menggunakan kunci penandatanganan untuk menghasilkan 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)
```
Skrip akan mencetak JWT ke layar.
```
abcdefgtjwttoken...
```
# Menggunakan Slurm REST API untuk manajemen pekerjaan di PCS AWS
## Ikhtisar Slurm REST API
Slurm REST API menyediakan akses terprogram ke fungsi manajemen cluster melalui permintaan HTTP. Memahami karakteristik utama ini akan membantu Anda menggunakan API dengan AWS PCS secara efektif:
+ **Protokol Akses**: API menggunakan HTTP (bukan HTTPS) untuk komunikasi dalam jaringan pribadi cluster Anda.
+ **Detail Koneksi**: Akses API menggunakan alamat IP pribadi klaster Anda dan `slurmrestd` port (biasanya 6820). Format URL dasar lengkap adalah`http://:6820`.
+ **Pembuatan Versi API**: Versi API sesuai dengan instalasi Slurm Anda. **Untuk Slurm 25.05, gunakan versi v0.0.43.** Nomor versi berubah dengan setiap rilis Slurm. Anda dapat menemukan versi API yang saat ini didukung di catatan [rilis Slurm](https://slurm.schedmd.com/release_notes.html).
+ **Struktur URL: Struktur** URL untuk Slurm REST API adalah. `http://://` Informasi penggunaan terperinci untuk endpoint REST API dapat ditemukan di dokumentasi [Slurm](https://slurm.schedmd.com/rest_api.html).
## Prasyarat
Sebelum menggunakan Slurm REST API, pastikan Anda memiliki:
+ **Konfigurasi cluster**: Cluster AWS PCS dengan Slurm 25.05\$1 dan REST API diaktifkan.
+ **Otentikasi**: Token JWT yang valid dengan klaim identitas pengguna yang tepat.
+ **Akses jaringan**: Konektivitas dalam VPC cluster Anda dengan grup keamanan yang memungkinkan port 6820.
## Prosedur
**Untuk mengirimkan pekerjaan menggunakan REST API**
1. Buat permintaan pengiriman pekerjaan dengan parameter yang diperlukan:
```
{
"job": {
"name": "my-job",
"partition": "compute",
"nodes": 1,
"tasks": 1,
"script": "#!/bin/bash\necho 'Hello from Slurm REST API'"
}
}
```
1. Kirim pekerjaan menggunakan permintaan HTTP POST:
```
curl -X POST \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '' \
https://:6820/slurm/v0.0.43/job/submit
```
1. Perhatikan ID pekerjaan yang dikembalikan dalam respons untuk tujuan pemantauan.
**Untuk memantau status pekerjaan**
1. Dapatkan informasi tentang pekerjaan tertentu:
```
curl -X GET -H "Authorization: Bearer " \
https://:6820/slurm/v0.0.43/job/
```
1. Daftar semua pekerjaan untuk pengguna yang diautentikasi:
```
curl -X GET -H "Authorization: Bearer " \
https://:6820/slurm/v0.0.43/jobs
```
**Untuk membatalkan tugas**
+ Kirim permintaan DELETE untuk membatalkan pekerjaan tertentu:
```
curl -X DELETE -H "Authorization: Bearer " \
https://:6820/slurm/v0.0.43/job/
```
# Slurm REST API pertanyaan yang sering diajukan di PCS AWS
Bagian ini menjawab pertanyaan umum tentang Slurm REST API di AWS PCS.
**Apa itu Slurm REST API?**
Slurm REST API adalah antarmuka HTTP yang memungkinkan Anda berinteraksi dengan manajer beban kerja Slurm secara terprogram. Anda dapat menggunakan metode HTTP standar seperti GET, POST, dan DELETE untuk mengirimkan pekerjaan, memantau status klaster, dan mengelola sumber daya tanpa memerlukan akses baris perintah ke cluster.
**Dapatkah saya menggunakan token yang dihasilkan oleh`scontrol token`?**
Tidak, `scontrol token` output standar tidak kompatibel dengan AWS PCS. PCS Slurm REST API memerlukan token JWT yang diperkaya yang berisi klaim identitas spesifik yang mencakup username (`sun`), POSIX user ID (), dan group (`uid`). IDs `gids` Token Slurm standar tidak memiliki klaim yang diperlukan ini dan akan ditolak oleh API.
**Dapatkah saya mengakses API dari luar VPC saya?**
Tidak, titik akhir REST API hanya dapat diakses dari dalam VPC Anda menggunakan alamat IP pribadi pengontrol Slurm. Untuk mengaktifkan akses eksternal, terapkan AWS layanan seperti Application Load Balancer dengan VPC Link, API Gateway, atau buat koneksi VPC peering atau VPN untuk konektivitas yang aman.
**Mengapa API menggunakan HTTP alih-alih HTTPS?**
Slurm REST API dimaksudkan untuk menjadi endpoint internal dalam jaringan pribadi cluster Anda. Untuk penerapan produksi yang memerlukan enkripsi, Anda dapat menerapkan SSL/TLS penghentian pada tingkat yang lebih tinggi dalam arsitektur Anda, seperti melalui gateway API, penyeimbang beban, atau proxy terbalik.
**Bagaimana cara mengontrol akses ke REST API?**
Konfigurasikan aturan grup keamanan klaster Anda untuk membatasi akses ke port 6820 pada pengontrol Slurm. Tetapkan aturan masuk untuk mengizinkan koneksi hanya dari rentang IP tepercaya atau sumber tertentu dalam VPC Anda, memblokir akses tidak sah ke titik akhir API.
**Bagaimana cara memutar kunci penandatanganan JWT?**
Letakkan klaster Anda dalam mode pemeliharaan tanpa instance aktif, lalu mulai rotasi kunci melalui AWS Secrets Manager. Setelah rotasi selesai, aktifkan kembali antrian. Semua token JWT yang ada akan menjadi tidak valid dan harus dibuat ulang menggunakan kunci penandatanganan baru dari Secrets Manager.
**Apakah saya perlu mengaktifkan akuntansi Slurm untuk menggunakan REST API?**
Tidak, akuntansi Slurm tidak diperlukan untuk operasi REST API dasar seperti pengajuan dan pemantauan pekerjaan. Namun, seluruh `/slurmdb` titik akhir membutuhkan akuntansi untuk aktif.
**Alat pihak ketiga apa yang bekerja dengan AWS PCS REST API?**
Banyak klien Slurm REST API yang ada harus bekerja dengan AWS PCS, termasuk Slurm Exporter untuk Prometheus,, dan aplikasi khusus yang mengikuti format API Slurm REST SlurmWeb standar. Namun, alat yang diandalkan `scontrol token` untuk otentikasi akan memerlukan modifikasi untuk bekerja dengan persyaratan AWS PCS JWT.
**Apakah ada biaya tambahan untuk menggunakan REST API?**
Tidak, tidak ada biaya tambahan untuk mengaktifkan atau menggunakan fitur Slurm REST API. Anda hanya membayar sumber daya cluster yang mendasarinya seperti biasa.
**Bagaimana saya bisa memecahkan masalah REST API?**
+ **Masalah konektivitas jaringan**
Jika Anda tidak dapat mencapai titik akhir API, Anda akan melihat batas waktu koneksi atau kesalahan “koneksi ditolak” saat membuat permintaan HTTP ke pengontrol cluster.
**Apa yang harus dilakukan**: Verifikasi klien Anda berada di VPC yang sama atau memiliki perutean jaringan yang tepat, dan konfirmasikan grup keamanan Anda mengizinkan lalu lintas HTTP pada port 6820 dari IP sumber atau subnet Anda.
+ **Masalah otentikasi Slurm REST**
Jika token JWT Anda tidak valid, kedaluwarsa, atau ditandatangani dengan tidak benar, permintaan API akan mengembalikan “Kesalahan otentikasi protokol” di bidang kesalahan respons.
Contoh pesan kesalahan:
```
{
"errors": [
{
"description": "Batch job submission failed",
"error_number": 1007,
"error": "Protocol authentication error",
"source": "slurm_submit_batch_job()"
}
]
}
```
**Apa yang harus dilakukan**: Periksa apakah token JWT Anda diformat dengan benar, tidak kedaluwarsa, dan ditandatangani dengan kunci yang benar dari Secrets Manager. Verifikasi bahwa token telah dibentuk dengan benar dan menyertakan klaim yang diperlukan dan bahwa Anda menggunakan format header otentikasi yang benar.
+ **Job gagal berjalan setelah pengajuan**
Jika token JWT Anda valid tetapi berisi struktur atau konten internal yang salah, pekerjaan mungkin telah memasukkan status jeda (`PD`) dengan kode alasan. `JobAdminHead` Gunakan `scontrol show job ` untuk memeriksa pekerjaan — Anda akan melihat`JobState=PENDING, Reason=JobHeldAdmin`, dan`SystemComment=slurm_cred_create failure, holding job`.
**Apa yang harus dilakukan**: Akar penyebabnya mungkin nilai yang salah di JWT. Verifikasi bahwa token terstruktur dengan benar dan menyertakan klaim yang diperlukan sesuai dokumentasi PCS.
+ **Masalah izin direktori kerja**
Jika identitas pengguna yang ditentukan dalam JWT Anda tidak memiliki izin menulis ke direktori kerja pekerjaan, pekerjaan akan gagal dengan kesalahan izin, mirip dengan menggunakan `sbatch --chdir` dengan direktori yang tidak dapat diakses.
**Apa yang harus dilakukan**: Pastikan pengguna yang ditentukan dalam token JWT Anda memiliki izin yang sesuai untuk direktori kerja pekerjaan.