openstack/neutron-lib
Code Issues Proposed changes

api-ref: Fix api-ref for routers

Browse Source 
Also merge extraroute.inc into routers.inc as it is
an attribute extension to the router resource.

Part of blueprint neutron-in-tree-api-ref

Change-Id: If5bc158e1a208650ce6b1689ee9ce969024cfeb0
This commit is contained in:
Akihiro Motoki 2016-08-03 17:29:21 +09:00
parent 31816d2eb1
commit 9e178650e2
14 changed files with 746 additions and 634 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
api-ref/source/v2/extraroute.inc
View File

@ -1,83 +0,0 @@
.. -*- rst -*-
.. needs:method_verification
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
======================
Extra routes (routers)
======================
Adds extra routes to the ``router`` resource.
You can update a router to add a set of next hop IPs and
destination CIDRs.
The next hop IP must be part of a subnet to which the router
interfaces are connected. You can configure the ``routes``
attribute on only update operations.
Update extra routes
===================
.. rest_method:: PUT /v2.0/routers/{router_id}
Updates extra routes on a router.
The next hop IP address must be a part of one of the subnets to
which the router interfaces are connected. Otherwise, the server
responds with the ``Bad Request (400)`` error code.
When a validation error is detected, such as a format error of IP
address or CIDR, the server responds with the ``Bad Request (400)``
response code.
When Networking receives a request to delete the router interface
for subnets that are used by one or more routes, it responds with a
``Conflict (409)`` response code.
Normal response codes: 200
Error response codes: 404,409,401,400
Request
-------
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- destination: destination
- nexthop: nexthop
- routes: routes
- router: router
- external_fixed_ips: external_fixed_ips
- router_id: router_id
Request Example
---------------
.. literalinclude:: samples/routers/router-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- status: status
- enable_snat: enable_snat
- name: name
- admin_state_up: admin_state_up
- tenant_id: tenant_id
- routes: routes
- router: router
- id: id
- external_fixed_ips: external_fixed_ips
Response Example
----------------
.. literalinclude:: samples/routers/router-update-response.json
:language: javascript

1
api-ref/source/v2/index.rst
View File

@ -18,7 +18,6 @@ Networking API v2.0
.. include:: subnetpools.inc
.. include:: routers.inc
.. include:: floatingips.inc
.. include:: extraroute.inc
.. include:: security-groups.inc
.. include:: security-group-rules.inc
.. include:: quotas.inc

362
api-ref/source/v2/parameters.yaml
View File

