Desplegar un servidor mediante la API

Un script que despliega sin supervisión necesita más de lo que muestra la Guía rápida: una clave SSH guardada previamente, configuración del primer arranque, esperar al final del despliegue y una forma de leer la operación si falla. En los ejemplos, <api-key> representa tu clave de API y un nombre entre llaves como {serviceId} representa un ID devuelto por un paso anterior.

1. Guardar una clave SSH

Una clave guardada en la organización puede instalarse en cualquier servidor que despliegues. Añadir clave SSH acepta un name y, como publicKey, la línea completa de tu archivo .pub (~/.ssh/id_ed25519.pub, por ejemplo). Se aceptan claves RSA, ED25519 y ECDSA.

curl --request POST \
  --url https://api.serverside.com/v1/organization/ssh-keys \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "laptop",
  "publicKey": "<public-key>"
}
'

La llamada responde 201 con la clave guardada. Conserva su id; Listar claves SSH permite encontrarla después.

2. Obtener el servidor

Elige un plan y un centro de datos con existencias y contrata y paga el servidor como en la Guía rápida, que termina con su ID. Una organización con facturación por hora, indicada como billing.isUsageBased true en Obtener derechos, crea el servicio en una llamada con Crear servicio bare metal. plan acepta el id del plan o su slug y datacenter un código como ams1 o el ID del centro de datos. Genera una vez la clave de idempotencia (sirve la salida de uuidgen) y envía el mismo valor al reintentar, para reconocer una petición repetida tras un error de red como la misma:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "plan": "<plan-id>",
  "datacenter": "<datacenter-code>",
  "name": "web-1"
}
'

La llamada responde 201 con el nuevo servicio y su data.id es el {serviceId} que aceptan las peticiones de despliegue, estado y operación. Un reintento con la misma clave responde 200 con el servidor creado por la primera petición y no crea nada nuevo; la misma clave con otro cuerpo responde 409 IDEMPOTENCY_KEY_REUSED. Una organización sin facturación por hora recibe 422 USAGE_BILLING_DISABLED.

El servidor recibe un IPv4 /30 y un IPv6 /120 salvo que la petición indique otra cosa (Facturación explica los tamaños), y el despliegue del paso 3 necesita la IPv4. bootMode e ipxeScript en el mismo cuerpo inician el servidor con tu propio script iPXE en lugar de una imagen, como explica Scripts iPXE personalizados.

Un plan agotado entre su consulta y el pedido se rechaza con 422 y el código OFFERING_NOT_AVAILABLE, tanto en esta llamada como en un pedido. Si otro pedido toma el último servidor justo después de esa comprobación, esta llamada responde 409 con PROVISIONING_FAILED; vuelve a enumerar los planes antes de reintentar. Un pedido por periodo no reserva un servidor mientras su factura está sin pagar, así que un plan agotado antes del pago deja el pedido pagado en FAILED para que soporte lo aprovisione o reembolse. Una tarjeta rechazada nunca aparece en esta fase. Aparece en el resultado de Pagar factura, al pagarla.

3. Desplegar con configuración del primer arranque

cloudInit acepta un documento cloud-config, ejecutado por cloud-init de la imagen en el primer arranque. Este instala dos paquetes y crea un usuario:

#cloud-config
packages:
  - htop
  - fail2ban
users:
  - name: deploy
    groups: sudo
    shell: /bin/bash

La petición de despliegue lo lleva como una única cadena JSON, con cada salto de línea escrito como \n. image acepta un id o un slug de Listar imágenes de SO; un slug como ubuntu-24.04 elige la primera imagen activa que lo tenga.

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/deploy \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": "<image-slug>",
  "sshKeyIds": [
    "<ssh-key-id>"
  ],
  "raidVariant": "RAID1",
  "cloudInit": "#cloud-config\npackages:\n  - htop\n  - fail2ban\nusers:\n  - name: deploy\n    groups: sudo\n    shell: /bin/bash"
}
'

La llamada responde 201 con la operación iniciada, de type DEPLOYMENT; conserva su id para el paso 5.

