Networks operations#

This section covers the following networking and virtual interface operations:

Network Operations:

List networks
Create network
Create server with network
Show network details
Delete network

Virtual Interface Operations:

List virtual interfaces
Create virtual interface
Delete virtual interface

Retrieve list of networks#

GET /os-networksv2

This operation retrieves a list of the networks configured for the tenant ID specified in the request URI.

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	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This operation does not accept a request body.

Example Retrieves list of networks: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response#

This table shows the body parameters for the response:

Name	Type	Description
networks	Array	An array of networks.
networks.cidr	String	The CIDR for an isolated network. This parameter is not included for PublicNet and ServiceNet.
networks.id	String	The network ID.
networks. label	String	The name of the network. ServiceNet is labeled as private, and PublicNet is labeled as public in the network list.

Example Retrieve list of networks: JSON response

Status Code: 200 OK
Content-Length: 474
Content-Type: application/json
Date: Mon, 13 Apr 2015 18:41:07 GMT, Mon, 13 Apr 2015 18:41:08 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-889f3f67-e02e-416c-9d91-9e3bb33e766d

{
   "networks":[
      {
         "cidr":"192.168.0.0/24",
         "id":"1f84c238-b05a-4374-a0cb-aa6140032cd1",
         "label":"new_network"
      },
      {
         "id":"00000000-0000-0000-0000-000000000000",
         "label":"public"
      },
      {
         "id":"11111111-1111-1111-1111-111111111111",
         "label":"private"
      }
   ]
}

Create network#

POST /os-networksv2

This operation creates a network for the tenant ID specified in the request URI.

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	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the body parameters for the request:

Name	Type	Description
network	Object	A container of network details.
network.cidr	Uuid	The IP block from which to allocate the network. For example, 172.16.0.0/24 or 2001:DB8::/64. For more information about CIDR notation, Using CIDR Notation in Cloud Networks.
network. label	String	The name of the new network. For example, my_new_network.

Example Create network: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "network":
        {
            "cidr": "192.168.0.0/24",
            "label": "superprivate"
        }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
network	Object	A container of network details.
network.cidr	String	The CIDR for an isolated network.
network. id	String	The network ID.
network.label	String	The name of the network. ServiceNet is labeled as private and PublicNet is labeled as public in the network list.

Example Create network: JSON response

Status Code: 200 OK
Content-Length: 110
Content-Type: application/json
Date: Mon, 13 Apr 2015 19:04:21 GMT, Mon, 13 Apr 2015 19:04:24 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-175c37e9-60a7-42de-9922-5bf95644dad2

{
    "network": {
        "cidr": "192.168.0.0/24",
        "id": "1ff4489e-db0e-45a6-8c9f-4616c6ef5db1",
        "label": "superprivate"
    }
}

Create server with network#

POST /servers

This operation provisions a server asynchronously with a network.

You must specify the networks that you want to attach to your server. If you do not specify any networks, ServiceNet and PublicNet are attached by default.

The progress of the server build depends on factors including location of the requested image, network i/o, host load, and the selected flavor. You can check the progress of the build request by issuing a call to retrieve the details of the server. Once the build is complete, the server’s status is ACTIVE.

You can optionally provision the server instance with specified isolated networks. However, if you specify an isolated network, you must explicitly specify the UUIDs for PublicNet and ServiceNet to attach these networks to your server. The UUID for ServiceNet is 11111111-1111-1111-1111-111111111111, and the UUID for PublicNet is 00000000-0000-0000-0000-000000000000. Omit these UUIDs from the request to detach from these networks.

Note

Rack Connect and Managed Operations Service Level customers will receive an error if they opt out of attaching to PublicNet or ServiceNet.

To attach a network to an existing server, you must create a virtual interface.

For complete information about this API operation, see the Create server operation.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the body parameters for the request:

