{"id":2212,"date":"2019-09-23T13:06:16","date_gmt":"2019-09-23T10:06:16","guid":{"rendered":"https:\/\/upcloud.com\/global\/us\/resources\/tutorials\/managing-floating-ips-upcloud-api\/"},"modified":"2019-09-23T13:06:16","modified_gmt":"2019-09-23T10:06:16","slug":"managing-floating-ips-upcloud-api","status":"publish","type":"tutorial","link":"https:\/\/upcloud.com\/global\/resources\/tutorials\/managing-floating-ips-upcloud-api\/","title":{"rendered":"Managing floating IPs using the UpCloud API"},"content":{"rendered":"\n

Our SDN<\/a> enables a transferable IP address called a\u00a0floating 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 a time and can be moved between multiple\u00a0servers in a blink of an eye.<\/p>\n\n\n\n

Using the UpCloud API to manage your floating IP addresses allows you to perform all necessary operations programmatically and automate failover. In this guide, we\u2019ll show you how to attach new floating IP addresses, transfer them on request, and delete the IPs once they are no longer needed.<\/p>\n\n\n\n

If you are not yet familiar with the UpCloud API, we would suggest taking a quick look at our guide to\u00a0getting started with UpCloud API<\/a>\u00a0to set up your API user account and access rights.<\/p>\n\n\n\n

\n
Test hosting on UpCloud!<\/a><\/div>\n<\/div>\n\n\n\n

Attaching a new floating IP<\/h2>\n\n\n\n

When a new floating IP is created and attached, the target cloud server needs to be shut down.<\/p>\n\n\n\n

Begin by shutting down one of the cloud servers on which you wish to use the floating IP address. Only one of the servers must be shut down while a new floating IP is attached.<\/p>\n\n\n\n

POST \/1.3\/server\/server_UUID<\/span>\/stop<\/pre>\n\n\n\n
Replace the IP address highlighted below in red<\/span> with the floating IP you wish to attach to a new cloud server, and 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.<\/p>\n\n\n\n
GET \/1.3\/server\/server_uuid<\/span><\/pre>\n\n\n\n
Then, create and attach a new IP address defined by setting the floating property to yes<\/tt>.<\/p>\n\n\n\n
POST \/1.3\/ip_address\n\n{\n  \"ip_address\": {\n    \"family\": \"IPv4\",\n    \"mac\": \"mm:mm:mm:mm:mm:m1<\/span>\",\n    \"floating\": \"yes\"\n  }\n}<\/pre>\n\n\n\n
You must also configure the floating IP at the operating system level.\u00a0You can find instructions in our guides for\u00a0CentOS<\/a>,\u00a0Debian<\/a>,\u00a0Ubuntu<\/a>,\u00a0CoreOS<\/a>\u00a0or\u00a0Windows<\/a>\u00a0on how to configure\u00a0the floating IP on your servers.<\/p>\n\n\n\n
Transferring an existing floating IP<\/h2>\n\n\n\n
The advantage of 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 your chosen time or by configuring automation.<\/p>\n\n\n\n
Transferring a floating IP address using the UpCloud API is simple. While attaching a floating IP for the first time requires shutting down the target cloud server, transferring an existing address also works with running cloud servers.<\/p>\n\n\n\n
First, you need to know the network interface MAC address to which you wish to transfer the floating IP. For example, you can find the MAC address in your cloud server details by querying the API with the target server\u2019s UUID.<\/p>\n\n\n\n
GET \/1.3\/server\/server_uuid<\/span><\/pre>\n\n\n\n
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, and then enter the MAC address of the network interface on the target.<\/p>\n\n\n\n
PATCH \/1.3\/ip_address\/0.0.0.0<\/span>\n\n{\n  \"ip_address\": {\n    \"mac\": \"mm:mm:mm:mm:mm:m1<\/span>\"\n  }\n}\n<\/pre>\n\n\n\n
If you haven\u2019t yet used the floating IP on the new cloud server, you will also need to configure the floating IP at the operating system level.\u00a0You can find instructions in our guides for\u00a0CentOS<\/a>,\u00a0Debian<\/a>,\u00a0Ubuntu<\/a>,\u00a0CoreOS<\/a>\u00a0or\u00a0Windows<\/a>\u00a0on how to configure\u00a0the floating IP on your servers.<\/p>\n\n\n\n
It\u2019s 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.<\/p>\n\n\n\n
#!\/bin\/bash\n\n# Export your UpCloud credentials to the environmental variables\n# export UPCLOUD_USERNAME=username\n# export UPCLOUD_PASSWORD=password\n\n# Enter the floating ip address you want to attach\nip=0.0.0.0<\/span>\n# Select the target network interface, commonly eth0\ninterface=eth0<\/span>\n\n# API command to transfer the floating IP\ncurl -u \"$UPCLOUD_USERNAME:$UPCLOUD_PASSWORD\" -X PATCH \n-H Content-Type:application\/json https:\/\/api.upcloud.com\/1.3\/ip_address\/$ip \n--data-binary '{\"ip_address\":{\"mac\":\"'`cat \/sys\/class\/net\/$interface\/address`'\"}}'\n<\/pre>\n\n\n\n
Then, execute the script whenever you need the floating IP transferred. This allows you to redirect traffic or even automate failover quickly.<\/p>\n\n\n\n
Detaching a floating IP<\/h2>\n\n\n\n
Detaching a floating IP without attaching it to another interface, pass an explicit null<\/tt> or empty string as a mac<\/tt> value.<\/p>\n\n\n\n
Replace the IP address highlighted below in red<\/span> with the floating IP you wish to detach.<\/p>\n\n\n\n
PATCH \/1.3\/ip_address\/0.0.0.0<\/span>\n\n{\n  \"ip_address\": {\n    \"mac\": null<\/span>\n  }\n}<\/pre>\n\n\n\n
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., a DDoS attack.<\/p>\n\n\n\n
Deleting a floating IP<\/h2>\n\n\n\n
Use the following command to delete any IP address. The deletion is permanent and cannot be reversed.<\/p>\n\n\n\n
Replace the IP address highlighted below in red<\/span> with the floating IP you wish to delete.<\/p>\n\n\n\n
DELETE \/1.3\/ip_address\/0.0.0.0<\/span><\/pre>\n\n\n\n
If you delete an IP address by mistake, immediately attaching a new IP of the same type may give you the IP that was just released if it has not been attached anywhere else.<\/p>\n","protected":false},"author":3,"featured_media":27559,"comment_status":"open","ping_status":"closed","template":"","community-category":[271,259,247],"class_list":["post-2212","tutorial","type-tutorial","status-publish","has-post-thumbnail","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/2212","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial"}],"about":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/types\/tutorial"}],"author":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/comments?post=2212"}],"version-history":[{"count":0,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/2212\/revisions"}],"wp:attachment":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/media?parent=2212"}],"wp:term":[{"taxonomy":"community-category","embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/community-category?post=2212"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}