From 75e75b03b3cb4d9b1860dbf51bcdea30c9799a99 Mon Sep 17 00:00:00 2001 From: Salvatore Orlando Date: Sat, 24 Aug 2013 22:06:06 +0100 Subject: [PATCH] API docs for configurable external gateway modes extension Bug 1216576 The documentation discusses how the router resources is extended and provides information concerning how to enable or disable SNAT using the Neutron API. Change-Id: I20f2913495558dd40b1d9ffa59797a97a342bf49 --- v2.0/neutron-api-guide.xml | 1 + v2.0/neutron-extgwmodes-ext.xml | 207 ++++++++++++++++++ v2.0/samples/router-create-enablesnat.sample | 29 +++ .../samples/router-update-enablesnat-1.sample | 55 +++++ .../samples/router-update-enablesnat-2.sample | 55 +++++ .../samples/router-update-enablesnat-3.sample | 56 +++++ v2.0/samples/routers-get-enablesnat-res.json | 23 ++ 7 files changed, 426 insertions(+) create mode 100644 v2.0/neutron-extgwmodes-ext.xml create mode 100644 v2.0/samples/router-create-enablesnat.sample create mode 100644 v2.0/samples/router-update-enablesnat-1.sample create mode 100644 v2.0/samples/router-update-enablesnat-2.sample create mode 100644 v2.0/samples/router-update-enablesnat-3.sample create mode 100644 v2.0/samples/routers-get-enablesnat-res.json diff --git a/v2.0/neutron-api-guide.xml b/v2.0/neutron-api-guide.xml index 4458ae0..aa2c21b 100644 --- a/v2.0/neutron-api-guide.xml +++ b/v2.0/neutron-api-guide.xml @@ -2676,6 +2676,7 @@ Date: Wed, 12 Sep 2012 11:36:20 GMT + diff --git a/v2.0/neutron-extgwmodes-ext.xml b/v2.0/neutron-extgwmodes-ext.xml new file mode 100644 index 0000000..8adb424 --- /dev/null +++ b/v2.0/neutron-extgwmodes-ext.xml @@ -0,0 +1,207 @@ + + + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + + '> + + + + + + '> +]> +
+ Configurable external gateway modes extension + By default, when a gateway is attached to a router using the Neutron L3 extension, Network + Address Translation (NAT) is enabled for traffic generated by subnets attached to the + router. With this extension, the user will have the option of choosing whether SNAT + should be enabled or not on a router basis. + This is achieved simply by specifying a boolean attribute, enable_snat, + in the external_gateway_info attribute of the router + resource. + This extension redefines the external_gateway_info attribute as depicted in the following + table. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
external_gateway_info attributes
Attribute Type Required Default Value Validation Constraints Notes
network_idUUIDYesN/AMust be a valid uuid representative of an external network. +
enable_snatBooleanNoTrue{True|False}The default setting is True to ensure backward compatibility + for plugins supporting this extension.
+ SNAT can be enabled or disabled at any time on a Neutron router regardless of the + current status of floating IPs. Floating IPs will continue working even when SNAT is + disabled. +
+ List Routers + + + + + + + + Verb + URI + Description + + + + + &GET; + /routers + Retrieve Neutron routers + + + + + Success and error response codes are not changed with regards to the operation as + introduced by the L3 API extension. + When this extension is enabled, this operation will also return the current Source + NAT status for configured routers, as shown in the sample below. + The response for the show router operation is the same, with + the obvious exception that a single router is returned. + + Router list with configurable external gateway modes enabled + + +
+
+ Create Router with external gateway + + + + + + + + Verb + URI + Description + + + + + &POST; + /routers + Create a new Neutron router + + + + + + Success and error response codes are not changed with regards to the operation as + introduced by the L3 API extension. + Neutron API users can specify whether SNAT should be performed on the network + specifed as the router's external gateway by setting enable_snat in + external_gateway_info to either True or + False; the default value is True. + + Create router with SNAT disabled + + +
+
+ Update Router's external gateway info + + + + + + + + Verb + URI + Description + + + + + &PUT; + /routers/router_id + Create a new Neutron router + + + + + Success and error response codes are not changed with regards to the operation as + introduced by the L3 API extension. + Neutron API users can enable or disable SNAT on a router specifying the + enable_snat attribute in the + external_gateway_info attribute for the router resource. This + operation can be either used for updating the SNAT status only, the + external network, or both attributes at the same time. In any case, if + the enable_snat attribute is not specified, it will default to + True. For instance, if the current SNAT status is disabled, and + the router's gateway is updated to a different external network without specifying + enable_snat, SNAT will be enabled for the new network. + It is important to note that whenever updating a router's external gateway + information, the network_id parameter must be specified always, even + if the final goal is just to enable or disable SNAT for the router on the same + external network. + The rest of this section provides some samples for updating a router's external gateway + info with SNAT mode. + + + Disable SNAT for the current external network + + + + Change external network and enable SNAT + + + + Change external network and keep SNAT disabled + + + +
+ + +
diff --git a/v2.0/samples/router-create-enablesnat.sample b/v2.0/samples/router-create-enablesnat.sample new file mode 100644 index 0000000..d3d73cb --- /dev/null +++ b/v2.0/samples/router-create-enablesnat.sample @@ -0,0 +1,29 @@ + +POST /v2.0/routers +Accept: application/json +{ + "router": + { + "name": "another_router", + "admin_state_up": true, + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + } +} + +HTTP/1.1 201 OK +Content-Type: application/json; charset=UTF-8 +{ + "router": + { + "status": "ACTIVE", + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + "name": "another_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" + } +} \ No newline at end of file diff --git a/v2.0/samples/router-update-enablesnat-1.sample b/v2.0/samples/router-update-enablesnat-1.sample new file mode 100644 index 0000000..560e557 --- /dev/null +++ b/v2.0/samples/router-update-enablesnat-1.sample @@ -0,0 +1,55 @@ +POST /v2.0/routers +Accept: application/json +{ + "router": + { + "name": "another_router", + "admin_state_up": true, + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8"} + } +} + +HTTP/1.1 201 OK +Content-Type: application/json; charset=UTF-8 +{ + "router": + { + "status": "ACTIVE", + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": true} + "name": "another_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" + } +} + + +PUT /v2.0/routers +Accept: application/json +{ + "router": + { + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + } +} + +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +{ + "router": + { + "status": "ACTIVE", + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + "name": "another_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" + } +} \ No newline at end of file diff --git a/v2.0/samples/router-update-enablesnat-2.sample b/v2.0/samples/router-update-enablesnat-2.sample new file mode 100644 index 0000000..322c85d --- /dev/null +++ b/v2.0/samples/router-update-enablesnat-2.sample @@ -0,0 +1,55 @@ +POST /v2.0/routers +Accept: application/json +{ + "router": + { + "name": "another_router", + "admin_state_up": true, + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + } +} + +HTTP/1.1 201 OK +Content-Type: application/json; charset=UTF-8 +{ + "router": + { + "status": "ACTIVE", + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + "name": "another_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" + } +} + + +PUT /v2.0/routers +Accept: application/json +{ + "router": + { + "external_gateway_info": { + "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5"} + } +} + +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +{ + "router": + { + "status": "ACTIVE", + "external_gateway_info": { + "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5", + "enable_snat": true} + "name": "another_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" + } +} \ No newline at end of file diff --git a/v2.0/samples/router-update-enablesnat-3.sample b/v2.0/samples/router-update-enablesnat-3.sample new file mode 100644 index 0000000..6a62eef --- /dev/null +++ b/v2.0/samples/router-update-enablesnat-3.sample @@ -0,0 +1,56 @@ +POST /v2.0/routers +Accept: application/json +{ + "router": + { + "name": "another_router", + "admin_state_up": true, + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + } +} + +HTTP/1.1 201 OK +Content-Type: application/json; charset=UTF-8 +{ + "router": + { + "status": "ACTIVE", + "external_gateway_info": { + "network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false} + "name": "another_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" + } +} + + +PUT /v2.0/routers +Accept: application/json +{ + "router": + { + "external_gateway_info": { + "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5", + "enable_snat": false} + } +} + +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +{ + "router": + { + "status": "ACTIVE", + "external_gateway_info": { + "network_id": "002ab3b9-9127-4158-be30-4b45f3814df5", + "enable_snat": false} + "name": "another_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e" + } +} \ No newline at end of file diff --git a/v2.0/samples/routers-get-enablesnat-res.json b/v2.0/samples/routers-get-enablesnat-res.json new file mode 100644 index 0000000..bbfb44b --- /dev/null +++ b/v2.0/samples/routers-get-enablesnat-res.json @@ -0,0 +1,23 @@ +{ + "routers": + [{ + "status": "ACTIVE", + "external_gateway_info": + {"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": true}, + "name": "second_router", + "admin_state_up": true, + "tenant_id": "6b96ff0cb17a4b859e1e575d221683d3", + "id": "7177abc4-5ae9-4bb7-b0d4-89e94a4abf3b" + }, + { + "status": "ACTIVE", + "external_gateway_info": + {"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8", + "enable_snat": false}, + "name": "router1", + "admin_state_up": true, + "tenant_id": "33a40233088643acb66ff6eb0ebea679", + "id": "a9254bdb-2613-4a13-ac4c-adc581fba50d" + }] +} \ No newline at end of file