Server

I server virtuali sono il nucleo dei servizi ECS. Questa pagina elenca tutte le operazioni disponibili sui server.

Creare un nuovo server

Sono necessarie pochissime informazioni per creare un server di base, hai solo bisogno di:

• Un Piano
• Un'Immagine o un Template
• Una Regione o Location
• Un'Etichetta

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server"
}

Risposta HTTP

{
  "status": "ok",
  "action": 35,
  "server": {
    "name": "ec200001",
    "ipv4": "",
    "ipv6": "",
    "plan": "ECS6",
    "location": "it-fr2",
    "os": "debian-12",
    "status": "Booting",
    "progress": 10
    ...
  }
}

Puoi monitorare lo stato dell'Azione di creazione per sapere quando un server è pronto o se l'operazione sia fallita.

Attenzione

La creazione del server può facilmente fallire per mancanza di risorse, per evitare questo comportamento si raccomanda di verificare la disponibilità del Piano prima di tentare di creare un server in un determinato data center.

Elenca tutti i server

Per elencare tutti i tuoi server puoi facilmente utilizzare il seguente endpoint:

Richiesta HTTP

GET /ecs/v2/servers

Risposta HTTP

{
    "status": "ok",
    "count":5,
    "server":[
        {
            "name": "ec200001",
            "ipv4": "127.0.0.1",
            "ipv6": "fe80::1",
            "group": "eg100001",
            "plan": "ECS6",
            "plan_size": {
                "core": 12,
                "ram": 24576,
                "disk": 400,
                "gpu": 0,
                "gpu_label": "",
                "host_type": "ECS"
            },
            "reserved_plans": [],
            "is_reserved": false,
            "reserved_until": "",
            "support": null,
            "location": "it-fr2",
            "location_label": "frosinone",
            "notes": "my-server",
            "so": "debian-12",
            "so_label": "Debian 12",
            "creation_date": "2024-10-10 12:00...",
            "deletion_date": null,
            "active_flag": true,
            "status": "Booted",
            "progress": 100,
            "api_version": "v4",
            "user": "eCS99999",
        },
        ...
    ]
}

Ottenere un server specifico

Per ottenere solo un server specifico, puoi aggiungere il nome del server all'URL come segue:

Richiesta HTTP

GET /ecs/v2/servers/{servername}

Risposta HTTP

{
    "status": "ok",
    "server": {
        "name": "ec200001",
        "ipv4": "127.0.0.1",
        "ipv6": "fe80::1",
        "group": "eg100001",
        "plan": "ECS6",
        "plan_size": {
            "core": 12,
            "ram": 24576,
            "disk": 400,
            "gpu": 0,
            "gpu_label": "",
            "host_type": "ECS"
        },
        "reserved_plans": [],
        "is_reserved": false,
        "reserved_until": "",
        "support": null,
        "location": "it-fr2",
        "location_label": "frosinone",
        "notes": "my-server",
        "so": "debian-12",
        "so_label": "Debian 12",
        "creation_date": "2024-10-10 12:00...",
        "deletion_date": null,
        "active_flag": true,
        "status": "Booted",
        "progress": 100,
        "api_version": "v4",
        "user": "eCS99999",
    }
}

Cambiare etichetta del server

Se vuoi cambiare un'etichetta per un server specifico, puoi usare la seguente richiesta:

Richiesta HTTP

PUT /ecs/v2/servers/{servername}
{
  "note": "my-new-server-label"
}

Risposta HTTP

{
  "status": "ok"
}

Periodo riservato

Sottoscrivere un periodo riservato è una buona scelta se affronti sfide che richiedono alta intensità lavorativa per periodi medio-lunghi.

Facendo così, puoi ricevere significativi sconti basati sulla durata del periodo disabilitando la possibilità di distruggere il server.

Aggiungere un Periodo Riservato durante la creazione

Per sottoscrivere un Periodo Riservato Durante la Creazione del Server, puoi aggiungere il campo "reserved_plan" nella tua richiesta come segue:

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server",
  "reserved_plan": "M24PECS6"
}

