From c24391cb5ce2f759b8a029044baa1b083bb11c7a Mon Sep 17 00:00:00 2001 From: Paul Michali Date: Mon, 15 Jun 2015 15:21:12 -0400 Subject: [PATCH] VPNaaS: DevRef for multiple local subnets This provides design information to go along with the RFE. Selected approach that is the most flexible, permitting future reuse. Provided details on how to handle backwards compatibility. Change-Id: I943ed13d3d43017a86d709eeae33967f25515937 Partial-Bug: 1459423 --- doc/source/devref/index.rst | 5 +- doc/source/devref/multiple-local-subnets.rst | 292 +++++++++++++++++++ 2 files changed, 293 insertions(+), 4 deletions(-) create mode 100644 doc/source/devref/multiple-local-subnets.rst diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index 10d99ceb5..f33b795d8 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -40,10 +40,7 @@ VPNaaS Internals .. toctree:: :maxdepth: 3 -.. todo:: - - Add design details about VPN, especially items that are not obvious. - Can indication restrictions/limitations. + multiple-local-subnets Testing diff --git a/doc/source/devref/multiple-local-subnets.rst b/doc/source/devref/multiple-local-subnets.rst new file mode 100644 index 000000000..c5c74b1d3 --- /dev/null +++ b/doc/source/devref/multiple-local-subnets.rst @@ -0,0 +1,292 @@ +================================= +Multiple Local Subnets for VPNaaS +================================= + +As originally implemented, an VPN IPSec connection could have one or more +peer subnets specified, but only **one** local subnet. To support multiple +local subnets, multiple IPSec connections would be needed. + +With the multiple local subnet support, three goals are addressed. First, +there can be multiple local and peer endpoints for a single IPSec connection. + +Second, validation enforces that the same IP version is used for all +endpoints (to reduce complexity and ease testing). + +Third, the "what is connected" is separated from the "how to connect", +so that other flavors of VPN (as they are developed) can use some of this +mechanism. + + +Design Notes +------------ + +There were three proposals considered, to support multiple local subnets. + +Proposal A was to just add the local subnets to the IPSec connection API. +That would be the quickest way, and addresses the first two goals, but +not the third. + +Proposal B was to create a new API that specifies of the local subnets +and peer CIDRs, and reference those in the connection API. This would +separate the "what is connected" from the "how to connect", and again +addresses the first two goals (only). + +Proposal C, which was the *selected proposal*, creates a new API +that represents the "endpoint groups" for VPN connections, in the same +manner as proposal B. The added flexibility here, though, which meets +goal three, is to also include the endpoint group "type", thus allowing +subnets (local) and CIDRs (peer) to be used for IPSec, but routers, +networks, and VLANs to be used for other VPN types (BGP, L2, direct +connection). Additional types can be added in the future as needed. + + +Client CLI API +-------------- + +The originally implemented client CLI APIs (which are still available +for backward compatibility) for an IPsec connection are: + | neutron vpn-service-create ROUTER SUBNET + | neutron ipsec-site-connection-create + | --vpnservice-id VPNSERVICE + | --ikepolicy-id IKEPOLICY + | --ipsecpolicy-id IPSECPOLICY + | --peer-address PEER_ADDRESS + | --peer-id PEER_ID + | --peer-cidr PEER_CIDRS + | --dpd action=ACTION,interval=INTERVAL,timeout=TIMEOUT + | --initiator {bi-directional | response-only} + | --mtu MTU + | --psk PSK + +Changes to the API, to support multiple local subnets, are shown in +**bold** text: + | neutron vpn-service-create ROUTER + | **neutron vpn-endpoint-groups-create** + | **--name OPTIONAL-NAME** + | **--description OPTIONAL-DESCRIPTION** + | **--ep-type={subnet,cidr,network,vlan,router}** + | **--ep-value=[list-of-endpoints-of-type]** + | neutron ipsec-site-connection-create + | --vpnservice-id VPNSERVICE + | --ikepolicy-id IKEPOLICY + | --ipsecpolicy-id IPSECPOLICY + | --peer-address PEER_ADDRESS + | --peer-id PEER_ID + | --dpd action=ACTION,interval=INTERVAL,timeout=TIMEOUT + | --initiator {bi-directional | response-only} + | --mtu MTU + | --psk PSK + | **--local-endpoints ENDPOINT-GROUPS-UUID** + | **--peer-endpoints ENDPOINT-GROUPS-UUID** + +The SUBNET in the original service API is optional, and will be used as an +indicator of whether or not the multiple local subnets feature is active. +See the 'Backward Compatibility' section, below, for details. + +For the endpoint groups, the --ep-type value is a string, so that other +types can be supported in the future. + +The endpoint groups API would enforce that the endpoint values are all of +the same type, and match the endpoint type specified. + +The connection APIs, would then provide additional validation. For example, +with IPSec, the endpoint type must be 'subnet' for local, and 'cidr' for +peer, all the endpoints should be of the same IP version, and for the local +endpoint, all subnets would be on the same router. + +For BGP VPN with dynamic routing, only a local endpoint group would be +specified, and the type would be 'network'. + +The ROUTER may also be able to be removed, in the future, and can be +determined, when the connections are created. + +Note: Using --ep-type, as --endpoint-type is already used elsewhere, and +--type is too generic. Using --ep-value, as --endpoint is already in use, +--end-point could be easily mistyped as --endpoint, and --value is too +generic. + + +Examples +-------- + +The original APIs to create one side of an IPSec connection with +only one local and peer subnet: + | neutron vpn-ikepolicy-create ikepolicy + | neutron vpn-ipsecpolicy-create ipsecpolicy + | neutron vpn-service-create --name myvpn router1 privateA + | neutron ipsec-site-connection-create + | --name vpnconnection1 + | --vpnservice-id myvpn + | --ikepolicy-id ikepolicy + | --ipsecpolicy-id ipsecpolicy + | --peer-address 172.24.4.13 + | --peer-id 172.24.4.13 + | --peer-cidr 10.3.0.0/24 + | --psk secret + +The local CIDR is obtained from the subnet, privateA. In this example, +that would be 10.1.0.0/24 (because that's how privateA was created). + +Using the multiple local subnet feature, the APIs (with changes shown +in **bold** below: + | neutron vpn-ikepolicy-create ikepolicy + | neutron vpn-ipsecpolicy-create ipsecpolicy + | neutron vpn-service-create --name myvpn router1 + | **neutron vpn-endpoint-group-create** + | **--name local-eps** + | **--ep-type=subnet** + | **--ep-value=privateA** + | **--ep-value=privateB** + | **neutron vpn-endpoint-group-create** + | **--name peer-eps** + | **--ep-type=cidr** + | **--ep-vallue=10.3.0.0/24** + | neutron ipsec-site-connection-create + | --name vpnconnection1 + | --vpnservice-id myvpn + | --ikepolicy-id ikepolicy + | --ipsecpolicy-id ipsecpolicy + | --peer-address 172.24.4.13 + | --psk secret + | **--local-endpoints local-eps** + | **--peer-endpoints peer-eps** + +The subnets privateA and privateB are used for local endpoints and the +10.3.0.0/24 CIDR is used for the peer endpoint. + + +Database +-------- + +The vpn_endpoints table contains single endpoint entries and a reference +to the containing endpoint group. The vpn_endpoint_groups table defines +the group, specifying the endpoint type. + + +Database Migration +------------------ + +For an older database, the first subnet, in the subnet entry of the +service table can be placed in an endpoint group that will be used +for the local endpoints of the connection. The CIDRs from the connection +can be placed into another endpoint group for the peer endpoints. + + +Backwards Compatibility +----------------------- + +Operators would like to see this new capability provided, with backward +compatibility support. The implication, as I see it, is to provide the +ability for end users to be able to switch to the new API at any time, +versus being forced to use the new API immediately, upon upgrade to the +new release containing this feature. This would apply to both manual +API use, and client apps/scripting-tools that would be used to configure +VPNaaS. + +There are several attributes that are involve here. One is the subnet ID +attribute in the VPN service API. The other is the peer CIDR attribute in +the IPSec connection API. Both would be specified by endpoint groups in +the new API, and thise groups would be called out in the IPSec connection +API. + +A plan to meet the backward compatibility goal of allowing both APIs to +be used at once involves taking the following steps. + +For VPN service: + +- Make the subnet ID attribute optional. +- If subnet ID is specified for create, consider old API mode. +- If subnet ID specified for create, create endpoint group and store ID. +- For delete, if subnet ID exists, delete corresponding endpoint group. +- For show/list, if subnet ID exists, show the ID in output. +- Subnet ID is not mutable, so no change for update API. + + +For IPSec site to site connection: + +- For create, if old API mode, only allow peer-cidr attribute. +- For create, if not old API mode, require local/peer endpoint group IDs attributes. +- For create, if peer-cidr specified, create endpoint group and store ID. +- For create, reject endpoint group ID attributes, if old API mode. +- For create, reject peer-cidr attribute, if not old API mode. +- For create, if old API mode, lookup subnet in service, find containing endpoint group ID and store. +- For delete, if old API mode, delete endpoint group for peer. +- For update of CIDRs (old mode), will delete endpoint group and create new one. (note 1) +- For update of endpoint-group IDs (new mode), will allow different groups to be specified. (note 1,2) +- For show/list, if old API mode, only display the peer CIDR values from peer endpoint group. +- For show/list, if not old API mode, also show local subnets from local endpoint group. + +Note 1: Implication is that connection is torn down and re-created (as is +done currently). + +Note 2: Users would create a new endpoint group, and then select that group, +when modifying the IPSec connection. + + +For endpoint groups: + +- For delete, if subnet, and (sole) subnet ID is used in a VPN service (old mode), reject request. +- Updates are not supported, so no action required. (note 2) + +Note 2: Allowing updates would require deletion/recreation of connection +using endpoint group. Avoiding that complexity. + + +The thought here is to use endpoint groups under the hood, but if the old +API was being used, treat the endpoint groups as if they never existed. +Deleting connections and services would remove any endpoint groups, unlike +with the new API, where they are independent. + +Migration can be used to move any VPNaaS configurations using the old +schema to the new schema. This would look at VPN services and for any +with a subnet ID, an endpoint group would be created and the group ID +stored in any existing IPSec connections for that service. Likewise, +any peer CIDRs in a connection would be copied into a new endpoint group +and the group ID stored in the connection. + +The subnet ID field would then be removed from the VPN service table, +and the peer CIDRs table would be removed. + +This migration could be done at the time of the new API release, in which +case all tenants with existing VPNaaS configurations would use the new +API to manage them (but could use old for new configurations). + +Alternatively, the migration could be deferred until the old API is +removed, to ensure all existing configurations conform to the new schema. +Migration tools can then be created to manually migrate individual +tenants, as desired. + + +Stories +------- + +For the endpoint groups, stories can cover: + +- CRUD API for the endpoint groups. +- Database support for new tables. +- Migration creation of new tables. +- Validation of endpoints for a group (same type). +- Neutron client support for new API. +- Horizon support for new API. +- API documentation update. + +For the multiple local subnets, stories can cover: + +- create IPsec connection with one local subnet, but using new API. +- create IPSec connection with multiple local subnets. +- Show IPSec connection to display endpoint group IDs (or endpoints?). +- Ensure previous API still works, but uses new tables. +- Validation to ensure old and new APIs are not mixed. +- Modify CLI client. +- Validate multiple local subnets on same router. +- Validate local and peer endpoints are of same IP version. +- Functional tests with multiple local subnets +- API and How-To documentation update + +Note: The intent here is to have the initial stories take slices +vertically through the process so that we can demonstrate the +capability early. + +Note: Horizon work to support the changes is not expected to be part +of this effort and would be handled by the Horizon team separately, +if support is desired.