10.2. Creating virtual routers

POST /v2.0/routers

Creates a logical router.

This operation creates a logical router. The logical router does not have any internal interface and it is not associated with any subnet. You can optionally specify an external gateway for a router at create time. The external gateway for the router must be plugged into an external network. An external network has its router:external extended field set to true. To specify an external gateway, the ID of the external network must be passed in the network_id parameter of the external_gateway_info attribute in the request body.

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

10.2.1. Request

Name In Type Description
router body object A router 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.
description (Optional) body string A human-readable description for the resource. Default is an empty string.
admin_state_up (Optional) body boolean The administrative state of the resource, which is up (true) or down (false). Default is true.
external_gateway_info (Optional) body object The external gateway information of the router. If the router has an external gateway, this would be a dictionary of network_id, enable_snat and external_fixed_ips. Otherwise, this would be null.
network_id body string Network ID which the router gateway is connected to.
enable_snat (Optional) body boolean Enable Source NAT (SNAT) attribute. Default is true. To persist this attribute value, set the enable_snat_by_default option in the neutron.conf file. It is available when ext-gw-mode extension is enabled.
external_fixed_ips (Optional) body array IP address(es) of the external gateway interface of the router. Use ip_version to automatically allocate an IP address from any subnet of the specified type.
external_fixed_ips.ip_version body integer The IP protocol version. Value is 4 or 6.
distributed (Optional) body boolean true indicates a distributed router. It is available when dvr extension is enabled.
ha (Optional) body boolean true indicates a highly-available router. It is available when l3-ha extension is enabled.
availability_zone_hints (Optional) body array The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.
service_type_id (Optional) body string The ID of the service type associated with the router.
flavor_id (Optional) body string The ID of the flavor associated with the router.

10.2.1.1. Example

Create a router with an attached public interface. You will need to specify the public network ID and the ID of its subnet.

The new interface will attempt to use the selected network’s gateway IP address by default. You can also pass a custom IP address from the selected network in the ip_address parameter.

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
  "router": {
    "name": "router1",
    "external_gateway_info": {
      "network_id": "b4907761-8c0f-447e-9cfe-c688ca6e44a0",
      "enable_snat": true,
      "external_fixed_ips": [
        {
          "ip_version": 4
        }
      ]
    }
  }
}' https://<node_IP_addr>:9696/v2.0/routers

10.2.2. Response

Name In Type Description
router body object A router object.
id body string The ID of the router.
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.
description body string A human-readable description for the resource.
admin_state_up body boolean The administrative state of the resource, which is up (true) or down (false).
status body string The router status.
external_gateway_info body object The external gateway information of the router. If the router has an external gateway, this would be a dictionary of network_id, enable_snat and external_fixed_ips. Otherwise, this would be null.
network_id body string Network ID which the router gateway is connected to.
enable_snat body boolean Enable Source NAT (SNAT) attribute. true means Network Address Translation (NAT) is enabled for traffic generated by subnets attached to the router when the traffic is sent to/received from the external network. false means no NAT is applied for traffic from/to the external network. It is available when ext-gw-mode extension is enabled.
external_fixed_ips body array IP address(es) of the external gateway of the router. It is a list of IP addresses. Each element of the list is a dictionary of ip_address and subnet_id.
revision_number body integer The revision number of the resource.
routes body array The extra routes configuration for L3 router. A list of dictionaries with destination and nexthop parameters. It is available when extraroute extension is enabled.
destination body string The destination CIDR.
nexthop body string The IP address of the next hop for the corresponding destination. The next hop IP address must be a part of one of the subnets to which the router interfaces are connected.
distributed body boolean true indicates a distributed router. It is available when dvr extension is enabled.
ha body boolean true indicates a highly-available router. It is available when l3-ha extension is enabled.
availability_zone_hints body array The availability zone candidates for the router. It is available when router_availability_zone extension is enabled.
availability_zones body array The availability zone(s) for the router. It is available when router_availability_zone extension is enabled.
service_type_id body string The ID of the service type associated with the router.
flavor_id body string The ID of the flavor associated with the router.
created_at body string Time at which the resource has been created (in UTC ISO8601 format).
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.
conntrack_helpers body array The associated conntrack helper resources for the roter. If the router has multiple conntrack helper resources, this field has multiple entries. Each entry consists of netfilter conntrack helper (helper), the network protocol (protocol), the network port (port).

10.2.2.1. Status codes

10.2.2.1.1. Success

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

10.2.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.

10.2.2.2. Example

{
  "router": {
    "status": "ACTIVE",
    "external_gateway_info": {
      "network_id": "b4907761-8c0f-447e-9cfe-c688ca6e44a0",
      "enable_snat": true,
      "external_fixed_ips": [
        {
          "subnet_id": "351884c7-ee37-4a7d-9dcb-4cff4a1bba27",
          "ip_address": "10.94.139.171"
        }
      ]
    },
    "availability_zone_hints": [],
    "availability_zones": [],
    "description": "",
    "tags": [],
    "tenant_id": "f5d834d636c642c7bfe8af86139c6f26",
    "created_at": "2020-03-04T16:12:16Z",
    "admin_state_up": true,
    "distributed": false,
    "updated_at": "2020-03-04T16:12:18Z",
    "project_id": "f5d834d636c642c7bfe8af86139c6f26",
    "flavor_id": null,
    "revision_number": 3,
    "routes": [],
    "ha": false,
    "id": "02542148-44cb-470d-a551-58f370c47b83",
    "name": "router1"
  }
}