Gérer les adresses IP via l’API

Les adresses appartiennent aux blocs d’IP ; chaque appel nomme le bloc et l’adresse dans son chemin : /v1/networking/ip-blocks/{blockId}/addresses/{address}, suivi de l’action.

Pour les instructions de la console et un exemple de partage de bloc, consultez les blocs d’IP publiques.

Trouver un bloc et ses adresses libres

Lister les blocs d’IP renvoie tous les blocs des réseaux de votre organisation avec leur id, networkId, datacenter, ipVersion, cidr, gateway, subnetMask, prefixLength et le nombre d’adresses utilisées et libres :

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

Les blocs propres à un serveur se trouvent sur son réseau d’accès Internet. Lister les réseaux virtuels du service les affiche sous les prefixes de chaque réseau, avec leur id et les adresses du serveur qu’ils contiennent.

Obtenir un bloc d’IP renvoie un bloc avec ses adresses :

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

data.addresses contient une entrée par adresse enregistrée dans le bloc, avec son state (FREE, RESERVED, GATEWAY, ASSIGNED), son nom DNS inverse dans rdns et, sous serviceAssignments, le serviceId et le name de chaque serveur auquel elle est attribuée. data.availableAddresses liste les adresses libres les plus basses, jusqu’à 255. Un bloc qui n’appartient plus à l’un de vos réseaux répond 404.

Réserver une adresse

Réserver une adresse IP retire une adresse libre du pool sans la donner à un serveur. L’appel n’a pas de corps et répond 200 avec l’adresse, désormais 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>'

La réservation et l’attribution sont deux usages distincts d’une adresse, pas deux étapes. Attribuer une adresse réservée est refusé avec 409 IP_ADDRESS_IN_USE ; libérez-la d’abord.

Attribuer une adresse à un serveur

Attribuer une adresse IP lie une adresse à un serveur rattaché au réseau du bloc. L’appel accepte le serviceId et le segmentId du rattachement, indiqué sur la ligne du réseau dans Lister les réseaux virtuels du service :

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 réponse est 200 avec l’adresse, désormais ASSIGNED, et le serveur sous serviceAssignments. La première adresse de chaque famille reçue par un serveur sur un réseau y devient son adresse principale ; un déploiement utilise l’IPv4 principale d’un réseau natif.

Les adresses publiques d’un serveur ne sont pas distribuées par DHCP. Le programme d’installation écrit celles attribuées avant le déploiement dans le système comme configuration statique ; une adresse attribuée ensuite doit être ajoutée manuellement avec le prefixLength et la gateway de Obtenir un bloc d’IP.

Libérer une adresse

Libérer une adresse IP retire l’adresse de tout serveur auquel elle est attribuée, ou termine sa réservation, puis répond 200 avec l’adresse désormais 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>'

La libération supprime son enregistrement DNS inverse. Si l’adresse était principale, l’adresse la plus basse de la même famille encore détenue par le serveur sur ce réseau prend sa place.

Erreurs

La réservation, l’attribution et la libération peuvent répondre :

Définir le DNS inverse

Pour le workflow de la console et les vérifications de résolution, consultez le DNS inverse (rDNS).

Définir le DNS inverse écrit le PTR d’une IPv4 et répond 204. L’API vérifie le nom avant de l’accepter ; créez donc d’abord l’enregistrement direct :

1. Le nom doit être un nom de domaine pleinement qualifié. Un point final est autorisé puis retiré ; le nom est enregistré en minuscules.
2. Le nom doit posséder un enregistrement A, dont au moins un doit être cette adresse. La recherche utilise le résolveur public 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"
}
'

Définissez-le après attribution : attribuer ou réserver une adresse efface tout enregistrement restant ; une adresse non enregistrée dans le bloc répond 404.

Supprimer le DNS inverse retire l’enregistrement et répond 204, même s’il n’y en avait aucun.

IPv6

Les blocs IPv6 utilisent les mêmes appels de réservation, attribution et libération. L’adresse peut utiliser toute forme IPv6, comme 2001:db8::1a, sans crochets ni zone. Les adresses libres d’un bloc IPv6 ne sont pas comptées ; availableAddressCount et availableAddresses valent donc null : choisissez un hôte de son cidr absent de addresses. Le DNS inverse IPv6 n’est pas servi ; les deux appels répondent à une IPv6 avec 422 RDNS_IPV6_UNSUPPORTED.

Ajouter de l’espace d’adressage avec un bloc d’IP

Lorsqu’un bloc est plein, un autre ajoute de l’espace à un réseau public de votre organisation, comme le réseau Internet d’un serveur. Lister les offres de blocs d’IP propose une offre par taille, avec ipVersion, prefixLength et usableAddresses dans specs, le prix par cycle dans pricing et le stock par datacenter dans availability. Le paramètre datacenter limite la liste à un emplacement et accepte un code comme ams1 ou un ID, fournis par Lister les régions.

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

Par période, le bloc est un article IP_BLOCK de Créer une commande, ajouté après paiement de la facture (Facturation). En horaire, Créer un bloc d’IP l’ajoute en une requête. Cela exige billing.isUsageBased à true dans Obtenir les droits, sinon l’appel répond 422 USAGE_BILLING_DISABLED :

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 accepte l’id de l’offre ; networkId nomme le réseau rejoint par le bloc. La réponse est 201 avec le nouveau bloc, dont l’id est le {blockId} des appels d’adresse. La même requête renvoyée avec la même Idempotency-Key ne crée rien et répond 200 avec ce bloc. Un bloc impossible à allouer est refusé avec 409 PROVISIONING_FAILED ; une taille pour laquelle le datacenter n’a pas d’espace donne 422 OFFERING_NOT_AVAILABLE.

Restituer un bloc d’IP

Supprimer un bloc d’IP résilie l’abonnement d’un bloc commandé seul et répond 204 ; Obtenir l’abonnement du bloc d’IP indique cet abonnement.

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

Un bloc sans adresse attribuée est immédiatement libéré. Avec une adresse encore attribuée à un serveur, il est refusé avec 422 TERMINATION_BLOCKED : libérez d’abord ces adresses. Un bloc inclus avec un serveur est facturé sur l’abonnement du serveur ; sa suppression est refusée avec 422 BUNDLED_ITEM_CANCELLATION_BLOCKED. Il est libéré après la suppression du serveur.