GPUtw 說明文件

執行個體即時狀態

即時資源用量、Pod 狀態、事件、日誌與指令執行。

開啟控制台 API 金鑰

這個章節涵蓋什麼

生命週期端點描述執行個體配置了哪些資源；本章節的端點則描述它正在做什麼——目前的 CPU、GPU、記憶體與網路用量、Pod 健康狀態、近期事件、容器日誌，以及單次指令執行。除另有說明外，皆需要 instances:read，且只能存取同一帳號擁有的執行個體。

讀取單一執行個體

GET/api/instances/{id}

回傳單一執行個體，格式與 GET /api/instances 清單中的項目完全相同。

即時資源用量

GET/api/instances/{id}/resources

在同一個回應中提供配置量、即時用量與計費費率——沒有對照的上限，用量數字無法判讀。百分比是以該執行個體自身的配置量計算，而非整台主機。

範例
curl -H "Authorization: Bearer $GPUTW_API_KEY" https://gputw.ai/api/instances/<instance-id>/resources
Info

每個指標為數值或 null，不會以 0 代替。source 欄位說明樣本來源：prometheus（即時擷取）、fallback（備援輪詢）或 none（無遙測資料），因此可區分「閒置中所以是 0%」與「沒有回報資料」。在沒有 GPU 遙測的機器上，GPU 欄位為 null。

部署期間輪詢狀態

GET/api/instances/{id}/status

回應精簡且成本低，適合在等待機器啟動時以迴圈輪詢。內容包含平台狀態、部署子階段（SCHEDULING、PREPARING、PULLING_IMAGE、STARTING、CONFIG_ERROR、START_FAILED、CRASH_LOOP、RUNNING）、容器本身的階段與就緒狀態、重啟次數，以及失敗時的原因。

範例
curl -H "Authorization: Bearer $GPUTW_API_KEY" https://gputw.ai/api/instances/<instance-id>/status
Tip

請優先使用本端點，而非輪詢完整執行個體清單。大型映像拉取需要數分鐘，deployPhase 可告訴你機器仍在準備、已開始啟動，或卡在值得處理的狀態。PREPARING 涵蓋 kubelet 回報為 ContainerCreating 的所有情形——沙箱建立、儲存掛載與映像拉取在節點外無法區分——因此它並不保證拉取正在進行。

目前執行中的一切

GET/api/instances/active

一次取得所有 DEPLOYING 與 RUNNING 的執行個體，並附上即時 Pod 狀態與目前用量。

事件與日誌

GET/api/instances/{id}/eventsGET/api/instances/{id}/logs

事件以結構化紀錄回傳，而非純文字。日誌支援 ?tail=（最多 2000 行）與 ?previous=1；後者會讀取前一個容器的日誌——發生 crash loop 時，真正的錯誤只會出現在那裡。

範例
curl -H "Authorization: Bearer $GPUTW_API_KEY" "https://gputw.ai/api/instances/<instance-id>/logs?tail=100&previous=1"
Info

事件、日誌與指令輸出在離開伺服器前都會移除基礎設施識別資訊：worker 主機名稱與私有 IP 位址會被替換為佔位字串。

單一執行個體的計費紀錄

GET/api/instances/{id}/runs

依時間由新至舊列出該執行個體的計費區間，各自包含起訖時間、當時的硬體配置與時費率，以及持續時間。帳務明細即由這些紀錄產生。

執行指令

POST/api/instances/{id}/exec

在容器內執行一次指令，回傳 stdout、stderr 與 exitCode。command 為參數陣列，會原樣傳遞而不經過 shell，因此不會被重新切分或展開萬用字元。若需要管線或萬用字元，請自行指定 shell：["sh","-c","..."]。

範例
curl -X POST https://gputw.ai/api/instances/<instance-id>/exec \
  -H "Authorization: Bearer $GPUTW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":["nvidia-smi","--query-gpu=utilization.gpu","--format=csv"]}'
Warning

這等同於在你的執行個體上取得 root shell，需要獨立的 instances:exec 權限，且除了 full 之外的預設組合都不包含它。每次呼叫都會連同指令與結束碼寫入稽核紀錄（不含輸出內容）。執行個體必須為 RUNNING；輸出上限為每個串流 256 KB，指令預設 30 秒逾時（timeoutMs，最長 120 秒）。

重啟容器

POST/api/instances/{id}/pod/restart

原地重建容器，保留映像、連接埠與工作區。需要 instances:manage。

Info

自訂映像的執行個體無法以此方式重啟——registry 憑證會在執行個體停止或失敗時清除，因此重新部署必須指定環境範本或重新提供映像資訊。

從執行個體內部關機

POST/api/instances/self-stop

這是唯一不需要 API 金鑰的執行個體端點。它使用 GPUTW_CONTROL_TOKEN 驗證；該 token 為執行個體專屬，與 GPUTW_API_URL 一併注入每個容器。Token 只能證明是哪一個執行個體在呼叫，無法存取其他執行個體或帳號中的任何其他資源——正因如此，把它放在會執行你自己程式碼的容器內才是安全的。GPUtw 基礎映像已將其包裝為 gputw-shutdown；若自訂映像並非以基礎映像建置，可直接呼叫此端點。

範例
curl -X POST "$GPUTW_API_URL/api/instances/self-stop" \
  -H "Authorization: Bearer $GPUTW_CONTROL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"stop"}'

action可為 stop（預設，保留執行個體紀錄與 /vault）或 terminate（刪除執行個體）。

Info

回應為 202 Accepted，實際關機在回應送出之後才進行。這個順序是刻意的：停止會刪除發出此請求的那個 Pod，先回應才能避免呼叫端把一次其實成功的關機誤判為失敗。對已停止的執行個體送出 stop 會成功且不造成任何變更。

Warning

請直接使用注入的公開 $GPUTW_API_URL。租戶容器禁止對私有網段連線，因此改用私有位址將無法連通。