10.1. Listing virtual routers

GET /v2.0/routers

Lists virtual routers that the project who submits the request can access.

Default policy settings return only those routers that the project who submits the request owns, unless an administrative user submits the request.

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

10.1.1. Request

Name In Type Description
id (Optional) query string Filter the list result by the ID of the resource.
tenant_id (Optional) query string Filter the list result by the ID of the project that owns the resource.
project_id (Optional) query string Filter the list result by the ID of the project that owns the resource.
name (Optional) query string Filter the list result by the human-readable name of the resource.
description (Optional) query string Filter the list result by the human-readable description of the resource.
admin_state_up (Optional) query boolean Filter the list result by the administrative state of the resource, which is up (true) or down (false).
revision_number (Optional) query integer Filter the list result by the revision number of the resource.
sort_dir (Optional) query string Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters.
sort_key (Optional) query string

Sorts by a router attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to:

  • admin_state_up
  • flavor_id
  • id
  • name
  • status
  • tenant_id
  • project_id
tags (Optional) query string A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma.
tags-any (Optional) query string A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma.
not-tags (Optional) query string A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma.
not-tags-any (Optional) query string A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma.
fields (Optional) query string The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using fields parameter, the API returns only the requested set of attributes. fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only id and name attributes will be returned.

10.1.1.1. Example

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://<node_IP_addr>:9696/v2.0/routers

10.1.2. Response

Name In Type Description
routers body array A list of router objects.
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.
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.1.2.1. Status codes

10.1.2.1.1. Success

Code Reason
200 - OK Request was successful.

10.1.2.1.2. Error

Code Reason
401 - Unauthorized User must authenticate before making a request.

10.1.2.2. Example

{
  "routers": [
    {
      "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.172"
          }
        ]
      },
      "availability_zone_hints": [],
      "availability_zones": [
        "nova"
      ],
      "description": "",
      "tags": [],
      "tenant_id": "f5d834d636c642c7bfe8af86139c6f26",
      "created_at": "2020-03-04T15:22:40Z",
      "admin_state_up": true,
      "distributed": false,
      "updated_at": "2020-03-04T15:22:44Z",
      "project_id": "f5d834d636c642c7bfe8af86139c6f26",
      "flavor_id": null,
      "revision_number": 4,
      "routes": [],
      "ha": false,
      "id": "ce996632-45a2-4c6b-a951-a624eba74621",
      "name": "router1"
    }
  ]
}