9.3. Creating virtual subnets

POST /v2.0/subnets

Create a subnet in a network.

OpenStack Networking does not try to derive the correct IP version from the CIDR. If you do not specify the gateway_ip attribute, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet.

To specify a subnet without a gateway, set the gateway_ip attribute to null in the request body. If you do not specify the allocation_pools attribute, OpenStack Networking 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.

When you specify both the allocation_pools and gateway_ip attributes, you must ensure that the gateway IP does not overlap with the allocation pools; otherwise, the call returns the Conflict (409) response code.

A subnet can have one or more name servers and host routes. Hosts in this subnet use the name servers. Devices with IP addresses from this subnet, not including the local subnet route, use the host routes.

Specify the ipv6_ra_mode and ipv6_address_mode attributes to create subnets that support IPv6 configurations, such as stateless address autoconfiguration (SLAAC), DHCPv6 stateful, and DHCPv6 stateless configurations.

A subnet can optionally be associated with a network segment when it is created by specifying the segment_id of a valid segment on the specified network. A network with subnets associated in this way is called a routed network. On any given network, all of the subnets must be associated with segments or none of them can be. Neutron enforces this invariant. Currently, routed networks are only supported for provider networks.

Source: https://docs.openstack.org/api-ref/network/v2/index.html#create-subnet

9.3.1. Request

Name In Type Description
subnet body object A subnet object.
tenant_id (Optional) body string The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.
project_id (Optional) body string The ID of the project that owns the resource. Only administrative and users with advsvc role can specify a project ID other than their own. You cannot change this value through authorization policies.
name (Optional) body string Human-readable name of the resource. Default is an empty string.
enable_dhcp (Optional) body boolean Indicates whether dhcp is enabled or disabled for the subnet. Default is true.
network_id body string The ID of the network to which the subnet belongs.
dns_nameservers (Optional) body array List of dns name servers associated with the subnet. Default is an empty list.
allocation_pools (Optional) body array Allocation pools with start and end IP addresses for this subnet. If allocation_pools are not specified, OpenStack Networking automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway by default.
host_routes (Optional) body array Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters. Default value is an empty list.
ip_version body integer The IP protocol version. Value is 4 or 6.
gateway_ip (Optional) body string Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet. If the gateway_ip is not specified, OpenStack Networking allocates an address from the CIDR for the gateway for the subnet by default.
cidr body string The CIDR of the subnet.
prefixlen (Optional) body integer The prefix length to use for subnet allocation from a subnet pool. If not specified, the default_prefixlen value of the subnet pool will be used.
description (Optional) body string A human-readable description for the resource. Default is an empty string.
ipv6_address_mode (Optional) body string The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless.
ipv6_ra_mode (Optional) body string The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless.
segment_id (Optional) body string The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.
subnetpool_id (Optional) body string The ID of the subnet pool associated with the subnet.
use_default_subnetpool (Optional) body boolean Whether to allocate this subnet from the default subnet pool.
service_types (Optional) body array The service types associated with the subnet.
dns_publish_fixed_ip (Optional) body boolean Whether to publish DNS records for IPs from this subnet. Default is false.

9.3.1.1. Examples

Create a subnet with enabled DHCP, an allocation pool, a gateway, a DNS. Attach it to a network with the specified ID.

For a private network:

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d'
{                                    
  "subnet": {
    "enable_dhcp": true,
    "network_id": "c5252a20-9206-4b8e-9a0f-45bd22ee7bc8",
    "dns_nameservers": [
      "10.30.0.27",
      "10.30.0.28"
    ],
    "allocation_pools": [
      {
        "start": "192.168.10.2",
        "end": "192.168.10.254"
      }
    ],
    "ip_version": 4,
    "gateway_ip": "192.168.10.1",
    "cidr": "192.168.10.0/24"
  }
}' https://<node_IP_addr>:9696/v2.0/subnets

For a public network:

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
  "subnet": {
    "enable_dhcp": true,
    "network_id": "c5a5d68e-55cd-40b8-a272-3768cbb86bd1",
    "dns_nameservers": [
      "10.30.0.27",
      "10.30.0.28"
    ],
    "allocation_pools": [
      {
        "start": "10.94.139.168",
        "end": "10.94.139.175"
      }
    ],
    "ip_version": 4,
    "gateway_ip": "10.94.0.1",
    "cidr": "10.94.0.0/16"
  }
}' https://<node_IP_addr>:9696/v2.0/subnets