Il campo reserved_plan è composto da:

M{durata del piano}P{Nome del piano}

dove la durata del piano può essere 3, 6 o 12 mesi

Aggiungere un Periodo Riservato su a un server già esistente

Per aggiungere un Periodo Riservato su a un server già esistente, è necessario utilizzare la seguente richiesta:

Richiesta HTTP

POST /api/v2/servers/{servername}/reserved
{
  "reserved_plan": "M24PECS6"
}

Risposta HTTP

{
  "reserved_plan": 50,
  "reserved_month": 24,
  "plan": 7,
  "discount": 20,
  "start_date": "2024-10-10 12:34...",
  "end_date": "2026-10-10 12:34...",
  "server": "ec200001"
}

Puoi ricevere i seguenti errori:

Status Code	Messaggio	Spiegazione
400	Formula non valida per definire il piano riservato: usare id o MxxPxxxx (M12PECS1)	Hai provato a selezionare un piano riservato senza usare l'id del piano o la formula del piano riservato
404	Piano riservato non trovato	Formula giusta ma nessun piano trovato
400	Non è possibile aggiungere un piano riservato a un server con un piano risorse diverso	Il Piano Riservato inserito è disponibile solo per un piano risorse diverso
400	Argomento 'reserved_plan' richiesto	Campo 'reserved_plan' mancante nel corpo json
400	I piani riservati non sono disponibili per il tuo profilo	Il tuo account non è autorizzato a utilizzare il Piano Riservato

Supporto

Scegliere un piano di supporto per il tuo server ti permette di ricevere aiuto direttamente dai nostri ingegneri esperti; sono disponibili diversi piani di supporto, per maggiori informazioni puoi consultare il nostro sito.

Aggiungere un piano di supporto durante la creazione

Per aggiungere un Piano di Supporto Durante la Creazione del Server, puoi aggiungere il campo "support" nella tua richiesta come segue:

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server",
  "support": "global"
}

Il campo "support" può essere: "basic" o "global.".

Per attivare un supporto "proattivo", ti consigliamo di visitare il nostro sito e contattare i nostri uffici.

Aggiungere un piano di supporto a un server già esistente

Per aggiungere o modificare un Piano di Supporto a un server già esistente, puoi usare la seguente richiesta:

Richiesta HTTP

POST /ecs/v2/servers/{server-name}/support
{
  "code": "global"
}

Risposta HTTP

{
  "status": "ok",
  "support": {
    "support_title": "global",
    "support_code": "global",
    "immutable": false,             //se è forzato a non cambiare
    "start": "2024-10-10 17:03...",
    "start": null,
    "may_downgrade": false,         //se il piano può essere declassato
    "weigth": 2,                    //il peso del piano è usato per conoscere la relazione tra downgrade e upgrade
    "days": 30,                     //durata
    "cancelled": false,
    "cancelled_at": null,
  } 
}

Puoi anche usare questo endpoint per aggiornare o declassare il tuo piano di supporto.

Puoi ricevere i seguenti errori:

Status Code	Messaggio	Spiegazione
400	Non è possibile modificare un piano di supporto immutabile	Se il tuo piano di supporto è immutabile non puoi declassarlo
400	Codice di supporto non trovato	Codice di supporto non trovato, prova un altro
400	Non è possibile declassare un piano di supporto, piano non ancora terminato...	Puoi declassare il piano di supporto solo dopo che è terminato

Rimuovere un piano di supporto

Per rimuovere un piano di supporto (e impostare il supporto unmanaged), è sufficiente utilizzare la seguente richiesta:

Richiesta HTTP

DELETE /ecs/v2/servers/{server-name}/support

Risposta HTTP

{
  "status": "ok"
}

Puoi ricevere i seguenti errori:

Status Code	Messaggio	Spiegazione
400	Non è possibile modificare un piano di supporto immutabile	Se il tuo piano di supporto è immutabile non puoi declassarlo
400	Non è possibile declassare un piano di supporto, piano non ancora terminato...	Puoi declassare il piano di supporto solo dopo che è terminato

Gruppi

