API Spot Instances

Questa pagina raccoglie gli endpoint API dedicati alle Spot Instances. Per tutte le altre operazioni sui server (elenco, delete, azioni, …) vedi Server.

Autenticazione tramite header X-APITOKEN: <token> — vedi come creare un API Token.

Gli sconti sono frazioni

Tutti i campi di sconto (discount, spot_discount) sono espressi come frazione compresa tra 0 e 1 — ad esempio 0.4 corrisponde al 40%, non a un valore percentuale intero.

Piani spot disponibili

Elenca i piani per cui è attivo uno sconto spot, filtrati in base al provider del profilo utente.

GET /api/v2/plans/spot

Risposta 200 — plan ha la stessa forma di /plans, con in più il campo discount:

{
  "status": "ok",
  "plans": [
    {
      "plan": {
        "id": 17,
        "name": "ECS4",
        "hourly_price": 0.10,
        "montly_price": 72.0,
        "cpu": "4",
        "ram": "8",
        "disk": "80",
        "host_type": "ECS",
        "available_regions": [
          { "id": 3, "location": "it-fr2", "description": "Frosinone" },
          { "id": 5, "location": "it-mi1", "description": "Milano" }
        ]
      },
      "discount": 0.4
    }
  ]
}

Creazione

Per creare una spot è sufficiente aggiungere il campo "spot": true al body della normale creazione server:

POST /api/v2/servers
{
  "plan": "ECS4",
  "image": "ubuntu-22.04",
  "location": "it-fr2",
  "spot": true
}

La risposta è identica a quella di una create on-demand (action_id + server), con il nodo spot valorizzato nell'oggetto server. Vincoli:

spot: true e reserved_plan sono mutuamente esclusivi → 400 (spot and reserved_plan are mutually exclusive);
se per il piano richiesto non esiste uno sconto spot disponibile → errore SpotPlanNotAvailable.

Stato spot

Restituisce lo stato della Spot Instance. Risponde anche dopo la terminazione del server, perché il record di stato sopravvive alla cancellazione.

GET /api/v2/servers/<servername>/spot-status

Risposta 200:

{
  "server": "ec2-abc123",
  "status": "ok",
  "discount": 0.4,
  "notified_at": null,
  "terminate_at": null,
  "promoted_at": null
}

status: ok | terminating | terminated | promoted (vedi Terminazione e preavviso);
notified_at / terminate_at: null finché non parte il reclaim; alla notifica valgono rispettivamente l'istante del preavviso e notified_at + 120s;
promoted_at: null se l'istanza non è mai stata promossa.

Promozione

Promuove la spot a on-demand. Idempotente se l'istanza è già promoted.

PATCH /api/v2/servers/<servername>/spot-status
{
  "status": "promoted"
}

L'endpoint accetta anche PUT. La risposta 200 contiene il record spot aggiornato (stessa forma di Stato spot). Esiti:

Condizione	Esito
istanza `ok`	`200` — promossa
istanza già `promoted`	`200` — nessun effetto (idempotente)
istanza `terminating`	`400` — terminazione già schedulata
istanza `terminated`	`400` — istanza già terminata
il server non è una spot	`404`

Disponibilità

L'endpoint di disponibilità piani espone i campi spot per ogni piano/region:

GET /api/v2/plans/availables

spot_discount — sconto del piano come frazione 0..1, oppure null se il piano non è spot-eligibile;
spot_available — true se in quella region è creabile una spot in questo momento.

Vedi anche Piani.