Alimentación y acceso remoto mediante la API

Estas llamadas se comunican con el controlador de gestión del servidor, por lo que funcionan con el sistema operativo detenido y devuelven el estado de alimentación y las lecturas de sensores con el servidor apagado. Las llamadas propias del servidor están en /v1/baremetal/{serviceId}; la biblioteca ISO está en /v1/assets/isos.

Alimentación

El estado de alimentación es powerState en Obtener estado del servicio: ON, OFF, UNKNOWN o BMC_RESETTING. UNKNOWN significa que el controlador de gestión no respondió o que el servidor no tiene uno. El esquema también enumera PENDING, que esta llamada nunca devuelve.

Enviar comando de alimentación acepta un command obligatorio:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/power \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "GRACEFUL_RESTART"
}
'

La llamada responde 204 sin cuerpo y cualquier otro valor de command responde 400 VALIDATION_ERROR. Un comando ordenado depende de que el sistema operativo responda. Un servidor que sigue ON tras GRACEFUL_SHUTDOWN tiene un SO que no actuó ante la petición y el siguiente paso es FORCE_OFF.

Un comando de alimentación se rechaza con:

Lecturas de hardware

Tres llamadas de solo lectura informan de lo que mide el controlador en un servidor cuyo hardware.capabilities enumera la entrada METRICS_* correspondiente; en los demás responden 422 OPERATION_NOT_SUPPORTED_PLATFORM:

• Obtener estado de PSU (METRICS_PSU) enumera cada fuente de alimentación con su lineInputVoltage, powerInputWatts y status.
• Obtener datos térmicos (METRICS_THERMALS) devuelve temperatures, cada una con readingCelsius y sus umbrales críticos, y fans, cada uno con un reading en sus readingUnits.
• Obtener métricas de alimentación (METRICS_POWER) da el consumo actual como powerConsumedWatts y, en powerMetrics, el consumo mínimo, máximo y medio de los últimos intervalInMin minutos.

Cada status de las dos primeras es un par: el state del componente, como ENABLED o ABSENT, y su health, que es OK, WARNING, CRITICAL o UNKNOWN.

Si empiezan a agotar el tiempo de espera o no se abre una sesión de consola, Reiniciar BMC reinicia el controlador de gestión sin afectar al servidor en ejecución. Responde 204 y powerState muestra BMC_RESETTING hasta que vuelve el controlador. Mientras tanto, los comandos de alimentación, operaciones, sesiones de consola y medios virtuales responden 409 BMC_RESET_IN_PROGRESS.

Sesiones de consola

Una sesión de consola abre la pantalla y el teclado del servidor en tu navegador, en un servidor cuyas hardware.capabilities incluyan KVM o IPMI; en los demás responde 422 OPERATION_NOT_SUPPORTED_PLATFORM. La sesión es un reenvío de puerto al controlador de gestión que solo acepta conexiones desde la dirección indicada en clientIpAddress y se cierra tras timeoutSeconds, de 3600 a 86.400 (1 a 24 horas).

Indica la dirección pública, IPv4 o IPv6, del equipo desde el que abrirás la consola. Detrás de un router NAT es la dirección pública del router, que muestra una web de consulta de IP o la página de estado del router. Abre una sesión de consola con ella:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/console-sessions \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientIpAddress": "<your-ip>",
  "timeoutSeconds": 7200
}
'

La llamada responde 201 con la url que abrir, el forwardId, startedAt y expiresAt de la sesión. En un servidor cuyas capacidades enumeren IPMI también incluye ipmiUsername e ipmiPassword para la página de acceso del controlador; en uno que enumere KVM (Dell iDRAC9 e iDRAC10, Supermicro Gen12), ambos son null. Una segunda petición mientras la primera sigue configurándose responde 409 KVM_SESSION_REQUEST_IN_PROGRESS; reintenta tras Retry-After (10 segundos). Una sesión nueva desde la misma dirección reutiliza el forwardId de la abierta y su expiresAt sustituye al anterior.