I gruppi ti permettono di avere una visione suddivisa dei tuoi server tramite il pannello web Ermes, possono anche essere configurati tramite i seguenti endpoint API:

Info

Per ulteriori informazioni sulla creazione di gruppi, consulta la Pagina del Gruppo.

Aggiungere un Server a un Gruppo durante la creazione

Per aggiungere il tuo server a un gruppo durante la creazione, puoi usare il campo "group":

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server",
  "group": "eg-000001"
}

Aggiungere un Server già esistente a un Gruppo

Per aggiungere un server già esistente a un gruppo, puoi usare l'endpoint di gestione del server:

Richiesta HTTP

PUT /ecs/v2/servers/{servername}
{
  "group": "eg-000001"
}

Risposta HTTP

{
  "status": "ok"
}

Puoi ricevere i seguenti errori:

Status Code	Messaggio	Spiegazione
404	gruppo non trovato	Impossibile trovare il gruppo richiesto

Rimuovere un Server da un Gruppo

Per rimuovere un server da un gruppo, usa la seguente richiesta:

Richiesta HTTP

PUT /ecs/v2/servers/{servername}
{
  "group": "nogroup"
}

Risposta HTTP

{
  "status": "ok"
}

Cloud Script

Il Cloud Script è una funzionalità molto potente che ti permette di eseguire uno script remoto durante l'installazione del server, per maggiori informazioni sul Cloud Script vai alla Pagina Cloud Script.

Puoi utilizzare un Cloud Script durante la creazione del server è possibile usare uno Script Temporaneo o uno script già esistente dalla tua libreria.

L' uso della libreria di script è fortemente consigliato, specialmente per l'utilizzo via API.

Script Temporaneo

Utilizzare uno Script Temporaneo o "otf" significa inviare tutto il contenuto dello script durante la richiesta di creazione del server:

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server",
  "user_customize": "#!/bin/bash\necho \"il mio script\" > /root/out.txt"
}

Libreria di Script e variabili di ambiente

Utilizzare la Libreria di Script richiede che un Cloud Script sia già scritto nella tua Libreria di Script;.

Potrà poi essere richiamato durante la creazione:

Prendiamo, per esempio, il seguente Script con id 2:

#!/bin/bash

echo "i'm $NAME, i work in $WORK !!!" > /root/presentation.txt

Puoi utilizzarlo tramite:

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server",
  "user_customize": 2,           // codice dello script
  "user_customize_env": "NAME=\"bob\"\nWORK=\"seeweb\""
}

Le variabili di ambiente (user_customize_env) permettono di scrivere il contenuto dello script e modificare solo i valori necessari, inoltre, sono trattate come informazioni sensibili e oscurate in quanto tali.

Le variabili di ambiente devono seguire questa sintassi per funzionare: "VARNAME1=VARCONTENT1\nVARNAME2=VARCONTENT2...".

Puoi ricevere i seguenti errori:

Status Code	Messaggio	Spiegazione
400	lo script powershell non può essere usato nei server linux	puoi usare solo script powershell con server windows
400	Formato delle variabili env non valido	controlla il campo 'user_customize_env', ricorda di usare '\n'
400	Impossibile utilizzare il percorso relativo nello script utente	i percorsi relativi e i percorsi home es: '~/' non sono supportati

Utilizzare le Chiavi SSH

Per utilizzare l'autenticazione tramite Chiavi SSH via API, devi prima registrare la tua chiave SSH pubblica e utilizzarla tramite il seguente campo durante la creazione del server:

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server",
  "ssh_key": "my-key-label"
}

Aggiungere una Rete durante la creazione

Le reti sono una funzionalità estremamente utili che introduce il discorso networking sui prodotti ecs. Per creare e gestire le reti è possibile consultare Le reti.

Per aggiungere delle reti durante la creazione è sufficiente utilizzare il campo 'networks' durante la creazione del server:

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-first-server",
  "networks": [
    {
        "name": "net000015",          //nome della rete
        "vlans": [                    //lista delle vlan
            {
                "vlan_id": 100,       //vlan singola
                "pvid": true          //se la vlan è pvid
            },
            {
                "vlans": "1-99"       //intervallo di vlan
            },
            {
                "vlans": "150-200"
            }
        ]
    }
  ]
}

