Managing IP addresses

Addresses live in IP blocks, and every address call names the block and the address in its path: /v1/networking/ip-blocks/{blockId}/addresses/{address}, followed by the action.

Find a block and its free addresses

List IP blocks returns every block on your organization's networks, each with its id, the networkId it sits on, its datacenter, ipVersion, cidr, gateway, subnetMask and prefixLength, and how many addresses are used and free:

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

A server's own blocks sit on its internet access network. List service virtual networks shows them under each network's prefixes, every one with its id and the server's addresses in it.

Get IP block returns one block with its addresses:

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

data.addresses holds one entry per address the block has on record, with its state (FREE, RESERVED, GATEWAY or ASSIGNED), its reverse DNS name as rdns, and under serviceAssignments the serviceId and name of each server it is assigned to. data.availableAddresses lists the lowest free addresses, up to 255 of them. A block that is no longer on one of your networks answers 404.

Reserve an address

Reserve IP address holds a free address back from the pool without giving it to a server. It takes no body and answers 200 with the address, now 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>'

Reserving and assigning are two different uses of an address, not two steps. Assigning a reserved address is refused with 409 IP_ADDRESS_IN_USE; release it first.

Assign an address to a server

Assign IP address binds an address to a server attached to the block's network. It takes the serviceId and the segmentId the server is attached on, which is on that network's row in List service virtual networks:

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>"
}
'

The answer is 200 with the address, now ASSIGNED, naming the server under serviceAssignments. The first address of each family a server gets on a network becomes its primary one there, and a deployment takes its primary IPv4 address from a native network.

A server's public addresses are not handed out over DHCP. The installer writes the addresses assigned before a deployment into the operating system as static configuration, and an address assigned afterwards has to be added by hand, with the prefixLength and gateway from Get IP block.

Release an address

Release IP address takes an address off any server it is assigned to, or ends its reservation, and answers 200 with the address, now 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>'

Releasing deletes the address's reverse DNS record. When the released address was a server's primary one, the lowest address of the same family that the server still holds on that network takes its place.

Errors

Reserving, assigning and releasing answer these:

Set reverse DNS

Set reverse DNS writes the PTR record for an IPv4 address and answers 204. The API checks the name before it accepts it, so create the forward record first:

1. The name must be a fully qualified domain name. A trailing dot is allowed and dropped, and the name is stored in lower case.
2. The name must have an A record, and one of its A records must be this address. The lookup goes through Cloudflare's public resolver, 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"
}
'

Set it once the address is assigned: assigning or reserving an address clears any record left on it, and an address the block has no record of answers 404.

Delete reverse DNS removes the record and answers 204, also when there was none to remove.

IPv6

IPv6 blocks take the same reserve, assign and release calls. The address may be written in any IPv6 form, such as 2001:db8::1a, without brackets or a zone. An IPv6 block's free addresses are not counted, so its availableAddressCount and availableAddresses are null: pick any host in its cidr that addresses does not list. Reverse DNS is not served for IPv6, and both reverse DNS calls answer an IPv6 address with 422 RDNS_IPV6_UNSUPPORTED.

Add address space with an IP block

When a block runs out, another one adds address space to a public network of your organization, such as a server's internet access network. List IP block plans has one plan per size, its specs giving the ipVersion, prefixLength and usableAddresses, with its price per billing cycle under pricing and its stock per datacenter under availability. The query parameter datacenter narrows the list to one location and takes a code such as ams1 or an id, as List regions gives them.

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

On a term, the block is an IP_BLOCK item of Create order, added once the order's invoice is paid (Billing). On hourly billing, Create IP block adds it in one request. That needs billing.isUsageBased set to true in Get entitlements, and answers 422 USAGE_BILLING_DISABLED without it:

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 takes the plan's id, and networkId names the network the block joins. The answer is 201 with the new block, whose id is the {blockId} of the address calls. The same request sent again with the same Idempotency-Key places nothing new and answers 200 with that block. A block that could not be allocated is refused with 409 PROVISIONING_FAILED, and a size the datacenter has no room for with 422 OFFERING_NOT_AVAILABLE.

Return an IP block

Delete IP block cancels the subscription behind a block ordered on its own and answers 204; Get IP block subscription shows which subscription that is.

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

A block with none of its addresses assigned is released at once. One with an address still assigned to a server is refused with 422 TERMINATION_BLOCKED, so release those addresses first. A block that came with a server is billed on the server's subscription, and deleting it is refused with 422 BUNDLED_ITEM_CANCELLATION_BLOCKED; it is released after the server is deleted.