Subnet operations#

This section describes the API operations for subnets. For general information about subnets, see Subnets concepts.

Retrieve list of subnets#

GET /v2.0/subnets

This operation retrieves list of subnets to which the specified tenant has access.

You can control which attributes are returned by using the fields query parameter. For more information, see Filtering Requests.

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
subnets	Array	The array of subnets.
subnets.name	String	The subnet name.
subnets.enable_dhcp	Boolean	Indicates if DHCP for the subnet is enabled. This value is `false` and cannot be changed.
subnets.network_id	Uuid	The ID of the attached network.
subnets.tenant_id	Uuid	The ID of the tenant who owns the subnet.
subnets.dns_nameservers	Array	The array of dns name servers for the subnet.
subnets.allocation_pools	Array	The array of allocation pool objects.
subnets.allocation_pools.end	String	The ending IP address of the subnet allocation pool.
subnets.allocation_pools.start	String	The starting IP address of the subnet allocation pool.
subnets.host_routes	Array	The array of host routes for the subnet.
subnets.ip_version	String	The subnet IP version, which is `4` or `6`.
subnets.gateway_ip	String	The gateway IP address.
subnets.cidr	String	The CIDR for the subnet.
subnets.id	Uuid	The ID of the subnet.

Example Retrieve list of subnets: JSON response

{
    "subnets": [
        {
            "allocation_pools": [
                {
                    "end": "192.168.9.254",
                    "start": "192.168.9.1"
                }
            ],
            "cidr": "192.168.9.0/24",
            "dns_nameservers": [],
            "enable_dhcp": false,
            "gateway_ip": null,
            "host_routes": [],
            "id": "f975defc-637d-4e2a-858b-c6cc4cec3951",
            "ip_version": 4,
            "name": "",
            "network_id": "0ebf6a10-5fc1-4f13-aca9-be0a2a00b1ac",
            "tenant_id": "123456"
        }
    ]
}

Create subnet#

POST /v2.0/subnets

This operation creates a subnet on a specified network.

You cannot create subnets on the PublicNet and ServiceNet networks. Only one IPv4 subnet and one IPv6 subnet are permitted per network.

If the gateway_ip parameter is not specified, it is set to null.

If the allocation_pools parameter is not specified, Cloud Networks automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise, you can explicitly specify allocation pools as shown in the following example.

Warning

When you specify both the allocation_pools and gateway_ip parameters, you must ensure that the gateway IP address does not overlap with the specified allocation pools. Otherwise, a 409 Conflict error occurs.

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.
404	Not Found	Item not found.
409	conflict	There is a resource conflict.

Request#

This table shows the body parameters for the request:

Name	Type	Description
subnet	Object	The container for subnet details.
subnet.name	String (Optional)	The subnet name.
subnet.network_id	Uuid	The ID of the attached network.
subnet.cidr	String	The subnet CIDR.
subnet.ip_version	String	The subnet IP version, which is `4` or `6`.
subnet.allocation_pools	Array (Optional)	The array of allocation pool objects.
subnet.allocation_pools.end	String (Optional)	The ending IP address of the subnet allocation pool.
subnet.allocation_pools.start	String (Optional)	The starting IP address of the subnet allocation pool.
subnet.host_routes	Array (Optional)	The array of host route IP addresses for the subnet.
subnet.host_routes.destination	String (Optional)	The host route destination IP address and port.
subnet.host_routes.next_hop	String (Optional)	The host route destination next hop IP address.
subnet.gateway_ip	String (Optional)	The subnet gateway IP address.

Example Create subnet: JSON request

{
    "subnet": {
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "ip_version": 4,
        "name":"",
        "cidr": "192.168.199.0/24"
    }
}

Example Create Subnet with host routes: JSON request

{
    "subnet": {
    "network_id": "eaac8bec-9caf-43a2-8a9d-18ad3d1709c9",
    "ip_version": 4,
    "name":"",
    "cidr": "192.168.19.0/24",
    "host_routes": [
            {
                "destination": "1.1.1.0/24",
                "nexthop": "192.168.19.20"
            }
        ]
    }
}