Isolamento

L'isolamento è una funzionalità molto interessante che ti permette di isolare le risorse hardware fisiche tra due server nello stesso datacenter.

In tal modo si può garantire la sicurezza di molteplici istanze a livello di risorsa fisica.

Impostare L'isolamento

Puoi isolare un server aggiungendo il seguente campo durante la sua creazione:

Richiesta HTTP

POST /ecs/v2/servers
{
  "plan": "ECS6",
  "image": "debian-12",
  "location": "it-fr2",
  "notes": "my-isolated-server",
  "isolate_from": [
    "ecs000001",
    "ecs000002"
  ]
}

Questo forza il nuovo server a partire su un host fisico diverso da ecs000001 e ec000002.

Ottenere tutti gli isolamenti di un server

Per ottenere tutte gli isolamenti attivi per un server è possibile utilizzare la seguente richiesta:

Richiesta HTTP

/ecs/v2/servers/{servername}/isolations

Risposta HTTP

{
  "status": "ok",
  "isolations": [
    {
      "name": "ec000001",
      "notes": "my-isolated-server"
    },
    {
      "name": "ec000002",
      "notes": "my-faboulus-isolated-server"
    }
  ]
}

Ottenere lo stato del server

Per ottenere lo stato di funzionamento del server, puoi utilizzare il seguente endpoint:

Richiesta HTTP

GET /ecs/v2/servers/{servername}/status

Risposta HTTP

{
  "status": "ok",
  "server": {
    "name": "ec000001",
    "current_status": "Running"
  }
}

puoi ricevere i seguenti errori:

Status Code	Messaggio	Spiegazione
400	Impossibile recuperare lo stato del server	Lo stato del server è esportato dal tool libvirt exporter quindi possono verificarsi errori nel recuperlo

Metriche

Il servizio ECS esporta diverse informazioni sulle prestazioni e le metriche del tuo server, puoi ottenere i consumi di CPU, Disco e Rete tramite il seguente endpoint:

Richiesta HTTP

GET /ecs/v2/servers/{servername}/metrics

Risposta HTTP

{
  "metrics": {
    "resource": "ec000001",
    "core": [
      {
        "t": "2024-10-17 08:25:58",
        "y": "0.00"
      },
      {
        "t": "2024-10-17 08:30:58",
        "y": "0.00"
      },
     ...
    ],
    "disk": {
      "reads": [
        {
          "t": "2024-10-17 08:35:58",
          "y": "28.45"
        },
        {
          "t": "2024-10-17 08:40:58",
          "y": "0.00"
        },
        ...
      ],
      "writes": [
        {
          "t": "2024-10-17 08:35:58",
          "y": "2.37"
        },
        {
          "t": "2024-10-17 08:40:58",
          "y": "0.00"
        },
        ...
      ]
    },
    "network": {
      "received": [
        {
          "t": "2024-10-17 08:35:58",
          "y": "0.00"
        },
        {
          "t": "2024-10-17 08:40:58",
          "y": "0.00"
        },
        ...
      ],
      "transmitted": [
        {
          "t": "2024-10-17 08:35:58",
          "y": "0.00"
        },
        {
          "t": "2024-10-17 08:40:58",
          "y": "0.00"
        },
        ...
      ]
    }
  }
}

Distruggere un Server

Per distruggere un Server è disponibile la seguente richiesta:

Richiesta HTTP

DELETE /ecs/v2/servers/{servername}

Risposta HTTP

{
  "status": "ok",
  "action": {
    "id": 39,
    "status": "in-progress",
    "user": "foo",
    "created_at": "2019-04-30T16:33:03.317800+00:00",
    "started_at": "2019-04-30T16:33:03.317019+00:00",
    "completed_at": null,
    "resource": "ec200016",
    "resource_type": "ECS",
    "type": "delete_server",
    "progress": 0
  }
}