IP Addresses

IP addresses can be assigned to servers and services. UpCloud supports both IPv4 and IPv6 addresses, as well as floating IPs that can be moved between servers in the same zone.

Each server can have up to five public IP addresses assigned. IP addresses can be either permanent (released when the server is deleted) or floating (retained for reassignment).

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.

Name
release
Description
The address is also deleted when the dependent resource is deleted. This applies to both normal and floating IP addresses.
Name
keep
Description
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. 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:

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. Currently only Load Balancer supports IP address delegation.

GET/1.3/ip_address

List IP addresses

Returns a list of all IP addresses assigned to servers on the current account.

Response fields

Name
access
Type
string
Description
Network access type: "utility", "public", or "private".
Name
address
Type
string
Description
The IP address.
Name
family
Type
string
Description
Address family: "IPv4" or "IPv6".
Name
ptr_record
Type
string
Description
Reverse DNS PTR record for the address.
Name
server
Type
string
Description
UUID of the server the address is attached to.
Name
mac
Type
string
Description
MAC address of the network interface.
Name
floating
Type
string
Description
Whether this is a floating IP: "yes" or "no".
Name
release_policy
Type
string
Description
What happens when the dependent resource is deleted: "release" or "keep".
Name
is_delegated
Type
string
Description
Whether the IP is delegated to a service: "yes" or "no".
Name
zone
Type
string
Description
The zone where the IP address is located.

Request

GET

/1.3/ip_address

curl -X GET https://api.upcloud.com/1.3/ip_address \
  -u your_username:your_password

GET/1.3/ip_address/{address}

Get IP address details

Returns detailed information about a specific IP address.

Request

GET

/1.3/ip_address/{address}

curl -X GET https://api.upcloud.com/1.3/ip_address/185.70.196.1 \
  -u your_username:your_password

POST/1.3/ip_address

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 can be attached using the Modify IP address operation.

Attributes

Name
access
Type
string
Description
Network type: "utility" or "public". Default: "public".
Name
family
Type
string
Description
Address family: "IPv4" or "IPv6". Default: "IPv4".
Name
server
Type
string
Description
UUID of the server to assign the address to. Required for non-floating IPs.
Name
zone
Type
string
Description
Zone identifier. Required for floating IPs.
Name
floating
Type
string
Description
Create as floating IP: "yes" or "no".
Name
mac
Type
string
Description
MAC address of the network interface for floating IPs.

Creating Floating IPs

Directly attached floating IPs: Specify the mac address of the server's public network interface.
Detached floating IPs: Specify zone and floating: "yes" without a mac address to reserve for later use.

Request

POST

/1.3/ip_address

curl -X POST https://api.upcloud.com/1.3/ip_address \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": {
      "family": "IPv4",
      "server": "009d64ef-31d1-4684-a26b-c86c955cbf46"
    }
  }'

PATCH/1.3/ip_address/{address}

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 on public IP addresses.

Attributes

Name
mac
Type
string
Description
MAC address of server interface to attach floating IP to. Pass null or empty string to detach.
Name
ptr_record
Type
string
Description
A fully qualified domain name for the reverse DNS PTR record.
Name
release_policy
Type
string
Description
Release policy: "release" or "keep".

Request

PATCH

/1.3/ip_address/{address}

curl -X PATCH https://api.upcloud.com/1.3/ip_address/185.70.196.1 \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": {
      "mac": "de:ad:be:ef:00:02",
      "ptr_record": "hostname.example.com",
      "release_policy": "keep"
    }
  }'

DELETE/1.3/ip_address/{address}

Release IP address

Removes an IP address from a server. The IP address is released and returned to the pool.

IP addresses on the utility network cannot be deleted. Delegated IP addresses cannot be deleted while they are attached to a service.

Request

DELETE

/1.3/ip_address/{address}

curl -X DELETE https://api.upcloud.com/1.3/ip_address/185.70.196.2 \
  -u your_username:your_password