Example Create Subnet with allocation pools and gateway IP: JSON request

{
    "subnet":
    {
        "network_id": "c23f2b6c-efa1-4b66-8bdf-34cda87b8102",
        "ip_version": 4,
        "name":"",
        "cidr": "192.168.62.0/24",
        "gateway_ip": "192.168.62.1",
        "allocation_pools": [
            {
                "end": "192.168.62.21",
                "start": "192.168.62.11"
            },
            {
                "end": "192.168.62.251",
                "start": "192.168.62.241"
            }
        ],
        "tenant_id": "123456"
    }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
subnet	Object	The container for subnet details.
subnet.name	String	The subnet name.
subnet.enable_dhcp	Boolean	Indicates if DHCP for the subnet is enabled. This value is `false` and cannot be changed.
subnet.network_id	Uuid	The ID of the attached network.
subnet.tenant_id	Uuid	The tenant ID of the owner of the subnet. Only administrative users can specify a tenant ID other than their own.
subnet.dns_nameservers	Array	The array of DNS name servers for the subnet.
subnet.allocation_pools	Array	The array of allocation pool objects.
subnet.allocation_pools.end	String	The ending IP address of the subnet allocation pool.
subnet.allocation_pools.start	String	The starting IP address of the subnet allocation pool.
subnet.host_routes	Array	The array of host route IP addresses for the subnet.
subnet.ip_version	String	The subnet IP version, which is `4` or `6`.
subnet.gateway_ip	String	The subnet gateway IP address.
subnet.cidr	String	The subnet CIDR.
subnet.id	Uuid	The ID of the subnet.

Example Create subnet: JSON response

{
    "subnet": {
        "name": "",
        "enable_dhcp": false,
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "dns_nameservers": [],
        "allocation_pools": [
            {
                "start": "192.168.199.1",
                "end": "192.168.199.254"
            }
        ],
        "host_routes": [],
        "ip_version": 4,
        "gateway_ip": null,
        "cidr": "192.168.199.0/24",
        "id": "3b80198d-4f7b-4f77-9ef5-774d54e17126"
    }
}

Example Create Subnet with host routes: JSON response

{
    "subnet": {
        "allocation_pools": [
            {
               "end": "192.168.19.254",
               "start": "192.168.19.1"
            }
         ],
        "cidr": "192.168.19.0/24",
        "dns_nameservers": [],
        "enable_dhcp": false,
        "gateway_ip": null,
        "host_routes": [
            {
                "destination": "1.1.1.0/24",
                "nexthop": "192.168.19.20"
            }
        ],
        "id": "f46041c1-7c39-4d15-a018-de2ccc31931c",
        "ip_version": 4,
        "name": "",
        "network_id": "eaac8bec-9caf-43a2-8a9d-18ad3d1709c9",
        "tenant_id": "546428"
    }
}

Example Create Subnet with allocation pools and gateway IP: JSON response

{
    "allocation_pools": [
        {
            "end": "192.168.62.21",
            "start": "192.168.62.11"
        },
        {
            "end": "192.168.62.251",
            "start": "192.168.62.241"
        }
    ],
    "cidr": "192.168.62.0/24",
    "dns_nameservers": [],
    "enable_dhcp": false,
    "gateway_ip": "192.168.62.1",
    "host_routes": [],
    "id": "bbda1637-79df-4ec6-8399-baa8e01dda22",
    "ip_version": 4,
    "name": "",
    "network_id": "c23f2b6c-efa1-4b66-8bdf-34cda87b8102",
    "tenant_id": "546428"
}

Show subnet#

GET /v2.0/subnets/{subnet_id}

This operation retrieves information for a specified subnet.

You can control which attributes are returned by using the fields query parameter. For more information, see Filtering Requests.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	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
{subnet_id}	Uuid	The UUID for the subnet.

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
subnet	Object	The container of subnet details.
subnet.name	String	The subnet name.
subnet.enable_dhcp	Boolean	Indicates if DHCP for the subnet is enabled. This value is `false` and cannot be changed.
subnet.network_id	Uuid	The ID of the attached network.
subnet.tenant_id	Uuid	The ID of the tenant who owns the subnet.
subnet.dns_nameservers	Array	The array of dns name servers for the subnet.
subnet.allocation_pools	Array	The array of allocation pool objects.
subnet.allocation_pools.end	String	The ending IP address of the subnet allocation pool.
subnet.allocation_pools.start	String	The starting IP address of the subnet allocation pool.
subnet.host_routes	Array	The array of host routes for the subnet.
subnet.ip_version	String	The subnet IP version, which is `4` or `6`.
subnet.gateway_ip	String	The gateway IP address.
subnet.cidr	String	The CIDR for the subnet.
subnet.id	Uuid	The ID of the subnet.

Example Show subnet: JSON response

{
    "subnet": {
        "name": "my_subnet",
        "enable_dhcp": false,
        "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
        "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
        "dns_nameservers": [
        ],
        "allocation_pools": [
            {
                "start": "192.0.0.2",
                "end": "192.255.255.254"
            }
        ],
        "host_routes":[
        ],
        "ip_version": 4,
        "gateway_ip": "192.0.0.1",
        "cidr": "192.0.0.0/8",
        "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
    }
}

Update subnet#

PUT /v2.0/subnets/{subnet_id}

This operation updates a specified subnet.

The IP version ( ip_version ), network ID ( network_id ), and CIDR ( cidr ) cannot be updated. Attempting to update these parameters results in a 400 Bad Request error.

You cannot update allocation pools that are attached to a port.

Warning

If any attributes are updated, the changes will take effect only for ports or cloud servers using this subnet that are created after this modification. Any existing ports or servers are not updated.

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.
404	Not Found	Item not found.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{subnet_id}	Uuid	The UUID for the subnet.

This table shows the body parameters for the request:

Name	Type	Description
subnet	Object	The container for subnet details.
subnet.name	String	The subnet name.
subnet.gateway_ip	String	The gateway IP address.

Example Update subnet: JSON request

{
    "subnet": {
        "name": "private-subnet"
    }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
subnet	Object	The container for subnet details.
subnet.name	String	The subnet name.
subnet.enable_dhcp	Boolean	Indicates if DHCP for the subnet is enabled. This value is `false` and cannot be changed.
subnet.network_id	Uuid	The ID of the attached network.
subnet.tenant_id	Uuid	The tenant ID of the owner of the subnet. Only administrative users can specify a tenant ID other than their own.
subnet.dns_nameservers	Array	The array of DNS name servers for the subnet.
subnet.allocation_pools	Array	The array of allocation pool objects.
subnet.allocation_pools.end	String	The ending IP address of the subnet allocation pool.
subnet.allocation_pools.start	String	The starting IP address of the subnet allocation pool.
subnet.host_routes	Array	The array of host route IP addresses for the subnet.
subnet.ip_version	String	The subnet IP version, which is `4` or `6`.
subnet.gateway_ip	String	The subnet gateway IP address.
subnet.cidr	String	The subnet CIDR.
subnet.id	Uuid	The ID of the subnet.

Example Update subnet: JSON response

{
    "subnet": {
        "name": "private-subnet",
        "enable_dhcp": false,
        "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
        "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
        "dns_nameservers": [
        ],
        "allocation_pools": [
            {
                "start": "10.0.0.2",
                "end": "10.0.0.254"
            }
        ],
        "host_routes": [
        ],
        "ip_version": 4,
        "gateway_ip": "10.0.0.1",
        "cidr": "10.0.0.0/24",
        "id": "08eae331-0402-425a-923c-34f7cfe39c1b"
    }
}

Delete subnet#

DELETE /v2.0/subnets/{subnet_id}

This operation deletes a specified subnet.

The operation fails if the subnet IP addresses are still allocated.

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.
409	conflict	There is a resource conflict.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{subnet_id}	Uuid	The UUID for the subnet.

This operation does not accept a request body.

Response#

Example Delete subnet: JSON response

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