Tutorials Managing floating IPs using the UpCloud API

Managing floating IPs using the UpCloud API

Our SDN enables transferable IP address called a floating IP that can be used to build advanced availability and redundancy. Floating IP is a static public IPv4 address that can be attached to your cloud server. It directs traffic to one server at the time and can be moved between multiple servers in a blink of an eye.

Using the UpCloud API for managing your floating IP addresses allows you to perform all necessary operations programmatically and automate failover. In this guide, we’ll show you how to attach new floating IP addresses, transfer them on request, and delete the IPs once no longer needed.

If you are not yet familiar with the UpCloud API, we would suggest taking a quick look at our guide to getting started with UpCloud API to set up your API user account and access rights.

Attaching a new floating IP

When a new floating IP is created and attached, the target cloud server needs to be shut down.

Begin by shutting down one of the cloud servers you wish to use the floating IP address on. Only one of the servers must be shut down while a new floating IP is being attached.

POST /1.3/server/server_UUID/stop

Replace the IP address highlighted below in red with the floating IP you wish to attach to a new cloud server then enter the MAC address of the network interface on the target. You can find the MAC address in your cloud server details by querying the API with the target UUID.

GET /1.3/server/server_uuid

Then create and attach a new IP address defined by setting the floating property as yes.

POST /1.3/ip_address

{
  "ip_address": {
    "family": "IPv4",
    "mac": "mm:mm:mm:mm:mm:m1",
    "floating": "yes"
  }
}

You will also need to configure the floating IP at the operating system level. You can find instructions at our guides for CentOSDebianUbuntuCoreOS or Windows on how to configure the floating IP on your servers.

Transferring an existing floating IP

The advantage of a floating IP over regular IP addresses is the ability to transfer the IP from one server to another instantaneously. Depending on your use-case, you might wish to move the floating IP address between servers at the time of your choosing or by configuring automation.

Transferring a floating IP address using the UpCloud API is a simple task. While attaching a floating IP for the first time required the target cloud server to be shut down, transferring an existing address also works with running cloud servers.

First, you need to know the network interface MAC address you wish to transfer the floating IP to. You can find the MAC address in your cloud server details, for example, by querying the API with the target server’s UUID.

GET /1.3/server/server_uuid

Then use the following command to transfer the floating IP. Replace the IP address highlighted below in red with the floating IP address you wish to attach to a new cloud server then enter the MAC address of the network interface on the target.

PATCH /1.3/ip_address/0.0.0.0

{
  "ip_address": {
    "mac": "mm:mm:mm:mm:mm:m1"
  }
}

If you haven’t yet used the floating IP on the new cloud server, you will also need to configure the floating IP at the operating system level. You can find instructions at our guides for CentOSDebianUbuntuCoreOS or Windows on how to configure the floating IP on your servers.

It’s also possible to do this directly from the target cloud server if, for example, it notices a failure in the current server the floating IP is pointing to.

#!/bin/bash

# Export your UpCloud credentials to the environmental variables
# export UPCLOUD_USERNAME=username
# export UPCLOUD_PASSWORD=password

# Enter the floating ip address you want to attach
ip=0.0.0.0
# Select the target network interface, commonly eth0
interface=eth0

# API command to transfer the floating IP
curl -u "$UPCLOUD_USERNAME:$UPCLOUD_PASSWORD" -X PATCH \
-H Content-Type:application/json https://api.upcloud.com/1.3/ip_address/$ip \
--data-binary '{"ip_address":{"mac":"'`cat /sys/class/net/$interface/address`'"}}'

Then execute the script whenever you need the floating IP transferred. This allows you to quickly redirect traffic or even automate failover.

Detaching a floating IP

Detaching a floating IP without attaching it to another interface, pass an explicit null or empty string as mac value.

Replace the IP address highlighted below in red with the floating IP you wish to detach.

PATCH /1.3/ip_address/0.0.0.0

{
  "ip_address": {
    "mac": null
  }
}

Detaching a floating IP allows you to retain the IP address even if you wish to delete the servers it was used on. You might also wish to detach a floating IP while in use to stop traffic to the address in case of e.g. DDoS attack.

Deleting a floating IP

Delete any IP address using the following command. Note that the deletion is permanent and cannot be reverted.

Replace the IP address highlighted below in red with the floating IP you wish to delete.

DELETE /1.3/ip_address/0.0.0.0

If you do delete an IP address by mistake, immediately attaching a new IP of the same type may give you the same IP that was just released if it has not been attached anywhere else.

Leave a Reply

Your email address will not be published. Required fields are marked *

Locations

Helsinki (HQ)

In the capital city of Finland, you will find our headquarters, and our first data centre. This is where we handle most of our development and innovation.

London

London was our second office to open, and a important step in introducing UpCloud to the world. Here our amazing staff can help you with both sales and support, in addition to host tons of interesting meetups.

Singapore

Singapore was our 3rd office to be opened, and enjoys one of most engaged and fastest growing user bases we have ever seen.

Seattle

Seattle is our 4th and latest office to be opened, and our way to reach out across the pond to our many users in the Americas.