Name	Type	Description
server.name	String	The server name.
server.imageRef	Uuid	The image reference for the desired image for your server instance.
server.block_device_mapping_v2	Object (Optional)	The container of bootable volume details.
server.block_device_mapping_v2.boot_index	Integer (Optional)	The index of the bootable volume.
server.block_device_mapping_v2.uuid	Integer (Optional)	The id of the bootable volume.
server.block_device_mapping_v2.source_type	String (Optional)	The source type for the bootable volume.
server.block_device_mapping_v2.destination_type	String (Optional)	The destination type for the bootable volume.
server.block_device_mapping_v2.delete_on_termination	Boolean (Optional)	Flag to indicate whether the bootable volume should be deleted after server creation.
server.flavorRef	Uuid (Required)	The flavor reference for the desired flavor for your server instance.
server.config_drive	String (Optional)	Enables metadata injection in a server through a configuration drive. To enable a configuration drive, specify `true`. Otherwise, specify `false`.
server.key_name	String (Optional)	The name of the key pair used to authenticate by using key-based authentication instead of password- based authentication.
server.OS-DCF:diskConfig	String (Optional)	The disk configuration value. The image auto_disk_config metadata key set will affect the value you can choose to set the server `OS- DCF:diskConfig`. If an image has `auto_disk_config` value of `disabled`, you cannot create a server from that image when specifying `OS-DCF:diskConfig` value of `AUTO`. Valid values are: AUTO:The server is built with a single partition which is the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. AUTO is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images. MANUAL:The server is built using the partition scheme and file system of the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and it enables you to manage the disk configuration.
server.metadata	String (Optional)	Metadata key and value pairs. The maximum size of each metadata key and value is 255 bytes each.
server.personality	Array (Optional)	The array of personality files for the server.
server.user_data	String (Optional)	Data used with config_drive for configuring a server.
server.personality.path	String	The path of the personality file.
server.personality.contents	String	The contents of the personality file.
server.networks	Array	The array of networks attached to the server. By default, the server instance is provisioned with all isolated networks for the tenant. You can specify multiple NICs on the server. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a `Nova- network` network, specify the UUID in the `uuid` attribute in a `networks` object. To provision the server instance with a NIC for a `Neutron` network, specify the UUID in the `port` attribute in a `networks` object.
server.networks.uuid	Uuid (Optional)	The UUID of the `Nova-network` network attached to the server.
server.networks.port	Uuid (Optional)	The UUID of the `Neutron` port attached to the server.

Example Create server with network: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "server" : {
        "name" : "api-test-server-1",
        "imageRef" : "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
        "flavorRef" : "2",
        "config_drive": true,
        "key_name":"name_of_keypair",
        "OS-DCF:diskConfig" : "AUTO",
        "metadata" : {
            "My Server Name" : "API Test Server 1"
        },
        "personality" : [
            {
                "path" : "/etc/banner.txt",
                "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ],
        "networks": [
            {
                 "uuid": "f212726e-6321-4210-9bae-a13f5a33f83f"
            },
            {
                 "uuid": "00000000-0000-0000-0000-000000000000"
            },
            {
                 "uuid": "11111111-1111-1111-1111-111111111111"
            }
        ]
    }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
server	Object	The container for server data.
server.id	Uuid	The ID of the server.
server.links	Array	An array of the self and bookmark links to the server.
server.links.href	String	The URL for the server and the associated `rel`.
server.links.rel	String	The descriptive field for the associated `href`, which is either `self` or `bookmark`.
server.adminPass	String	The password assigned to provide login access to the server.
server.OS- DCF:diskConfig	String	The disk configuration value. Valid values are `AUTO` and `MANUAL`.

Example Create server with network: JSON response

Status Code: 202 Accepted
Content-Length: 380
Content-Type: application/json
Date: Thu, 04 Dec 2014 18:47:30 GMT
Location: https://dfw.servers.api.rackspacecloud.com/v2/820712/servers/4b963871-f591-4b7d-b05f-7c0286e3c50f
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-b8b54344-41a9-4d6a-a92f-60f3dcab4b1f

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "adminPass": "LMoheHauXt8w",
        "id": "ef08aa7a-b5e4-4bb8-86df-5ac56230f841",
        "links": [
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/ef08aa7a-b5e4-4bb8-86df-5ac56230f841",
                "rel": "self"
            },
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/010101/servers/ef08aa7a-b5e4-4bb8-86df-5ac56230f841",
                "rel": "bookmark"
            }
        ]
    }
}

Show network#

GET /os-networksv2/{id}

This operation shows information for the network specified in the request URI.

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	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{id}	Uuid	The network ID.

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
network	Object	A container of network details.
network.cidr	String	The CIDR for an isolated network.
network. id	String	The network ID.
network.label	String	The name of the network. ServiceNet is labeled as private and PublicNet is labeled as public in the network list.

Example Show network: JSON response

Status Code: 200 OK
Content-Length: 114
Content-Type: application/json
Date: Mon, 13 Apr 2015 20:50:28 GMT, Mon, 13 Apr 2015 20:50:28 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-bc7ab5c9-4a70-4a19-9189-e8f8884e8ae9

{
    "network": {
        "cidr": "192.168.0.0/24",
        "id": "f212726e-6321-4210-9bae-a13f5a33f83f",
        "label": "superprivate_xml"
    }
}

Delete network#

DELETE /os-networksv2/{id}

This operation deletes the network specified in the request URI.

Note

You can delete an isolated network only if it is not attached to any server. To detach a network from a server, delete the virtual interface for the network from the server instance.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Delete Successful	Delete request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{id}	Uuid	The network ID.

This operation does not accept a request body.

Example Delete network: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response#

Example Delete network: JSON response

Status Code: 202 Accepted
Content-Length: 58
Content-Type: text/plain; charset=UTF-8
Date: Tue, 14 Apr 2015 13:09:59 GMT, Tue, 14 Apr 2015 13:10:01 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-33b4fead-66a2-420e-b864-bc117d609a85

Retrieve list of virtual interfaces#

GET /servers/{server_id}/os-virtual-interfacesv2

