Shared IP address operations

This section describes the API operations for Shared IP addresses. For general information about shared IP addresses, see Shared IP addresses concepts.

Note

The Shared IP Addresses API is available to all customers except RackConnect customers.

Retrieve list of IP addresses

GET /v2.0/ip_addresses

This operation retrieves list of IP addresses for specified tenant.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.

Request

This operation does not accept a request body.

Response

This table shows the body parameters for the response:

Name	Type	Description
ip_addresses	Array	The array of IP addresses.
ip_addresses.id	Uuid	The ID of the IP address.
ip_addresses.network_id	Uuid	The network UUID of the IP address.
ip_addresses.address	String	The IP address.
ip_addresses.port_ids	Array	The array of port objects, containing port IDs. More than one port ID indicates a shared IP.
ip_addresses.subnet_id	Uuid	The subnet UUID of the IP address.
ip_addresses.tenant_id	Uuid	The ID of the tenant who owns the IP address.
ip_addresses.version	String	The subnet IP version, which is 4 or 6.
ip_addresses.type	String	The type of IP address. Valid types are fixed or shared.

Example Retrieve list of IP addresses: JSON response

{
    "ip_addresses":
    [
       {
            "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
            "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
            "address": "192.168.10.1",
            "port_ids":
                ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
            "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
            "tenant_id": "2345678",
            "version": "4",
            "type": "fixed"
        }
    ]
}

Provision IP address

POST /v2.0/ip_addresses

This operation allows you to provision an IP address on a specified network.

A list of port_ids must be specified to provision the IP address on the specified ports.

For Cloud Networks only, you can provision a shared IP with a specific IP address. To do this, you must specify a network ID in the request in addition to the specific IP that you want to provision. You cannot specify an IP to provision for either PublicNet or ServiceNet.

Note

When provisioning IP addresses, the type is automatically set to shared when multiple port IDs are included in the request.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.

Request

This table shows the body parameters for the request:

Name	Type	Description
ip_address	Object	The container for shared IP request parameters.
ip_address.network_id	Uuid	The ID of the network. A “network_id” of 00000000-0000-0000- 0000-000000000000 provisions an IP address on PublicNet
ip_address.port_ids	Array	The array of port objects, containing port IDs. At least two ports are required to provision a shared IP address.
ip_address.version	String	The subnet IP version, which is 4 or 6.
ip_address.ip-address	String	For Cloud Networks only, the specified IP that you want to provision.

Example Provision IP address: JSON request

{
    "ip_address": {
        "network_id": "00000000-0000-0000-0000-000000000000",
        "version": 4,
        "port_ids": [
            "6200d533-a42b-4c04-82a1-cc14dbdbf2de",
            "9d0db2d7-62df-4c99-80cb-6f140a5260e8"
         ]
    }
}

Example Provision IP address with a specified IP: JSON request