9.3.2. Response

Name In Type Description
subnet body object A subnet object.
id body string The ID of the subnet.
tenant_id body string The ID of the project.
project_id body string The ID of the project.
name body string Human-readable name of the resource.
enable_dhcp body boolean Indicates whether dhcp is enabled or disabled for the subnet.
network_id body string The ID of the network to which the subnet belongs.
dns_nameservers body array List of dns name servers associated with the subnet.
allocation_pools body array Allocation pools with start and end IP addresses for this subnet.
host_routes body array Additional routes for the subnet. A list of dictionaries with destination and nexthop parameters.
ip_version body integer The IP protocol version. Value is 4 or 6.
gateway_ip body string Gateway IP of this subnet. If the value is null that implies no gateway is associated with the subnet.
cidr body string The CIDR of the subnet.
created_at body string Time at which the resource has been created (in UTC ISO8601 format).
description body string A human-readable description for the resource.
ipv6_address_mode body string The IPv6 address modes specifies mechanisms for assigning IP addresses. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.
ipv6_ra_mode body string The IPv6 router advertisement specifies whether the networking service should transmit ICMPv6 packets, for a subnet. Value is slaac, dhcpv6-stateful, dhcpv6-stateless or null.
revision_number body integer The revision number of the resource.
service_types body array The service types associated with the subnet.
subnetpool_id body string The ID of the subnet pool associated with the subnet.
segment_id body string The ID of a network segment the subnet is associated with. It is available when segment extension is enabled.
updated_at body string Time at which the resource has been updated (in UTC ISO8601 format).
tags body array The list of tags on the resource.
dns_publish_fixed_ip body boolean Whether to publish DNS records for IPs from this subnet.

9.3.2.1. Status codes

9.3.2.1.1. Success

Code Reason
201 - Created Resource was created and is ready to use.

9.3.2.1.2. Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.

9.3.2.2. Examples

Subnet for a private network:

{
  "subnet": {
    "service_types": [],
    "description": "",
    "enable_dhcp": true,
    "tags": [],
    "network_id": "c5252a20-9206-4b8e-9a0f-45bd22ee7bc8",
    "tenant_id": "f5d834d636c642c7bfe8af86139c6f26",
    "created_at": "2020-02-14T13:42:56Z",
    "dns_nameservers": [
      "10.30.0.27",
      "10.30.0.28"
    ],
    "updated_at": "2020-02-14T13:42:56Z",
    "gateway_ip": "192.168.10.1",
    "ipv6_ra_mode": null,
    "allocation_pools": [
      {
        "start": "192.168.10.2",
        "end": "192.168.10.254"
      }
    ],
    "host_routes": [],
    "revision_number": 0,
    "ip_version": 4,
    "ipv6_address_mode": null,
    "cidr": "192.168.10.0/24",
    "project_id": "f5d834d636c642c7bfe8af86139c6f26",
    "id": "aa29d149-b2a4-45a0-8066-dc63fa9c9b77",
    "subnetpool_id": null,
    "name": ""
  }
}

Subnet for a public network:

{
  "subnet": {
    "service_types": [],
    "description": "",
    "enable_dhcp": true,
    "tags": [],
    "network_id": "c5a5d68e-55cdl-40b8-a272-3768cbb86bd1",
    "tenant_id": "f5d834d636c642c7bfe8af86139c6f26",
    "created_at": "2020-02-17T11:30:30Z",
    "dns_nameservers": [
      "10.30.0.27",
      "10.30.0.28"
    ],
    "updated_at": "2020-02-17T11:30:30Z",
    "gateway_ip": "10.94.0.1",
    "ipv6_ra_mode": null,
    "allocation_pools": [
      {
        "start": "10.94.139.168",
        "end": "10.94.139.175"
      }
    ],
    "host_routes": [],
    "revision_number": 0,
    "ip_version": 4,
    "ipv6_address_mode": null,
    "cidr": "10.94.0.0/16",
    "project_id": "f5d834d636c642c7bfe8af86139c6f26",
    "id": "5fc296ab-6f00-41ab-914d-0aea9c8da34f",
    "subnetpool_id": null,
    "name": ""
  }
}