This operation retrieves a lists the virtual interfaces configured for a server instance.

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	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This operation does not accept a request body.

Example Retrieves list of virtual interfaces: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response#

This table shows the body parameters for the response:

Name	Type	Description
virtual_interfaces	Array	The array of virtual interfaces.
virtual_interfaces.id	String	The virtual interface ID.
virtual_interfaces.ip_addresses	Array	The array of interface IP address details.
virtual_interfaces.ip-addresses.address	String	The interface IP address.
virtual_interfaces.ip_addresses.network_id	Uuid	The interface network ID.
virtual_interfaces.ip_addresses.network_label	String	The interface network label.
virtual_interfaces.mac_address	String	The Media Access Control (MAC) address for the virtual interface. A MAC address is a unique identifier assigned to network interfaces for communications on the physical network segment.

Example Retrieve list of virtual interfaces: JSON response

Status Code: 200 OK
Content-Length: 585
Content-Type: application/json
Date: Wed, 08 Apr 2015 14:24:10 GMT, Wed, 08 Apr 2015 14:24:11 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-3c46ba6b-36c6-42cd-a813-df476b396161

{
    "virtual_interfaces": [
        {
            "id": "a589b11b-cd51-4274-8ec0-832ce799d156",
            "ip_addresses": [
                {
                    "address": "2001:4800:7810:0512:d87b:9cbc:ff04:850c",
                    "network_id": "ba122b32-dbcc-4c21-836e-b701996baeb3",
                    "network_label": "public"
                },
                {
                    "address": "64.49.226.149",
                    "network_id": "ba122b32-dbcc-4c21-836e-b701996baeb3",
                    "network_label": "public"
                }
            ],
            "mac_address": "BC:76:4E:04:85:0C"
        },
        {
            "id": "de7c6d53-b895-4b4a-963c-517ccb0f0775",
            "ip_addresses": [
                {
                    "address": "192.168.0.2",
                    "network_id": "f212726e-6321-4210-9bae-a13f5a33f83f",
                    "network_label": "superprivate_xml"
                }
            ],
            "mac_address": "BC:76:4E:04:85:20"
        },
        {
            "id": "e14e789d-3b98-44a6-9c2d-c23eb1d1465c",
            "ip_addresses": [
                {
                    "address": "10.181.1.30",
                    "network_id": "3b324a1b-31b8-4db5-9fe5-4a2067f60297",
                    "network_label": "private"
                }
            ],
            "mac_address": "BC:76:4E:04:81:55"
        }
    ]
}

Create virtual interface and attach to server#

POST /servers/{server_id}/os-virtual-interfacesv2

This operation creates a virtual interface for a network and attaches the network to a server instance.

Note

You can create a maximum of one virtual interface per instance per network.

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	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
virtual_interface	Object	A container with virtual interface information.
virtual_interface.network_id	Uuid	The interface network ID.

Example Create virtual interface and attach to server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
   "virtual_interface":
    {
      "network_id": "1f7920d3-0e63-4fec-a1cb-f7916671e8eb"
    }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
virtual_interfaces	Array	The array of virtual interfaces.
virtual_interfaces.id	String	The virtual interface ID.
virtual_interfaces.ip_addresses	Array	The array of interface IP address details.
virtual_interfaces.ip_addressesaddress	String	The interface IP address.
virtual_interfaces.ip_addresses.network_id	Uuid	The interface network ID.
virtual_interfaces.ip_addresses.network_label	String	The interface network label.
virtual_interfaces.mac_address	String	The Media Access Control (MAC) address for the virtual interface. A MAC address is a unique identifier assigned to network interfaces for communications on the physical network segment.

Example Create virtual interface and attach to server: JSON response

Status Code: 200 OK
Content-Length: 247
Content-Type: application/json
Date: Wed, 08 Apr 2015 18:03:16 GMT, Wed, 08 Apr 2015 18:03:23 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-f28cbcae-fe5e-4318-908a-dd6a9cb23122

{
   "virtual_interfaces":[
      {
         "mac_address":"FE:ED:FA:00:08:93",
         "id":"045f195f-3347-487b-8e80-8ee3390eda56",
         "ip_addresses":[
            {
               "address":"192.168.0.1",
               "network_id":"196a0246-86cc-46fa-9ecf-850f67c2cb7c",
               "network_label":"added_network"
            }
         ]
      }
   ]
}

Delete virtual interface#

DELETE /servers/{server_id}/os-virtual-interfacesv2/{interface_id}

This operation deletes the specified virtual interface from the specified server instance.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Delete Successful	Delete request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{interface_id}	Uuid	The interface ID.

This operation does not accept a request body.

Example Delete virtual interface: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response#

Example Delete virtual interface: JSON response

Status Code: 200 OK
Content-Length: 0
Content-Type: application/json
Date: Wed, 08 Apr 2015 17:09:53 GMT, Wed, 08 Apr 2015 17:09:59 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-12a961ef-4cf3-419e-9ea5-b7afeb184691