cloudInit es para imágenes Linux. Un despliegue Windows acepta el campo y nunca lo lee, y un despliegue de aplicación lo rechaza. En una imagen Linux sin el paquete cloud-init, el despliegue falla en su último paso, después de escribir el disco.

La petición no tiene campo de nombre de host. El sistema instalado toma su nombre del name del servidor: un nombre de host válido o nombre de dominio completo se usa en minúsculas; cualquier otro se convierte en una etiqueta única (minúsculas, los demás caracteres sustituidos por - y máximo 63 caracteres), y un nombre sin nada utilizable se convierte en server- seguido de los primeros ocho caracteres hexadecimales del ID del servicio. Un cambio de nombre surte efecto en el siguiente despliegue.

La API comprueba la petición antes de escribir nada y una petición que incumpla estas reglas se rechaza con 422 VALIDATION_FAILED y un detalle que la identifica:

Otros dos errores responden con estados diferentes. Un applicationMetadata que no sea objeto JSON responde 400 VALIDATION_ERROR con un detalle INVALID_VALUE y una entrada de sshKeyIds que no sea una clave de la organización responde 404 ENTITY_NOT_FOUND. Un servidor sin IPv4 principal se rechaza con 422 PRIMARY_IPV4_REQUIRED antes de las comprobaciones de la tabla. Mientras hay otra operación, cambio de red o reinicio del BMC en curso, la petición responde 409 con OPERATION_IN_PROGRESS, NETWORK_CHANGE_IN_PROGRESS o BMC_RESET_IN_PROGRESS.

4. Esperar a que termine

Mientras se ejecuta una operación, el state del servicio es OPERATION_IN_PROGRESS. Envía Obtener estado del servicio aproximadamente cada 20 segundos hasta que deje de serlo:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/status \
  --header 'Authorization: Bearer <api-key>'

Entre consultas, data.operation.lastProgressMessage indica la fase alcanzada. Cuando cambia el estado, data.lastOperation.state dice cómo terminó: COMPLETED significa que el servidor está instalado. Su dirección es primaryIpv4 en Obtener servicio bare metal y operatingSystem.username es el usuario de acceso: el username de la petición o el defaultUser de la imagen si no se indicó ninguno. Las imágenes Windows siempre crean Administrator con la password de la petición y no aceptan claves SSH.

Para tu primera conexión interactiva, sigue Conectar por RDP para Windows o Conectar por SSH para Linux. Usa la contraseña establecida o la clave SSH elegida durante el despliegue; Serverside.com no conserva tu contraseña de despliegue.

5. Cuando falla un despliegue

Una operación FAILED conserva su rastro. Obtener operación con su id devuelve failureCategory, lastProgressMessage y updates: todos los informes de progreso enviados por el despliegue, cada uno con su hora (at), progress y message. details repite con qué se ejecutó: operatingSystem o application, raidVariant y username.

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/operations/{operationId} \
  --header 'Authorization: Bearer <api-key>'

La propia plataforma establece estas categorías:

Una aplicación cuya instalación falla después de la fase del SO informa SCRIPT_DOWNLOAD_FAILED, SCRIPT_CHECKSUM_MISMATCH o INSTALL_SCRIPT_FAILED: su instalador no pudo descargarse, no coincidía con el hash registrado o terminó con error. El SO sigue instalado y accesible en ese caso y /var/log/cloud-init-output.log del servidor contiene la salida del instalador. Un fallo dentro de la instalación del SO muestra por ahora failureCategory UNKNOWN. lastProgressMessage y los últimos updates permiten entonces distinguir un paso de disco o RAID de una descarga de imagen incompleta.

Puede empezar un nuevo despliegue en cuanto el servicio vuelva a ACTIVE. Si el segundo intento falla en la misma fase, contacta con soporte mediante el formulario de la consola o en tech@serverside.com. El formulario no adjunta el servicio, así que indica el servidor en el mensaje e incluye el id de la operación, su failureCategory y su lastProgressMessage.