Add spec for custom SGs on VIP ports

Related-Bug: #2065767
Change-Id: Id3d2e4747a633e4e55b2037ac92a194bd8fbe16f

specs/version14.0/custom-security-groups-for-VIP-ports.rst

@@ -0,0 +1,198 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+================================================
+Support for Custom Security Groups for VIP Ports
+================================================
+
+This specification describes how Octavia can allow users to provide their own
+Neutron Security Groups for the VIP Port of a load balancer.
+
+
+Problem description
+===================
+
+Many users have requested a method for customizing the security groups of the
+VIP ports of a load balancer in Octavia. There are some benefits from using
+custom security groups:
+
+* Allowing incoming connections only from specific remote group IDs.
+
+* Having a unique API (The networking Security Groups API) to configure the
+  network security for all the users' resources.
+
+
+Proposed change
+===============
+
+A user will be able to provide a ``vip_sg_ids`` parameter when creating a load
+balancer.
+
+This parameter will be optional and defaulted to None. When set, it contains a
+list of security group IDs.  When it's not set, the
+behavior of the VIP port would not change.
+
+If the parameter is set, Octavia would apply this security group to the VIP and
+Amphora ports (known as VRRP ports internally). Then Octavia would create and
+manage a security group with rules for its internal communication (haproxy
+peering, VRRP communication). Thus the VIP port would have more than one
+security group.
+
+No rules based on the port or the protocol of the listeners would be managed by
+Octavia, for each new listener, the user would have to add their own rules to
+these security groups.
+
+
+Alternatives
+------------
+
+An alternative method would be to implement an ``allowed_remote_group_ids``
+parameter when creating a load balancer. Users would have a feature that covers
+the first point described in "Problem Description".
+
+
+Data model impact
+-----------------
+
+This feature requires some changes in the data model, a new table
+``VipSecurityGroup`` is added, it contains:
+
+* ``load_balancer_id``: the UUID of the load balancer (which also represents a
+  Vip)
+
+* ``sg_id``: the UUID of a Security Group
+
+A load balancer (identified by its ID) or a VIP are linked to one or more
+security groups.
+
+It also requires an update of the data model in octavia-lib.
+
+
+REST API impact
+---------------
+
+The POST /v2/lbaas/loadbalancers endpoint is updated to accept an optional
+``vip_sg_ids`` parameter (a list of UUIDs that represents Neutron Security
+Groups).
+
+If the parameter is set, Octavia checks that the security groups exist and that
+the user is allowed to use then, then Octavia creates new VIPSecurityGroup
+objects with these new parameters.
+
+The PUT /v2/lbaas/loadbalancers endpoint is also updated, allowing to update
+the list of Security Groups.
+
+The ``vip_sg_ids`` parameter is also added to the reply of the GET method.
+
+Using ``vip_sg_ids`` is incompatible with some existing features in Octavia,
+like ``allowed_cidrs`` in the listeners. Setting ``allowed_cidrs`` in a load
+balancer with ``vip_sg_ids`` should be denied, updating the ``vip_sg_ids`` of a
+load balancer that includes listeners with ``allowed_cidrs`` too.
+
+``vip_sg_ids`` is also incompatible with SR-IOV enabled load balancers.
+
+
+Security impact
+---------------
+
+There's no security impact, the security of newly created load balancers and
+listeners would be more restricted with this feature, because less rules are
+pushed to the security groups.
+
+It's up to the users to add rules to allow incoming traffic to the load
+balancer.
+
+A RBAC policy is added to Octavia, an administrator can limit the access to
+this feature to an operator.
+
+
+Notifications impact
+--------------------
+
+None.
+
+
+Other end user impact
+---------------------
+
+The impact for the end user is that they are responsible for allowing the
+incomming traffic to their load balancer. The creating of a new listener would
+request at least 2 API calls, one for creating the listener in Octavia, one for
+adding a new security group rule to their Neutron security group.
+
+
+Performance Impact
+------------------
+
+Performance could be impacted if the user adds too many rules to their security
+group, but this issue is outside the scope of Octavia.
+
+
+Other deployer impact
+---------------------
+
+None.
+
+
+Developer impact
+----------------
+
+Impact is minimal, a few changes in the API and in the DB, only a few new
+conditionals in the allowed_address_pairs module.
+
+It could have a more significant impact if this feature is added to the
+octavia-dashboard.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  gthiemonge
+
+
+Work Items
+----------
+
+1. Update the data model of the VIP port in octavia_lib and octavia.
+2. Update the API to handle the new ``vip_sg_id`` parameter.
+3. Update the allowed_address_pairs module to handle this new feature.
+4. Update the api-ref and the user guide.
+5. Add required unit and functional tests.
+6. Add support to python-octaviaclient and openstacksdk
+7. Add tempest tests for this feature.
+
+
+Dependencies
+============
+
+None.
+
+
+Testing
+=======
+
+The feature can easily be tested with tempest tests.
+
+- creation of a load balancer and it security groups, check that it's reachable
+- update the list of security groups, check that the connectivity to the load
+  balancer is impacted.
+
+
+Documentation Impact
+====================
+
+The feature will be included in the cookbook.
+The api-ref and feature matrix will be also updated.
+
+
+References
+==========
+
+None.