10. IP Addresses
The UpCloud network has public and private IP addresses.
Public IP addresses are used to connect to the server from the Internet.
Private Utility network addresses are available for all servers within a single account, and can communicate with each other globally as long as the servers have the utility network interfaces configured. This is added to servers by default.
A server has a minimum of zero and a maximum of five public IPv4 and IPv6 addresses. Every server can have one utility network IPv4 address only, and must have at least one IP address. The UpCloud API assigns the IP addresses automatically in networks configured to use DHCP. IP addresses cannot be reserved for later use, except for floating IPs that can be reserved and switched from server to another freely within their specific zone.
The operating system running on the server will see a separate network interface per IP address. On a typical server, there are three network interfaces. The first network interface is assigned to the public network and the second to the Utility network. If the server has an IPv6 address configured it will use the third network interface. DHCP service is provided on all public IPv4 network interfaces and all private DHCP-enabled networks for automatic configuration of the correct IP address. IPv6 network interfaces should use stateless address autoconfiguration (SLAAC) with IPv6 privacy extensions disabled. On IPv6-only server DNS parameters can be obtained with stateless DHCPv6.
Additionally, there are floating IP's: IPv4 addresses that can be attached to any IPv4 interface in their specific zone (eg. de-fra1 or fi-hel2). Floating IP addresses can be instantly switched from one server to another when doing maintenance or dealing with technical issues. More information on floating IPs and their configuration can be found from our tutorials.
Release policy
The release policy defines what happens to an IP address when its dependent resource is deleted, such as a server or service it's attached to. The following values are supported:
release: The address is also deleted. This applies to both normal and floating IP addresses.
keep: For normal (non-floating) IP addresses, they are converted to detached floating IPs when their dependent resource is deleted. For floating IP addresses, they remain as detached floating IPs that can be reattached elsewhere.
Floating IP addresses are created with keep as default policy, ensuring they remain available even after dependency deletion.
The release policy can be set when creating a new IP address or modified for an existing one through the API.
Note that release policy functionality is currently only supported for public IPv4 addresses.
Service delegation
Assign existing Floating IPv4 addresses to a service instead of a server. This enables the service to manage the IP address and use your dedicated floating IP address in the service's DNS records.
Delegated IP addresses can be tracked with the is_delegated attribute in the API response.
When an IP address is delegated to a service, it becomes subject to specific access restrictions. The IP address becomes managed by the service until you explicitly remove it. During the delegation:
- You cannot delete the IP address.
- You cannot modify its MAC address.
- You can only update the release policy and PTR record.
These restrictions ensure service stability and are automatically lifted once the IP address is removed from the service and as long as the release policy is set to keep so the IP address remains available in your account.
Currently only Load Balancer supports IP address delegation.
List IP addresses
Returns a list of all IP addresses assigned to servers on the current user account.
Request
Normal response
{
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family": "IPv4",
"ptr_record": "",
"server": "0053cd80-5945-4105-9081-11192806a8f7",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "no",
"release_policy": "release",
"zone": "fi-hel2"
},
{
"access": "utility",
"address": "10.0.0.1",
"family": "IPv4",
"ptr_record": "",
"server": "006b6701-55d2-4374-ac40-56cc1501037f",
"mac": "mm:mm:mm:mm:mm:m2",
"floating": "no",
"release_policy": "keep",
"zone": "de-fra1"
},
{
"access": "public",
"address": "x.x.x.x",
"family": "IPv4",
"part_of_plan": "yes",
"ptr_record": "x-x-x-x.zone.upcloud.host",
"server": "0053cd80-5945-4105-9081-11192806a8f7",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "yes",
"release_policy": "release",
"zone": "de-fra1"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family": "IPv6",
"ptr_record": "xxxx-xxxx-xxxx-xxxx.v6.zone.upcloud.host",
"server": "006b6701-55d2-4374-ac40-56cc1501037f",
"mac": "mm:mm:mm:mm:mm:m3",
"floating": "no",
"release_policy": "release",
"zone": "fi-hel1"
},
{
"access": "public",
"address": "y.y.y.y",
"family": "IPv4",
"ptr_record": "y.y.y.y.zone.host.upcloud.com",
"floating": "yes",
"release_policy": "keep",
"zone": "nl-ams1"
},
{
"access": "public",
"address": "z.z.z.z",
"family": "IPv4",
"ptr_record": "z.z.z.z.zone.host.upcloud.com",
"floating": "yes",
"release_policy": "keep",
"is_delegated": "yes",
"zone": "nl-ams1"
}
]
}
}
Get IP address details
Returns detailed information about a specific IP address.
Request
Where address specifies the IP address. eg. 127.0.0.1
Normal response
{
"ip_address": {
"access": "public",
"address": "0.0.0.0",
"family": "IPv4",
"part_of_plan": "yes",
"ptr_record": "test.example.com",
"server": "009d64ef-31d1-4684-a26b-c86c955cbf46",
"mac": "mm:mm:mm:mm:mm:m5",
"floating": "no",
"release_policy": "keep",
"is_delegated": "yes",
"zone": "sg-sin1"
}
}
Assign IP address
Assigns a new IP address to a server.
There is a maximum of five public IP addresses per server.
If a MAC address is specified, the server where the corresponding interface is must be in stopped state.
Floating IPs are attached with the Modify IP address operation.
Request
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| access | utility / public | public | no | Is address for utility or public network. |
| family | IPv4 / IPv6 | IPv4 | no | The address family of new IP address. |
| address | IPv4 address | no | Assign a specific address. Requires special privileges and is supported for IPv4 only. | |
| server | Server UUID | yes | UUID of a server for which the address is assigned. |
Creating Floating IPs
Floating IPs can be directly attached to servers by specifying
a MAC address to one of their public interfaces. If mac is not
specified, the address is created without attaching it to any server.
{
"ip_address": {
"family": "IPv4",
"mac": "mm:mm:mm:mm:mm:m1",
"release_policy": "release",
"floating": "yes"
}
}
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| access | utility / public | public | no | Is address for utility or public network. |
| family | IPv4 / IPv6 | IPv4 | no | The address family of new IP address. |
| floating | yes / no | no | no | Whether the address to be assigned is a floating one. |
| address | IPv4 address | no | Assign a specific address. Requires special privileges and is supported for IPv4 only. | |
| mac | MAC address | (varies) | MAC address of server interface to assign address to. Required for non-floating addresses. | |
| release_policy | release / keep |
no | Defines what happens when a dependent resource (such as a server or service the IP is attached to) is deleted. release will delete the IP address when the dependent resource is deleted. keep will convert the address to a detached floating IP that remains available in your account. |
Normal response
{
"ip_address": {
"access": "public",
"address": "0.0.0.0",
"family": "IPv4",
"ptr_record": "xxxx-xxxx-xxxx-xxxx.v6.zone.upcloud.host",
"server": "009d64ef-31d1-4684-a26b-c86c955cbf46",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "yes",
"release_policy": "release",
"zone": "fi-hel2"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The attribute server has an invalid value. |
| 402 Payment Required | INSUFFICIENT_CREDITS | There are not enough credits to perform the requested action. See Credits. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 403 Forbidden | ADDRESS_SELECTION_FORBIDDEN | The address selection feature is not available for this account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 409 Conflict | IP_ADDRESS_LIMIT_REACHED | The maximum number of IP addresses are already attached to the server. |
| 409 Conflict | IP_ADDRESS_RESOURCES_UNAVAILABLE | There are not enough IP addresses available in the specified zone. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
| 409 Conflict | RELEASE_POLICY_NOT_AVAILABLE | The release policy is only available for public IPv4 addresses. |
Modify IP address
Modifies the reverse DNS PTR record corresponding to an IP address,
and modifies attachment of a floating IP. Attaching a floating IP to
an interface detaches it from its previous interface, if any. To
detach a floating IP without attaching it to another interface, pass
explicit null or empty string as mac value. The PTR record can
only be set to a public IP address.
Request
Where address specifies the IP address. eg. 127.0.0.1
{
"ip_address": {
"mac": "mm:mm:mm:mm:mm:m1",
"ptr_record": "hostname.example.com",
"release_policy": "release"
}
}
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| mac | MAC address | no | MAC address of server interface to attach floating IP to. | |
| ptr_record | DNS PTR record value | no | A fully qualified domain name. | |
| release_policy | release / keep |
no | Defines what happens when a dependent resource (such as a server or service the IP is attached to) is deleted. release will delete the IP address when the dependent resource is deleted. keep will convert the address to a detached floating IP that remains available in your account. |
Normal response
{
"ip_address": {
"access": "public",
"address": "0.0.0.0",
"family": "IPv4",
"ptr_record": "hostname.example.com",
"server": "009d64ef-31d1-4684-a26b-c86c95c5bf46",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "yes",
"zone": "sg-sin1"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | IP_ADDRESS_INVALID | The attribute ip_address has an invalid value. |
| 400 Bad Request | PTR_RECORD_INVALID | The attribute ptr_record has an invalid value. |
| 400 Bad Request | MAC_INVALID | The attribute mac has an invalid value. |
| 403 Forbidden | IP_ADDRESS_FORBIDDEN | The IP address exists, but belong to another user. |
| 404 Not found | IP_ADDRESS_NOT_FOUND | The IP address does not exist. |
| 409 Conflict | PTR_RECORD_NOT_SUPPORTED | A PTR record was tried to set on a utility IP address. |
| 409 Conflict | FLOATING_IP_NOT_AVAILABLE | The floating IP operation is not available for the specified IP address. |
| 409 Conflict | IP_ADDRESS_DELEGATED | The IP address is delegated to a service. Changes to the mac address or deletion of the IP address are not allowed. |
| 409 Conflict | RELEASE_POLICY_NOT_AVAILABLE | The release policy is only available for public IPv4 addresses. |
Release IP address
Removes an IP address from a server.
Request
Where address specifies the IP address. eg. 127.0.0.1
Normal response
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | IP_ADDRESS_INVALID | The attribute ip_address has an invalid value. |
| 403 Forbidden | IP_ADDRESS_FORBIDDEN | The IP address exists, but is assigned to another account. |
| 404 Not Found | IP_ADDRESS_NOT_FOUND | The IP address does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
| 409 Conflict | CANNOT_DELETE_PRIVATE_ADDRESS | The IP address on the utility network cannot be deleted. |
| 409 Conflict | IP_ADDRESS_DELEGATED | The IP address cannot be deleted while it is delegated to an existing service. |