IP-Adressen über die API verwalten

Adressen befinden sich in IP-Blöcken. Jeder Adressaufruf nennt Block und Adresse im Pfad: /v1/networking/ip-blocks/{blockId}/addresses/{address}, gefolgt von der Aktion.

Konsolenanleitungen und ein Beispiel für gemeinsam genutzte Blöcke finden Sie unter Öffentliche IP-Blöcke.

Block und freie Adressen finden

IP-Blöcke auflisten liefert alle Blöcke in den Netzwerken Ihrer Organisation. Jeder enthält id, die zugehörige networkId, datacenter, ipVersion, cidr, gateway, subnetMask und prefixLength sowie die Anzahl belegter und freier Adressen:

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

Die eigenen Blöcke eines Servers befinden sich in seinem Internetzugangsnetz. Virtuelle Dienstnetzwerke auflisten zeigt sie unter prefixes jedes Netzwerks, jeweils mit id und den darin enthaltenen Serveradressen.

IP-Block abrufen liefert einen Block mit seinen Adressen:

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

data.addresses enthält einen Eintrag pro erfasster Adresse des Blocks mit state (FREE, RESERVED, GATEWAY oder ASSIGNED), Reverse-DNS-Namen als rdns und unter serviceAssignments die serviceId und den name jedes zugewiesenen Servers. data.availableAddresses listet die niedrigsten freien Adressen auf, maximal 255. Ein Block, der nicht mehr zu einem Ihrer Netzwerke gehört, antwortet mit 404.

Adresse reservieren

IP-Adresse reservieren hält eine freie Adresse aus dem Pool zurück, ohne sie einem Server zuzuweisen. Der Aufruf benötigt keinen Body und antwortet mit 200 und der nun als RESERVED markierten Adresse:

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

Reservieren und Zuweisen sind zwei unterschiedliche Verwendungen einer Adresse, keine zwei aufeinanderfolgenden Schritte. Das Zuweisen einer reservierten Adresse wird mit 409 IP_ADDRESS_IN_USE abgelehnt; geben Sie sie zuerst frei.

Adresse einem Server zuweisen

IP-Adresse zuweisen bindet eine Adresse an einen mit dem Netzwerk des Blocks verbundenen Server. Der Aufruf akzeptiert serviceId und die segmentId der Verbindung. Diese steht in der Netzwerkzeile unter Virtuelle Dienstnetzwerke auflisten:

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

Die Antwort ist 200 mit der nun als ASSIGNED markierten Adresse und dem Server unter serviceAssignments. Die erste Adresse jeder Familie, die ein Server in einem Netzwerk erhält, wird dort seine primäre Adresse; eine Bereitstellung übernimmt ihre primäre IPv4-Adresse aus einem nativen Netzwerk.

Öffentliche Serveradressen werden nicht über DHCP vergeben. Das Installationsprogramm schreibt vor einer Bereitstellung zugewiesene Adressen als statische Konfiguration ins Betriebssystem. Später zugewiesene Adressen müssen manuell mit prefixLength und gateway aus IP-Block abrufen ergänzt werden.

Adresse freigeben

IP-Adresse freigeben entfernt eine Adresse von allen zugewiesenen Servern oder beendet ihre Reservierung und antwortet mit 200 und der nun als FREE markierten Adresse:

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

Die Freigabe löscht den Reverse-DNS-Eintrag der Adresse. War sie die primäre Serveradresse, übernimmt die niedrigste Adresse derselben Familie, die der Server noch in diesem Netzwerk hat, deren Platz.

Fehler

Reservieren, Zuweisen und Freigeben liefern diese Antworten:

Reverse DNS setzen

Den Konsolenablauf und Abfrageprüfungen beschreibt Reverse DNS (rDNS).

Reverse DNS setzen schreibt den PTR-Eintrag einer IPv4-Adresse und antwortet mit 204. Die API prüft den Namen vor der Annahme; erstellen Sie deshalb zuerst den Vorwärtseintrag:

1. Der Name muss ein vollständig qualifizierter Domainname sein. Ein abschließender Punkt ist erlaubt und wird entfernt; gespeichert wird der Name in Kleinschreibung.
2. Der Name muss einen A-Eintrag haben, und einer seiner A-Einträge muss diese Adresse sein. Die Abfrage erfolgt über Cloudflares öffentlichen 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"
}
'

Setzen Sie den Eintrag nach der Adresszuweisung: Zuweisen und Reservieren löschen vorhandene Einträge; eine im Block nicht erfasste Adresse antwortet mit 404.

Reverse DNS löschen entfernt den Eintrag und antwortet mit 204, auch wenn keiner vorhanden war.

IPv6

IPv6-Blöcke verwenden dieselben Aufrufe zum Reservieren, Zuweisen und Freigeben. Die Adresse kann in beliebiger IPv6-Schreibweise wie 2001:db8::1a angegeben werden, ohne Klammern oder Zone. Freie Adressen eines IPv6-Blocks werden nicht gezählt; availableAddressCount und availableAddresses sind daher null. Wählen Sie einen beliebigen Host im cidr, den addresses nicht aufführt. Reverse DNS wird für IPv6 nicht bereitgestellt; beide Reverse-DNS-Aufrufe antworten bei IPv6 mit 422 RDNS_IPV6_UNSUPPORTED.

Adressraum mit einem IP-Block erweitern

Ist ein Block erschöpft, erweitert ein weiterer den Adressraum eines öffentlichen Netzwerks Ihrer Organisation, etwa des Internetzugangsnetzes eines Servers. IP-Block-Tarife auflisten enthält einen Tarif pro Größe. Dessen specs geben ipVersion, prefixLength und usableAddresses an, pricing den Preis pro Abrechnungszyklus und availability den Bestand je Rechenzentrum. Der Abfrageparameter datacenter beschränkt die Liste auf einen Standort und akzeptiert einen Code wie ams1 oder eine ID aus Regionen auflisten.

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

Bei einer Laufzeit ist der Block ein IP_BLOCK-Posten von Bestellung erstellen, der nach Bezahlung der Bestellrechnung hinzugefügt wird (Abrechnung). Bei stündlicher Abrechnung fügt IP-Block erstellen ihn in einer Anfrage hinzu. Dafür muss billing.isUsageBased bei Berechtigte Funktionen abrufen true sein; andernfalls lautet die Antwort 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 akzeptiert die id des Tarifs; networkId nennt das Zielnetzwerk des Blocks. Die Antwort ist 201 mit dem neuen Block, dessen id die {blockId} der Adressaufrufe ist. Dieselbe Anfrage mit demselben Idempotency-Key legt nichts Neues an und antwortet mit 200 und diesem Block. Ein nicht zuweisbarer Block wird mit 409 PROVISIONING_FAILED abgelehnt, eine Größe ohne freien Platz im Rechenzentrum mit 422 OFFERING_NOT_AVAILABLE.

IP-Block zurückgeben

IP-Block löschen kündigt das Abonnement eines eigenständig bestellten Blocks und antwortet mit 204; IP-Block-Abonnement abrufen zeigt dieses Abonnement.

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

Ein Block ohne zugewiesene Adressen wird sofort freigegeben. Ist noch eine Adresse einem Server zugewiesen, wird er mit 422 TERMINATION_BLOCKED abgelehnt; geben Sie diese Adressen zuerst frei. Ein mit einem Server gelieferter Block wird über dessen Abonnement abgerechnet; sein Löschen wird mit 422 BUNDLED_ITEM_CANCELLATION_BLOCKED abgelehnt. Er wird nach dem Löschen des Servers freigegeben.