@ -129,9 +129,9 @@ resource_type:
type: string
router_id:
description: |
The UUID of the router.
The ID of the router.
in: path
required: false
required: true
type: string
rule_id:
description: |
@ -186,6 +186,12 @@ vip_id_1:
fields:
description: |
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.
in: query
required: false
type: string
@ -263,9 +269,17 @@ address_scope_id_1:
type: string
admin_state_up:
description: |
The administrative state of the network, which is
The administrative state of the resource, which is
up (``true``) or down (``false``).
in: body
required: true
type: boolean
admin_state_up-request:
description: |
The administrative state of the resource, which is
up (``true``) or down (``false``).
Default is ``true``.
in: body
required: false
type: boolean
admin_state_up_1:
@ -727,8 +741,13 @@ delay_2:
type: integer
description:
description: |
The human-readable description for the firewall
policy.
The human-readable description for the resource.
in: body
required: true
type: string
description-request:
description: |
The human-readable description for the resource.
in: body
required: false
type: string
@ -952,12 +971,6 @@ description_9:
in: body
required: false
type: string
destination:
description: |
The destination CIDR.
in: body
required: false
type: string
destination_ip_address:
description: |
The destination IPv4 or IPv6 address or CIDR. No
@ -1041,12 +1054,6 @@ direction_2:
in: body
required: true
type: string
distributed:
description: |
If ``true``, indicates a distributed router.
in: body
required: true
type: boolean
dpd:
description: |
A dictionary with dead peer detection (DPD)
@ -1099,23 +1106,6 @@ dscp_marking_rules:
in: body
required: true
type: array
enable_snat:
description: |
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.
in: body
required: false
type: boolean
enable_snat_1:
description: |
Enable Source NAT (SNAT) attribute, a part of
ext-gw-mode extension. When a gateway is attached to a router
using an L3 extension, Network Address Translation (NAT) is
enabled for traffic generated by subnets attached to the router.
in: body
required: true
type: boolean
enabled:
description: |
Set to ``false`` to disable this rule in the
@ -1270,34 +1260,6 @@ extension:
in: body
required: true
type: object
external_fixed_ips:
description: |
The IP address parameters.
in: body
required: false
type: array
external_fixed_ips_1:
description: |
The IP address parameters.
in: body
required: true
type: array
external_gateway_info:
description: |
The external gateway parameters, which include
the ``network_id``, ``enable_snat`` and ``external_fixed_ips``
parameters.
in: body
required: false
type: object
external_gateway_info_1:
description: |
The external gateway parameters, which include
the ``network_id``, ``enable_snat`` and ``external_fixed_ips``
parameters.
in: body
required: true
type: object
external_v4_ip:
description: |
Read-only external (public) IPv4 address that is
@ -1515,12 +1477,6 @@ floatingips:
in: body
required: true
type: array
ha:
description: |
If ``true``, indicates a highly-available router.
in: body
required: true
type: boolean
health_monitor:
description: |
A ``health_monitor`` object.
@ -1692,12 +1648,6 @@ id_26:
in: body
required: true
type: string
id_27:
description: |
The UUID of the router.
in: body
required: true
type: string
id_28:
description: |
The UUID of the service profile.
@ -2191,7 +2141,14 @@ mtu_3:
type: integer
name:
description: |
The network name.
Human-readable name of the resource.
in: body
required: true
type: string
name-request:
description: |
Human-readable name of the resource.
Default is an empty string.
in: body
required: false
type: string
@ -2219,12 +2176,6 @@ name_12:
in: body
required: false
type: string
name_13:
description: |
The router name.
in: body
required: false
type: string
name_14:
description: |
A symbolic name for the security group. Does not
@ -2537,12 +2488,6 @@ networks:
in: body
required: true
type: array
nexthop:
description: |
The IP address of the next hop.
in: body
required: false
type: string
operating_status:
description: |
The operating status of the load balancer. This
@ -3108,6 +3053,204 @@ router:
in: body
required: true
type: object
router-availability_zone_hints:
description: |
The availability zone candidates for the router.
It is available when ``router_availability_zone`` extension is enabled.
in: body
required: true
type: array
router-availability_zone_hints-request:
description: |
The availability zone candidates for the router.
It is available when ``router_availability_zone`` extension is enabled.
in: body
required: false
type: array
router-availability_zones:
description: |
The availability zone(s) for the router.
It is available when ``router_availability_zone`` extension is enabled.
in: body
required: true
type: array
router-destination:
description: |
The destination CIDR.
in: body
required: true
type: string
router-distributed:
description: |
``true`` indicates a distributed router.
It is available when ``dvr`` extension is enabled.
in: body
required: true
type: boolean
router-distributed-request:
description: |
``true`` indicates a distributed router.
It is available when ``dvr`` extension is enabled.
in: body
required: false
type: boolean
router-enable_snat:
description: |
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.
in: body
required: true
type: boolean
router-enable_snat-request:
description: |
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.
in: body
required: false
type: boolean
router-external_fixed_ips:
description: |
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``.
in: body
required: true
type: array
router-external_fixed_ips-request:
description: |
IP address(es) of the external gateway interface of the router.
It is a list of IP addresses you would like to assign to the
external gateway interface. Each element of ths list is
a dictionary of ``ip_address`` and ``subnet_id``.
in: body
required: false
type: array
router-external_gateway_info:
description: |
The external gateway information of the router.
If the router has an external gateway, this would be a dict with
``network_id``, ``enable_snat`` and ``external_fixed_ips``.
Otherwise, this would be ``null``.
in: body
required: true
type: dict
router-external_gateway_info-request:
description: |
The external gateway information of the router.
If the router has an external gateway, this would be a dict with
``network_id``, ``enable_snat`` and ``external_fixed_ips``.
Otherwise, this would be ``null``.
in: body
required: false
type: dict
router-ha:
description: |
``true`` indicates a highly-available router.
It is available when ``l3-ha`` extension is enabled.
in: body
required: true
type: boolean
router-ha-request:
description: |
``true`` indicates a highly-available router.
It is available when ``l3-ha`` extension is enabled.
in: body
required: false
type: boolean
router-id-body:
description: |
The ID of the router.
in: body
required: true
type: string
router-name-request:
description: |
The router name.
in: body
required: false
type: string
router-network_id:
description: |
Network ID which the router gateway is connected to.
in: body
required: true
type: string
router-network_id-interface:
description: |
Network ID which the router interface is connected to.
in: body
required: true
type: string
router-nexthop:
description: |
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.
in: body
required: true
type: string
router-port_id:
description: |
The ID of the port which represents the router interface.
in: body
required: true
type: string
router-port_id-request:
description: |
The ID of the port.
One of ``subnet_id`` or ``port_id`` must be specified.
in: body
required: false
type: string
router-routes:
description: |
The extra routes configuration for L3 router.
A list of dictionaries with ``destination`` and ``nexthop`` parameters.
It is available when ``extraroute`` extension is enabled.
in: body
required: true
type: array
router-routes-request:
description: |
The extra routes configuration for L3 router.
A list of dictionaries with ``destination`` and ``nexthop`` parameters.
It is available when ``extraroute`` extension is enabled.
Default is an empty list (``[]``).
in: body
required: false
type: array
router-subnet_id:
description: |
The ID of the subnet which the router interface belongs to.
in: body
required: true
type: string
router-subnet_id-request:
description: |
The ID of the subnet.
One of ``subnet_id`` or ``port_id`` must be specified.
in: body
required: false
type: string
router-subnet_ids:
description: |
A list of the ID of the subnet which the router interface belongs to.
The list contains only one member.
in: body
required: true
type: array
router-tenant_id-interface:
description: |
The ID of the tenant who owns the router interface.
in: body
required: true
type: string
router:external:
description: |
Indicates whether this network is externally
@ -3168,33 +3311,18 @@ router_ids_1:
in: body
required: true
type: array
router_status:
description: |
The router status.
in: body
required: true
type: string
routers:
description: |
A list of ``router`` objects.
in: body
required: true
type: array
routes:
description: |
The extra routes configuration for L3 router.
in: body
required: true
type: array
routes_1:
description: |
A list of dictionary pairs in this format:
::
[
{
"nexthop":"IPADDRESS",
"destination":"CIDR"
}
]
in: body
required: false
type: object
security_group:
description: |
A ``security_group`` object.
@ -3621,12 +3749,6 @@ subnet_id_4:
in: body
required: true
type: string
subnet_id_5:
description: |
The UUID of the subnet.
in: body
required: true
type: string
subnet_id_6:
description: |
If you omit this parameter, LBaaS uses the
@ -3701,9 +3823,15 @@ tags:
type: array
tenant_id:
description: |
The UUID of the tenant who owns the network. Only
administrative users can specify a tenant UUID other than their
own. You cannot change this value through authorization policies.
The ID of the tenant who owns the resource.
in: body
required: true
type: string
tenant_id-request:
description: |
The ID of the tenant who owns the resource.
Only administrative users can specify a tenant UUID other than their own.
You cannot change this value through authorization policies.
in: body
required: false
type: string

