Gestionar direcciones IP mediante la API

Las direcciones están en bloques de IP y cada llamada de direcciones identifica el bloque y la dirección en su ruta: /v1/networking/ip-blocks/{blockId}/addresses/{address}, seguida de la acción.

Para instrucciones de consola y un ejemplo de bloque compartido, consulta Bloques de IP públicas.

Buscar un bloque y sus direcciones libres

Listar bloques de IP devuelve todos los bloques de las redes de tu organización, cada uno con su id, el networkId donde está, su datacenter, ipVersion, cidr, gateway, subnetMask y prefixLength y cuántas direcciones están usadas y libres:

curl --request GET \
  --url https://api.serverside.com/v1/networking/ip-blocks \
  --header 'Authorization: Bearer <api-key>'

Los bloques propios de un servidor están en su red de acceso a Internet. Listar redes virtuales del servicio los muestra en prefixes de cada red, cada uno con su id y las direcciones del servidor que contiene.

Obtener bloque de IP devuelve un bloque con sus direcciones:

curl --request GET \
  --url https://api.serverside.com/v1/networking/ip-blocks/{blockId} \
  --header 'Authorization: Bearer <api-key>'

data.addresses contiene una entrada por dirección registrada en el bloque, con su state (FREE, RESERVED, GATEWAY o ASSIGNED), su nombre de DNS inverso como rdns y, en serviceAssignments, el serviceId y name de cada servidor al que está asignada. data.availableAddresses enumera las direcciones libres más bajas, hasta 255. Un bloque que ya no está en una de tus redes responde 404.

Reservar una dirección

Reservar dirección IP aparta una dirección libre del conjunto sin dársela a un servidor. No acepta cuerpo y responde 200 con la dirección, ahora RESERVED:

curl --request POST \
  --url https://api.serverside.com/v1/networking/ip-blocks/{blockId}/addresses/198.51.100.27/reserve \
  --header 'Authorization: Bearer <api-key>'

Reservar y asignar son dos usos diferentes de una dirección, no dos pasos. Asignar una dirección reservada se rechaza con 409 IP_ADDRESS_IN_USE; libérala primero.

Asignar una dirección a un servidor

Asignar dirección IP vincula una dirección a un servidor conectado a la red del bloque. Acepta el serviceId y el segmentId por el que se conecta el servidor, que aparece en la fila de esa red en Listar redes virtuales del servicio:

curl --request POST \
  --url https://api.serverside.com/v1/networking/ip-blocks/{blockId}/addresses/198.51.100.26/assign \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceId": "<service-id>",
  "segmentId": "<segment-id>"
}
'

La respuesta es 200 con la dirección, ahora ASSIGNED, indicando el servidor en serviceAssignments. La primera dirección de cada familia que recibe un servidor en una red se convierte en su principal allí y un despliegue toma su IPv4 principal de una red nativa.

Las direcciones públicas de un servidor no se entregan por DHCP. El instalador escribe las asignadas antes del despliegue en el sistema operativo como configuración estática y una dirección asignada después debe añadirse a mano, con el prefixLength y la gateway de Obtener bloque de IP.

Liberar una dirección

Liberar dirección IP retira una dirección de cualquier servidor al que esté asignada o termina su reserva y responde 200 con la dirección, ahora FREE:

curl --request POST \
  --url https://api.serverside.com/v1/networking/ip-blocks/{blockId}/addresses/198.51.100.26/release \
  --header 'Authorization: Bearer <api-key>'

Liberar elimina el registro de DNS inverso de la dirección. Si era la principal de un servidor, la dirección más baja de la misma familia que aún conserva en esa red la sustituye.

Errores

Reservar, asignar y liberar responden con estos errores:

Establecer DNS inverso

Para el flujo de consola y las comprobaciones de búsquedas, consulta DNS inverso (rDNS).

Establecer DNS inverso escribe el registro PTR de una IPv4 y responde 204. La API comprueba el nombre antes de aceptarlo, así que crea primero el registro directo:

1. El nombre debe ser un nombre de dominio completo. Se permite un punto final, que se elimina, y el nombre se guarda en minúsculas.
2. El nombre debe tener un registro A y uno de sus registros A debe ser esta dirección. La búsqueda pasa por el resolutor público de Cloudflare, 1.1.1.1.

curl --request PUT \
  --url https://api.serverside.com/v1/networking/ip-blocks/{blockId}/addresses/198.51.100.26/rdns \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rdns": "mail.example.com"
}
'

Establécelo después de asignar la dirección: asignar o reservar una dirección borra cualquier registro que quedara en ella y una dirección no registrada en el bloque responde 404.

Eliminar DNS inverso elimina el registro y responde 204, también si no había ninguno que eliminar.

IPv6

Los bloques IPv6 aceptan las mismas llamadas de reserva, asignación y liberación. La dirección puede escribirse en cualquier formato IPv6, como 2001:db8::1a, sin corchetes ni zona. No se cuentan las direcciones libres de un bloque IPv6, así que availableAddressCount y availableAddresses son null: elige cualquier host de su cidr que no figure en addresses. No se sirve DNS inverso para IPv6 y ambas llamadas de DNS inverso responden a una dirección IPv6 con 422 RDNS_IPV6_UNSUPPORTED.

Añadir espacio de direcciones con un bloque de IP

Cuando se agota un bloque, otro añade espacio de direcciones a una red pública de tu organización, como la red de acceso a Internet de un servidor. Listar planes de bloques de IP tiene un plan por tamaño, cuyas specs dan ipVersion, prefixLength y usableAddresses, con su precio por ciclo en pricing y existencias por centro de datos en availability. El parámetro de consulta datacenter limita la lista a una ubicación y acepta un código como ams1 o un ID, como los da Listar regiones.

curl --request GET \
  --url https://api.serverside.com/v1/networking/ip-blocks/plans \
  --header 'Authorization: Bearer <api-key>'

Por periodo, el bloque es un elemento IP_BLOCK de Crear pedido, añadido cuando se paga la factura del pedido (Facturación). Con facturación por hora, Crear bloque de IP lo añade en una petición. Esto necesita billing.isUsageBased en true en Obtener derechos y responde 422 USAGE_BILLING_DISABLED si falta:

curl --request POST \
  --url https://api.serverside.com/v1/networking/ip-blocks \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "plan": "<ip-block-plan-id>",
  "datacenter": "ams1",
  "networkId": "<network-id>"
}
'

plan acepta el id del plan y networkId indica la red a la que se une el bloque. La respuesta es 201 con el nuevo bloque, cuyo id es el {blockId} de las llamadas de direcciones. La misma petición reenviada con la misma Idempotency-Key no crea nada y responde 200 con ese bloque. Un bloque que no pudo asignarse se rechaza con 409 PROVISIONING_FAILED y un tamaño para el que no hay espacio en el centro de datos con 422 OFFERING_NOT_AVAILABLE.

Devolver un bloque de IP

Eliminar bloque de IP cancela la suscripción de un bloque contratado por separado y responde 204; Obtener suscripción del bloque de IP muestra cuál es.

curl --request DELETE \
  --url https://api.serverside.com/v1/networking/ip-blocks/{blockId} \
  --header 'Authorization: Bearer <api-key>'

Un bloque sin direcciones asignadas se libera de inmediato. Uno con una dirección aún asignada a un servidor se rechaza con 422 TERMINATION_BLOCKED, así que libera primero esas direcciones. Un bloque incluido con un servidor se factura en la suscripción del servidor y eliminarlo se rechaza con 422 BUNDLED_ITEM_CANCELLATION_BLOCKED; se libera después de eliminar el servidor.