{
    "ip_address": {
        "network_id": "851fe377-bb10-4922-a83a-6358bbc09347",
        "version": 4,
        "port_ids": [
            "6200d533-a42b-4c04-82a1-cc14dbdbf2de",
            "9d0db2d7-62df-4c99-80cb-6f140a5260e8"
         ]
       "ip_address": "192.168.100.4"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
ip_address	Object	The container of IP address information.
ip_address.id	Uuid	The ID of the IP address.
ip_address.network_id	Uuid	The network UUID of the IP address.
ip_address.address	String	The IP address.
ip_address.port_ids	Array	The array of port objects, containing port IDs. More than one port ID indicates a shared IP.
ip_address.subnet_id	Uuid	The subnet UUID of the IP address.
ip_address.tenant_id	Uuid	The ID of the tenant who owns the IP address.
ip_address.version	String	The subnet IP version, which is 4 or 6.
ip_address.type	String	The type of IP address. Valid types are fixed or shared.

Example Provision IP address: JSON response

{
    "ip_address":
    {
        "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
        "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
        "address": "192.168.10.1",
        "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de",
                    "9d0db2d7-62df-4c99-80cb-6f140a5260e8"],
        "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
        "tenant_id": "2345678",
        "version": "4",
        "type": "shared"
    }
}

Example Provision IP address with a specified IP: JSON response

{
    "ip_address":
    {
        "id": "4decd21e-d3ba-4ab3-96f4-5c2f56eba929",
        "network_id": "851fe377-bb10-4922-a83a-6358bbc09347",
        "address": "192.168.100.4",
        "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de",
                    "9d0db2d7-62df-4c99-80cb-6f140a5260e8"
        "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
        "tenant_id": "2345678",
        "version": "4",
        "type": "shared"
    }
}

Update ports with an IP address

PUT /v2.0/ip_addresses/{ipAddressID}

This operation updates the port IDs that are sharing an IP address, using the IP address ID. Old ports are replaced by the new list of ports included in the request body. Only the port attributes may be updated with this operation.

Note

Updating the IP address with an empty port list de-allocates the IP addresses from the tenant using the IP address.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.
403	Forbidden	The request is forbidden.
404	Not Found	Item not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{ipAddressID}	String	The IP address ID. Note that this is the ID and not the IP address itself.

This table shows the body parameters for the request:

Name	Type	Description
ip_address	Array	The container for shared IP request parasmeters.
ip_address.port_ids	Array	The array of port objects, containing port IDs which have the shared IP.

Example Update ports with an IP address: JSON request

{
    "ip_address": {
        "port_ids": ['275b0516-206f-4421-8e42-1d3d1e4e9fb2', '66811c0a-fdbd-49d4-b1dd-f0f15a329744']
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
ip_address	Object	The container of IP address information.
ip_address.id	Uuid	The ID of the IP address.
ip_address.network_id	Uuid	The network UUID of the IP address.
ip_address.address	String	The IP address.
ip_address.port_ids	Array	The array of port objects, containing port IDs. More than one port ID indicates a shared IP.
ip_address.subnet_id	Uuid	The subnet UUID of the IP address.
ip_address.tenant_id	Uuid	The ID of the tenant who owns the IP address.
ip_address.version	String	The subnet IP version, which is 4 or 6.
ip_address.type	String	The type of IP address. Valid types are fixed or shared.

Example Update ports with an IP address: JSON response

{
    "ip_address":
    {
        "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
        "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
        "address": "192.168.10.1",
        "port_ids": ['275b0516-206f-4421-8e42-1d3d1e4e9fb2',
                    '66811c0a-fdbd-49d4-b1dd-f0f15a329744'],
        "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
        "tenant_id": "2345678",
        "version": "4",
        "type": "shared"
    }
}

Show IP address details

GET /v2.0/ip_addresses/{ipAddressID}

This operation retrieves information for a specified IP address, using the IP address ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{ipAddressID}	String	The IP address ID. Note that this is the ID and not the IP address itself.

This operation does not accept a request body.

Response

This table shows the body parameters for the response:

Name	Type	Description
ip_address	Object	The container of IP address information.
ip_address.id	Uuid	The ID of the IP address.
ip_address.network_id	Uuid	The network UUID of the IP address.
ip_address.address	String	The IP address.
ip_address.port_ids	Array	The array of port objects, containing port IDs. More than one port ID indicates a shared IP.
ip_address.subnet_id	Uuid	The subnet UUID of the IP address.
ip_address.tenant_id	Uuid	The ID of the tenant who owns the IP address.
ip_address.version	String	The subnet IP version, which is 4 or 6.
ip_address.type	String	The type of IP address. Valid types are fixed or shared.

Example Show IP address details: JSON response

{
    "ip_address":
    {
        "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
        "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
        "address": "192.168.10.1",
        "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de",
                    "9d0db2d7-62df-4c99-80cb-6f140a5260e8"],
        "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
        "tenant_id": "2345678",
        "version": "4",
        "type": "shared"
    }
}

De-allocate IP address

DELETE /v2.0/ip_addresses/{ipAddressID}

This operation de-allocates the specified associated IP address from the tenant, using the associated IP address ID.

Note

Before using this operation to de-allocate an IP address from a tenant, all IP associations must be removed from the IP address by using the DELETE /ip_associations operation.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{ipAddressID}	String	The IP address ID. Note that this is the ID and not the IP address itself.

This operation does not accept a request body.

Response

Example De-allocate IP address: JSON response

Content-Type: application/json
Accept: application/json
status: 204

Retrieve list of IP addresses explicitly associated with a server

GET /v2/{tenantID}/servers/{serverID}/ip_associations

This operation retrieves a list of all IP addresses explicitly associated to the specified server using the /ip_addresses API operations.

Any IP addresses provisioned using POST /ip_addresses that have not been associated with the servers using the /ip_associations API will not be able to forward traffic from the intended servers. For example, if you need to share IP address between two ports, belonging to two servers, you must use a POST /ip_addresses for the relevant ports, followed by an IP association. The IP association must be done for the IP address for both the servers so that they can forward traffic for the IP address.

In the URI, specify the tenant ID and the target server ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.
403	Forbidden	The request is forbidden.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	Compute fault	There was a compute fault.
503	Service Unavailable	The requested service is unavailable.

Request

This operation does not accept a request body.

Response

This table shows the body parameters for the response:

Name	Type	Description
ip_associations	Array	The array of IP associations.
ip_associations.id	Uuid	The ID of the associated IP address.
ip_associations.address	Uuid	The associatied IP address.

Example Retrieve list of IP addresses explicitly associated with a server: JSON response

{
    "ip_associations":
    [
        {
            "id": "1",
            "address": "10.1.1.1"
        },
        {
            "id": "2",
            "address": "10.1.1.2"
        }
    ]
}

Explicitly associate IP address with server

PUT /v2/servers/{serverID}/ip_associations/{IPAddressID}

This operation explicitly associates to a server an IP address.

Important

Before using this operation, you must use the POST ip_addresses API operation to provision the IP address.

Any IP addresses provisioned using POST /ip_addresses that have not been associated with the servers using the /ip_associations API will not be able to forward traffic from the intended servers. For example, if you need to share IP address between two ports, belonging to two servers, you must use a POST /ip_addresses for the relevant ports, followed by an IP association. The IP association must be done for the IP address for both the servers so that they can forward traffic for the IP address.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.
403	Forbidden	The request is forbidden.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	Compute fault	There was a compute fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{IPAddressID}	Uuid	The IP address ID. Note that this is the ID and not the IP address itself.

This operation does not accept a request body.

Response

This table shows the body parameters for the response:

Name	Type	Description
ip_association.id	Uuid	The ID of the associated IP address.
ip_association.address	Uuid	The associatied IP address.

Example Explicitly associate IP address with server: JSON response

{
    "ip_association":
        {
            "id": "2",
            "address": "10.1.1.2"
        }
}

Show specific IP addresses explicitly associated with server

GET /v2/servers/{serverID}/ip_associations/{IPAddressID}

This operation retrieves information for a specific IP address explicitly associated with a server using the /ip_associations API operations by specifying the associated IP address ID.

Perform this operation to verify that the association of the IP address to the server exists.

Any IP addresses provisioned using POST /ip_addresses that have not been associated with the servers using the /ip_associations API will not be able to forward traffic from the intended servers. For example, if you need to share IP address between two ports, belonging to two servers, you must use a POST /ip_addresses for the relevant ports, followed by an IP association. The IP association must be done for the IP address for both the servers so that they can forward traffic for the IP address.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.
403	Forbidden	The request is forbidden.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	Compute fault	There was a compute fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{IPAddressID}	Uuid	The IP address ID. Note that this is the ID and not the IP address itself.

This operation does not accept a request body.

Response

This table shows the body parameters for the response:

Name	Type	Description
ip_association.id	Uuid	The ID of the associated IP address.
ip_association.address	Uuid	The associatied IP address.

Example Show specific IP addresses explicitly associated with server: JSON response

{
    "ip_association":
    {
        "id": "1",
        "address": "10.1.1.1"
    }
}

Delete association between IP address and server

DELETE /v2/servers/{serverID}/ip_associations/{IPAddressID}

This operation deletes the association between the server and the associated IP address, using the associated IP address ID.

Note

All IP associations must be removed from an IP address by using this operation before you can de-allocate an IP address from a tenant, by using the DELETE /ip_addresses or the PUT /ip_addresses operation with an empty list of port IDs.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.
403	Forbidden	The request is forbidden.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	Compute fault	There was a compute fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{IPAddressID}	Uuid	The IP address ID. Note that this is the ID and not the IP address itself.

This operation does not accept a request body.

Response

Example Delete association between IP address and server: JSON response

Content-Type: application/json
Accept: application/json
status: 204