749
api-ref/source/v2/routers.inc
View File

@ -1,350 +1,26 @@
.. -*- rst -*-
.. needs:method_verification
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
=================
Routers (routers)
=================
Routes packets between subnets, forwards packets from internal
networks to external ones, and accesses instances from external
networks through floating IPs.
A ``router`` is a logical entity for forwarding packets across
internal subnets and NATting them on external networks through an
appropriate external gateway.
This extension introduces these resources:
- **router**. A logical entity for forwarding packets across
internal subnets and NATting them on external networks through an
appropriate external gateway.
- **floatingip**. An external IP address that you map to a port in
an internal network.
Add interface to router
=======================
.. rest_method:: PUT /v2.0/routers/{router_id}/add_router_interface
Adds an internal interface to a logical router.
Attaches a subnet to an internal router interface.
Specify the UUID of a subnet or port in the request body:
- Subnet UUID. The gateway IP address for the subnet is used to
create the router interface.
- Port UUID. The IP address associated with the port is used to
create the router interface.
When you specify an IPv6 subnet, this operation adds the subnet to
an existing internal port with same network UUID, on the router. If
a port with the same network UUID does not exist, this operation
creates a port on the router for that subnet.
The limitation of one IPv4 subnet per router port remains, though a
port can contain any number of IPv6 subnets that belong to the same
network UUID.
When you use the ``port-create`` command to add a port and then
call ``router-interface-add`` with this port UUID, this operation
adds the port to the router if the following conditions are met:
- The port has no more than one IPv4 subnet.
The IPv6 subnets, if any, on the port do not have same network
UUID as the network UUID of IPv6 subnets on any other ports.
If you specify both UUIDs, this operation returns the ``Bad Request
(400)`` response code.
If the port is already in use, this operation returns the
``Conflict (409)`` response code.
This operation returns a port UUID that is either:
- The same UUID that is passed in the request body.
- The UUID of a port that this operation creates to attach the
subnet to the router.
After you run this operation, the operation sets:
- The device UUID of this port to the router UUID.
- The ``device_owner`` attribute to ``network:router_interface``.
Normal response codes: 200
Error response codes: 404,409,401,400
Request
-------
.. rest_parameters:: parameters.yaml
- subnet_id: subnet_id
- port_id: port_id
- router_id: router_id
Request Example
---------------
.. literalinclude:: samples/routers/router-add-interface-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- subnet_id: subnet_id
- tenant_id: tenant_id
- port_id: port_id
- id: id
Response Example
----------------
.. literalinclude:: samples/routers/router-add-interface-response.json
:language: javascript
Delete interface from router
============================
.. rest_method:: PUT /v2.0/routers/{router_id}/remove_router_interface
Deletes an internal interface from a logical router.
This operation deletes an internal router interface, which detaches
a subnet from the router. If this subnet UUID is the last subnet on
the port, this operation deletes the port itself. You must specify
either a subnet UUID or port UUID in the request body; the
operation uses this value to identify which router interface to
deletes.
You can also specify both a subnet UUID and port UUID. If you
specify both UUIDs, the subnet UUID must correspond to the subnet
UUID of the first IP address on the port. Otherwise, this operation
returns the ``Conflict (409)`` response code with information about
the affected router and interface.
If the router or the subnet and port do not exist or are not
visible to you, this operation returns the ``Not Found (404)``
response code. As a consequence of this operation, the operation
removes the port connecting the router with the subnet from the
subnet for the network.
This example deletes an interface from a router:
::
PUT /v2.0/routers/{router_id}/remove_router_interface Accept: application/json
Normal response codes: 200
Error response codes: 404,409,401,400
Request
-------
.. rest_parameters:: parameters.yaml
- subnet_id: subnet_id
- port_id: port_id
- router_id: router_id
Request Example
---------------
.. literalinclude:: samples/routers/router-remove-interface-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- subnet_id: subnet_id
- tenant_id: tenant_id
- port_id: port_id
- id: id
Response Example
----------------
.. literalinclude:: samples/routers/router-remove-interface-response.json
:language: javascript
Show router details
===================
.. rest_method:: GET /v2.0/routers/{router_id}
Shows details for a router.
This example request shows details for a router in JSON format:
::
GET /v2.0/routers/{router_id} Accept: application/json
Use the ``fields`` query parameter to control which fields are
returned in the response body. For information, see `Filtering and
Column Selection <http://specs.openstack.org/openstack/neutron-
specs/specs/api/networking_general_api_information.html#filtering-
and-column-selection>`__.
Normal response codes: 200
Error response codes: 404,403,401
Request
-------
.. rest_parameters:: parameters.yaml
- router_id: router_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- status: status
- availability_zone_hints: availability_zone_hints
- availability_zones: availability_zones
- name: name
- admin_state_up: admin_state_up
- tenant_id: tenant_id
- distributed: distributed
- enable_snat: enable_snat
- routes: routes
- router: router
- ha: ha
- id: id
- external_fixed_ips: external_fixed_ips
Response Example
----------------
.. literalinclude:: samples/routers/router-show-response.json
:language: javascript
Update router
=============
.. rest_method:: PUT /v2.0/routers/{router_id}
Updates a logical router.
You can update the name, administrative state, and the external
gateway. For more information about how to set the external gateway
for a router, see the create router operation. This operation does
not enable the update of router interfaces. To update a router, use
the add router interface and remove router interface operations.
This example updates the external gateway information for a router:
::
PUT /v2.0/routers/{router_id} Accept: application/json
Normal response codes: 200
Error response codes: 404,401,400
Request
-------
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- enable_snat: enable_snat
- name: name
- admin_state_up: admin_state_up
- router: router
- external_fixed_ips: external_fixed_ips
- router_id: router_id
Request Example
---------------
.. literalinclude:: samples/routers/router-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- status: status
- availability_zone_hints: availability_zone_hints
- availability_zones: availability_zones
- name: name
- admin_state_up: admin_state_up
- tenant_id: tenant_id
- distributed: distributed
- enable_snat: enable_snat
- routes: routes
- router: router
- ha: ha
- id: id
- external_fixed_ips: external_fixed_ips
Response Example
----------------
.. literalinclude:: samples/routers/router-update-response.json
:language: javascript
Delete router
=============
.. rest_method:: DELETE /v2.0/routers/{router_id}
Deletes a logical router and, if present, its external gateway interface.
This operation fails if the router has attached interfaces.
Use the remove router interface operation to remove all router
interfaces before you delete the router.
This example deletes a router:
::
DELETE /v2.0/routers/{router_id} Accept: application/json
Error response codes: 409,404,204,401
Request
-------
.. rest_parameters:: parameters.yaml
- router_id: router_id
This resource is provided when ``router`` extension is enabled.
List routers
============
.. rest_method:: GET /v2.0/routers
Lists logical routers that the tenant who submits the request can access.
Lists logical routers that the project who submits the request can access.
Default policy settings return only those routers that the tenant
Default policy settings return only those routers that the project
who submits the request owns, unless an administrative user submits
the request.
This example request lists routers in JSON format:
::
GET /v2.0/routers Accept: application/json
Use the ``fields`` query parameter to control which fields are
returned in the response body. Additionally, you can filter results
by using query string parameters. For information, see `Filtering
@ -358,25 +34,33 @@ Error response codes: 401
Request
-------
.. rest_parameters:: parameters.yaml
- fields: fields
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- status: status
- availability_zone_hints: availability_zone_hints
- availability_zones: availability_zones
- name: name
- admin_state_up: admin_state_up
- routers: routers
- distributed: distributed
- enable_snat: enable_snat
- id: router-id-body
- tenant_id: tenant_id
- routes: routes
- ha: ha
- id: id
- external_fixed_ips: external_fixed_ips
- name: name
- description: description
- admin_state_up: admin_state_up
- status: router_status
- external_gateway_info: router-external_gateway_info
- network_id: router-network_id
- enable_snat: router-enable_snat
- external_fixed_ips: router-external_fixed_ips
- routes: router-routes
- destination: router-destination
- nexthop: router-nexthop
- distributed: router-distributed
- ha: router-ha
- availability_zone_hints: router-availability_zone_hints
- availability_zones: router-availability_zones
Response Example
----------------
@ -397,33 +81,31 @@ 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 UUID of the external network must be passed
in the ``external_gateway_info`` attribute in the request body, as
follows:
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.
.. code-block:: json
Normal response codes: 201
{
"router": {
"external_gateway_info": {
"network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b"
}
}
}
Error response codes: 201,401,400
Error response codes: 400, 401
Request
-------
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- enable_snat: enable_snat
- name: name
- admin_state_up: admin_state_up
- router: router
- external_fixed_ips: external_fixed_ips
- tenant_id: tenant_id-request
- name: name-request
- description: description-request
- admin_state_up: admin_state_up-request
- external_gateway_info: router-external_gateway_info-request
- network_id: router-network_id
- enable_snat: router-enable_snat-request
- external_fixed_ips: router-external_fixed_ips-request
- distributed: router-distributed-request
- ha: router-ha-request
- availability_zone_hints: router-availability_zone_hints-request
Request Example
---------------
@ -436,18 +118,341 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- external_gateway_info: external_gateway_info
- status: status
- availability_zone_hints: availability_zone_hints
- availability_zones: availability_zones
- router: router
- id: router-id-body
- tenant_id: tenant_id
- name: name
- description: description
- admin_state_up: admin_state_up
- status: router_status
- external_gateway_info: router-external_gateway_info
- network_id: router-network_id
- enable_snat: router-enable_snat
- external_fixed_ips: router-external_fixed_ips
- routes: router-routes
- destination: router-destination
- nexthop: router-nexthop
- distributed: router-distributed
- ha: router-ha
- availability_zone_hints: router-availability_zone_hints
- availability_zones: router-availability_zones
Response Example
----------------
.. literalinclude:: samples/routers/router-create-response.json
:language: javascript
Show router details
===================
.. rest_method:: GET /v2.0/routers/{router_id}
Shows details for a router.
Use the ``fields`` query parameter to control which fields are
returned in the response body. For information, see `Filtering and
Column Selection <http://specs.openstack.org/openstack/neutron-
specs/specs/api/networking_general_api_information.html#filtering-
and-column-selection>`__.
Normal response codes: 200
Error response codes: 401, 403, 404
Request
-------
.. rest_parameters:: parameters.yaml
- router_id: router_id
- fields: fields
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- router: router
- id: router-id-body
- tenant_id: tenant_id
- name: name
- description: description
- admin_state_up: admin_state_up
- status: router_status
- external_gateway_info: router-external_gateway_info
- network_id: router-network_id
- enable_snat: router-enable_snat
- external_fixed_ips: router-external_fixed_ips
- routes: router-routes
- destination: router-destination
- nexthop: router-nexthop
- distributed: router-distributed
- ha: router-ha
- availability_zone_hints: router-availability_zone_hints
- availability_zones: router-availability_zones
Response Example
----------------
.. literalinclude:: samples/routers/router-show-response.json
:language: javascript
Update router
=============
.. rest_method:: PUT /v2.0/routers/{router_id}
Updates a logical router.
This operation does not enable the update of router interfaces.
To update a router intreface, use the add router interface and
remove router interface operations.
Normal response codes: 200
Error response codes: 400, 401, 404
Request
-------
.. rest_parameters:: parameters.yaml
- router: router
- external_gateway_info: router-external_gateway_info
- enable_snat: router-enable_snat
- name: name
- admin_state_up: admin_state_up
- tenant_id: tenant_id
- distributed: distributed
- enable_snat: enable_snat
- routes: routes
- router: router
- ha: ha
- id: id
- external_fixed_ips: external_fixed_ips
- external_fixed_ips: router-external_fixed_ips
- router_id: router_id
Request Example
---------------
.. literalinclude:: samples/routers/router-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- router: router
- id: router-id-body
- tenant_id: tenant_id
- name: name
- description: description
- admin_state_up: admin_state_up
- status: router_status
- external_gateway_info: router-external_gateway_info
- network_id: router-network_id
- enable_snat: router-enable_snat
- external_fixed_ips: router-external_fixed_ips
- routes: router-routes
- destination: router-destination
- nexthop: router-nexthop
- distributed: router-distributed
- ha: router-ha
- availability_zone_hints: router-availability_zone_hints
- availability_zones: router-availability_zones
Response Example
----------------
.. literalinclude:: samples/routers/router-update-response.json
:language: javascript
Delete router
=============
.. rest_method:: DELETE /v2.0/routers/{router_id}
Deletes a logical router and, if present, its external gateway interface.
This operation fails if the router has attached interfaces.
Use the remove router interface operation to remove all router
interfaces before you delete the router.
Normal response codes: 204
Error response codes: 401, 404, 409
Request
-------
.. rest_parameters:: parameters.yaml
- router_id: router_id
Response
--------
There is no body content for the response of a successful DELETE request.
Add interface to router
=======================
.. rest_method:: PUT /v2.0/routers/{router_id}/add_router_interface
Adds an internal interface to a logical router.
This means a specified subnet is attached to a router
as an internal router interface.
Specify the ID of a subnet or port in the request body:
- Subnet ID. The gateway IP address for the subnet is used as
an IP address of the created router interface.
- Port ID. The IP address associated with the port is used as
an IP address of the created router interface.
When you specify an IPv6 subnet, this operation adds the subnet to
an existing internal port with same network ID, on the router. If
a port with the same network ID does not exist, this operation
creates a port on the router for that subnet.
The limitation of one IPv4 subnet per router port remains, though a
port can contain any number of IPv6 subnets that belong to the same
network ID.
When you use the ``port-create`` command to add a port and then
call ``router-interface-add`` with this port ID, this operation
adds the port to the router if the following conditions are met:
- The port has no more than one IPv4 subnet.
- The IPv6 subnets, if any, on the port do not have same network
ID as the network ID of IPv6 subnets on any other ports.
If you specify both subnet ID and port ID,
this operation returns the ``Bad Request (400)`` response code.
If the port is already in use, this operation returns the
``Conflict (409)`` response code.
This operation returns a port ID that is either:
- The same ID that is passed in the request body
when a port is specified.
- The ID of a port that this operation creates to attach the
subnet to the router.
After you run this operation, the operation sets:
- The ``device_id`` attribute of this port to the router ID
- The ``device_owner`` attribute to ``network:router_interface``
Normal response codes: 200
Error response codes: 400, 401, 404, 409
Request
-------
.. rest_parameters:: parameters.yaml
- router_id: router_id
- subnet_id: router-subnet_id-request
- port_id: router-port_id-request
Request Example
---------------
.. literalinclude:: samples/routers/router-add-interface-request.json
:language: javascript
or
.. literalinclude:: samples/routers/router-add-interface-request-with-port.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: router-id-body
- subnet_id: router-subnet_id
- subnet_ids: router-subnet_ids
- tenant_id: router-tenant_id-interface
- port_id: router-port_id
- network_id: router-network_id-interface
Response Example
----------------
.. literalinclude:: samples/routers/router-add-interface-response.json
:language: javascript
Remove interface from router
============================
.. rest_method:: PUT /v2.0/routers/{router_id}/remove_router_interface
Deletes an internal interface from a logical router.
This operation deletes an internal router interface, which detaches
a subnet from the router. If this subnet ID is the last subnet on
the port, this operation deletes the port itself. You must specify
either a subnet ID or port ID in the request body; the
operation uses this value to identify which router interface to
deletes.
You can also specify both a subnet ID and port ID. If you
specify both IDs, the subnet ID must correspond to the subnet
ID of the first IP address on the port. Otherwise, this operation
returns the ``Conflict (409)`` response code with information about
the affected router and interface.
If you try to delete the router interface for subnets that are used
by one or more ``routes``, this operation returns the ``Conflict (409)``
response. In this case, you first need to delete such routes from
the router.
If the router or the subnet and port do not exist or are not
visible to you, this operation returns the ``Not Found (404)``
response code. As a consequence of this operation, the operation
removes the port connecting the router with the subnet from the
subnet for the network.
Normal response codes: 200
Error response codes: 400, 401, 404, 409
Request
-------
.. rest_parameters:: parameters.yaml
- router_id: router_id
- subnet_id: router-subnet_id-request
- port_id: router-port_id-request
Request Example
---------------
.. literalinclude:: samples/routers/router-remove-interface-request.json
:language: javascript
or
.. literalinclude:: samples/routers/router-remove-interface-request-with-port.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: router-id-body
- subnet_id: router-subnet_id
- subnet_ids: router-subnet_ids
- tenant_id: router-tenant_id-interface
- port_id: router-port_id
- network_id: router-network_id-interface
Response Example
----------------
.. literalinclude:: samples/routers/router-remove-interface-response.json
:language: javascript

3
api-ref/source/v2/samples/routers/router-add-interface-request-with-port.json Normal file
View File

@ -0,0 +1,3 @@
{
"port_id": "2dc46bcc-d1f2-4077-b99e-91ee28afaff0"
}

7
api-ref/source/v2/samples/routers/router-add-interface-response.json
View File

@ -1,9 +1,10 @@
{
"id": "915a14a6-867b-4af7-83d1-70efceb146f9",
"network_id": "91c013e2-d65a-474e-9177-c3e1799ca726",
"port_id": "2dc46bcc-d1f2-4077-b99e-91ee28afaff0",
"subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1",
"tenant_id": "6ba032e4730d42e2ad928f430f5da33e",
"subnet_ids": [
"a2f1f29d-571b-4533-907f-5803ab96ead1"
],
"port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4",
"id": "b0294d7e-7da4-4202-9882-2ab1de9dabc0"
"tenant_id": "0bd18306d801447bb457a46252d82d13"
}

8
api-ref/source/v2/samples/routers/router-create-request.json
View File

@ -1,13 +1,13 @@
{
"router": {
"name": "another_router",
"name": "router1",
"external_gateway_info": {
"network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
"network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3",
"enable_snat": true,
"external_fixed_ips": [
{
"subnet_id": "255.255.255.0",
"ip": "192.168.10.1"
"ip_address": "172.24.4.6",
"subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
}
]
},

27
api-ref/source/v2/samples/routers/router-create-response.json
View File

@ -1,22 +1,27 @@
{
"router": {
"status": "ACTIVE",
"admin_state_up": true,
"availability_zone_hints": [],
"availability_zones": [
"nova"
],
"description": "",
"distributed": false,
"external_gateway_info": {
"network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
"enable_snat": true,
"external_fixed_ips": [
{
"subnet_id": "255.255.255.0",
"ip": "192.168.10.2"
"ip_address": "172.24.4.6",
"subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
}
]
],
"network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
},
"name": "another_router",
"admin_state_up": true,
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
"distributed": false,
"routes": [],
"ha": false,
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
"id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
"name": "router1",
"routes": [],
"status": "ACTIVE",
"tenant_id": "0bd18306d801447bb457a46252d82d13"
}
}

3
api-ref/source/v2/samples/routers/router-remove-interface-request-with-port.json Normal file
View File

@ -0,0 +1,3 @@
{
"port_id": "2dc46bcc-d1f2-4077-b99e-91ee28afaff0"
}

12
api-ref/source/v2/samples/routers/router-remove-interface-response.json
View File

@ -1,6 +1,10 @@
{
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e",
"tenant_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
"port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4",
"subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"
"id": "915a14a6-867b-4af7-83d1-70efceb146f9",
"network_id": "91c013e2-d65a-474e-9177-c3e1799ca726",
"port_id": "a5b7d209-dc02-4c46-a51f-805eadd3de64",
"subnet_id": "4e5fe97c-82bc-432e-87d8-06d7e157dffa",
"subnet_ids": [
"4e5fe97c-82bc-432e-87d8-06d7e157dffa"
],
"tenant_id": "0bd18306d801447bb457a46252d82d13"
}

27
api-ref/source/v2/samples/routers/router-show-response.json
View File

@ -1,20 +1,31 @@
{
"router": {
"status": "ACTIVE",
"admin_state_up": true,
"availability_zone_hints": [],
"availability_zones": [
"nova"
],
"description": "",
"distributed": false,
"external_gateway_info": {
"network_id": "85d76829-6415-48ff-9c63-5c5ca8c61ac6",
"enable_snat": true,
"external_fixed_ips": [
{
"subnet_id": "255.255.255.0",
"ip": "192.168.10.2"
"ip_address": "172.24.4.6",
"subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
},
{
"ip_address": "2001:db8::9",
"subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
}
]
],
"network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
},
"ha": false,
"id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
"name": "router1",
"admin_state_up": true,
"tenant_id": "d6554fe62e2f41efbb6e026fad5c1542",
"routes": [],
"id": "a07eea83-7710-4860-931b-5fe220fae533"
"status": "ACTIVE",
"tenant_id": "0bd18306d801447bb457a46252d82d13"
}
}

6
api-ref/source/v2/samples/routers/router-update-request.json
View File

@ -1,12 +1,12 @@
{
"router": {
"external_gateway_info": {
"network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
"network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3",
"enable_snat": true,
"external_fixed_ips": [
{
"subnet_id": "255.255.255.0",
"ip": "192.168.10.1"
"ip_address": "172.24.4.6",
"subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
}
]
}

27
api-ref/source/v2/samples/routers/router-update-response.json
View File

@ -1,22 +1,27 @@
{
"router": {
"status": "ACTIVE",
"admin_state_up": true,
"availability_zone_hints": [],
"availability_zones": [
"nova"
],
"description": "",
"distributed": false,
"external_gateway_info": {
"network_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",
"enable_snat": true,
"external_fixed_ips": [
{
"subnet_id": "255.255.255.0",
"ip": "192.168.10.2"
"ip_address": "172.24.4.6",
"subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
}
]
],
"network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
},
"name": "another_router",
"admin_state_up": true,
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
"distributed": false,
"routes": [],
"ha": false,
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
"id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
"name": "router1",
"routes": [],
"status": "ACTIVE",
"tenant_id": "0bd18306d801447bb457a46252d82d13"
}
}

65
api-ref/source/v2/samples/routers/routers-list-response.json
View File

@ -1,31 +1,62 @@
{
"routers": [
{
"status": "ACTIVE",
"external_gateway_info": null,
"name": "second_routers",
"admin_state_up": true,
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
"routes": [],
"id": "7177abc4-5ae9-4bb7-b0d4-89e94a4abf3b"
},
{
"status": "ACTIVE",
"availability_zone_hints": [],
"availability_zones": [
"nova"
],
"description": "",
"distributed": false,
"external_gateway_info": {
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
"enable_snat": true,
"external_fixed_ips": [
{
"subnet_id": "255.255.255.0",
"ip": "192.168.10.2"
"ip_address": "172.24.4.3",
"subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
},
{
"ip_address": "2001:db8::c",
"subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
}
]
],
"network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
},
"name": "router1",
"admin_state_up": true,
"tenant_id": "33a40233088643acb66ff6eb0ebea679",
"ha": false,
"id": "915a14a6-867b-4af7-83d1-70efceb146f9",
"name": "router2",
"routes": [],
"id": "a9254bdb-2613-4a13-ac4c-adc581fba50d"
"status": "ACTIVE",
"tenant_id": "0bd18306d801447bb457a46252d82d13"
},
{
"admin_state_up": true,
"availability_zone_hints": [],
"availability_zones": [
"nova"
],
"description": "",
"distributed": false,
"external_gateway_info": {
"enable_snat": true,
"external_fixed_ips": [
{
"ip_address": "172.24.4.6",
"subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
},
{
"ip_address": "2001:db8::9",
"subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
}
],
"network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
},
"ha": false,
"id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
"name": "router1",
"routes": [],
"status": "ACTIVE",
"tenant_id": "0bd18306d801447bb457a46252d82d13"
}
]
}