Listar sesiones de consola muestra las sesiones abiertas de tu organización, cada una con su url, clientIpAddress, timeoutSeconds y expiresAt. Para cerrar una antes del tiempo límite, pasa su forwardId a Cerrar sesión de consola; la llamada responde 204, también para una sesión ya cerrada:

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

Una sesión abierta desde un equipo con una dirección pública distinta de la permitida no conecta. Abre una nueva con la dirección correcta en lugar de ampliar la anterior.

Medios virtuales

Los medios virtuales conectan un archivo ISO al servidor como unidad para arrancar un instalador o sistema de rescate que no ofrece la lista de imágenes. Funcionan en servidores cuyas hardware.capabilities incluyan VIRTUAL_MEDIA; las máquinas Supermicro Gen11 y ASRock responden a un montaje con 422 y OPERATION_NOT_SUPPORTED_PLATFORM. La ISO debe estar primero en tu biblioteca.

Subir una ISO

La subida requiere tres llamadas y el archivo va directamente al almacenamiento en lugar de pasar por la API:

1. Iniciar subida de ISO con un displayName de 3 a 64 caracteres y el sizeBytes exacto del archivo (máximo 20.971.520.000 bytes, que son 2.000 partes). Responde 201 con el id de la ISO, totalParts y una entrada uploadUrls prefirmada por parte.
2. Divide el archivo en partes de 10 MiB (10.485.760 bytes; la última es lo que quede) y envía PUT de la parte n a la URL n. Las URL caducan dos horas después de emitirse.
3. Completar subida de ISO. Cuando las partes suman el tamaño declarado, responde 200 con el archivo ISO y su isReady pasa a true ahí y en Listar ISO. Si las partes no alcanzan el tamaño, responde 422 ISO_UPLOAD_INCOMPLETE y una interrupción del almacenamiento responde 503 UPSTREAM_UNAVAILABLE.

stat -c %s installer.iso imprime el tamaño que enviar (stat -f %z en macOS):

curl --request POST \
  --url https://api.serverside.com/v1/assets/isos \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "rescue",
  "sizeBytes": 734003200
}
'

Con la respuesta guardada como upload.json, este bucle de shell divide el archivo y envía cada parte a su URL:

split -b 10485760 -d -a 4 installer.iso part-
i=0
for url in $(jq -r '.data.uploadUrls[]' upload.json); do
  curl -s -X PUT --upload-file "part-$(printf '%04d' $i)" "$url"
  i=$((i + 1))
done

split -d es el formato GNU; en macOS usa gsplit. Después completa la subida con el id de la ISO:

curl --request POST \
  --url https://api.serverside.com/v1/assets/isos/{isoId}/complete-upload \
  --header 'Authorization: Bearer <api-key>'

El número de ISO que puede tener una organización es baremetal.maxIsoFiles en Obtener derechos, donde null significa sin límite. Las subidas nunca completadas cuentan y, cuando la organización tiene más archivos que el límite, una subida nueva responde 422 ISO_LIMIT_REACHED. Eliminar ISO libera una plaza; una ISO montada no puede eliminarse (409 ENTITY_IN_USE).

Montarla

Montar medios virtuales acepta el ID de la ISO como isoFileId y expirySeconds entre 1800 y 43.200 (30 minutos a 12 horas). Una ISO cuya subida no ha terminado se rechaza con 422 ISO_UPLOAD_INCOMPLETE.

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/virtual-media \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "isoFileId": "<iso-id>",
  "expirySeconds": 3600,
  "isOneTimeBoot": true
}
'

La llamada responde 201 con el deviceIndex, isoFileId y expiresAt del montaje. Con isOneTimeBoot en true, la misma llamada arranca el servidor desde la ISO una vez: enciende uno detenido y reinicia uno en marcha de inmediato, sin pedir al SO que se apague. Observa el instalador mediante una sesión de consola. Sin ello, la ISO se conecta como unidad y el orden de arranque permanece igual.

Un servidor tiene un montaje a la vez y uno nuevo sustituye al anterior. Listar medios virtuales lo muestra y Listar ISO de un servicio marca el archivo montado con isMounted, mountExpiresAt y deviceIndex. Expulsar medios virtuales lo desconecta antes de caducar y responde 204; un índice sin nada montado expulsa el montaje registrado.