docs/design/port-data-plane-status.rst

   1 ..
   2  This work is licensed under a Creative Commons Attribution 3.0 Unported
   3  License.
   4
   5  http://creativecommons.org/licenses/by/3.0/legalcode
   6
   7 ====================================
   8 Port data plane status
   9 ====================================
  10
  11 https://bugs.launchpad.net/neutron/+bug/1598081
  12
  13 Neutron does not detect data plane failures affecting its logical resources.
  14 This spec addresses that issue by means of allowing external tools to report to
  15 Neutron about faults in the data plane that are affecting the ports. A new REST
  16 API field is proposed to that end.
  17
  18
  19 Problem Description
  20 ===================
  21
  22 An initial description of the problem was introduced in bug #159801 [1_]. This
  23 spec focuses on capturing one (main) part of the problem there described, i.e.
  24 extending Neutron's REST API to cover the scenario of allowing external tools
  25 to report network failures to Neutron. Out of scope of this spec are works to
  26 enable port status changes to be received and managed by mechanism drivers.
  27
  28 This spec also tries to address bug #1575146 [2_]. Specifically, and argued by
  29 the Neutron driver team in [3_]:
  30
  31  * Neutron should not shut down the port completly upon detection of physnet
  32    failure; connectivity between instances on the same node may still be
  33    reachable. Externals tools may or may not want to trigger a status change on
  34    the port based on their own logic and orchestration.
  35
  36  * Port down is not detected when an uplink of a switch is down;
  37
  38  * The physnet bridge may have multiple physical interfaces plugged; shutting
  39    down the logical port may not be needed in case network redundancy is in
  40    place.
  41
  42
  43 Proposed Change
  44 ===============
  45
  46 A couple of possible approaches were proposed in [1_] (comment #3). This spec
  47 proposes tackling the problema via a new extension API to the port resource.
  48 The extension adds a new attribute 'dp-down' (data plane down) to represent the
  49 status of the data plane. The field should be read-only by tenants and
  50 read-write by admins.
  51
  52 Neutron should send out an event to the message bus upon toggling the data
  53 plane status value. The event is relevant for e.g. auditing.
  54
  55
  56 Data Model Impact
  57 -----------------
  58
  59 A new attribute as extension will be added to the 'ports' table.
  60
  61 +------------+-------+----------+---------+--------------------+--------------+
  62 |Attribute   |Type   |Access    |Default  |Validation/         |Description   |
  63 |Name        |       |          |Value    |Conversion          |              |
  64 +============+=======+==========+=========+====================+==============+
  65 |dp_down     |boolean|RO, tenant|False    |True/False          |              |
  66 |            |       |RW, admin |         |                    |              |
  67 +------------+-------+----------+---------+--------------------+--------------+
  68
  69
  70 REST API Impact
  71 ---------------
  72
  73 A new API extension to the ports resource is going to be introduced.
  74
  75 .. code-block:: python
  76
  77   EXTENDED_ATTRIBUTES_2_0 = {
  78       'ports': {
  79           'dp_down': {'allow_post': False, 'allow_put': True,
  80                       'default': False, 'convert_to': convert_to_boolean,
  81                       'is_visible': True},
  82       },
  83   }
  84
  85
  86 Examples
  87 ~~~~~~~~
  88
  89 Updating port data plane status to down:
  90
  91 .. code-block:: json
  92
  93    PUT /v2.0/ports/<port-uuid>
  94    Accept: application/json
  95    {
  96        "port": {
  97            "dp_down": true
  98        }
  99    }
 100
 101
 102
 103 Command Line Client Impact
 104 --------------------------
 105
 106 ::
 107
 108   neutron port-update [--dp-down <True/False>] <port>
 109   openstack port set [--dp-down <True/False>] <port>
 110
 111 Argument --dp-down is optional. Defaults to False.
 112
 113
 114 Security Impact
 115 ---------------
 116
 117 None
 118
 119 Notifications Impact
 120 --------------------
 121
 122 A notification (event) upon toggling the data plane status (i.e. 'dp-down'
 123 attribute) value should be sent to the message bus. Such events do not happen
 124 with high frequency and thus no negative impact on the notification bus is
 125 expected.
 126
 127 Performance Impact
 128 ------------------
 129
 130 None
 131
 132 IPv6 Impact
 133 -----------
 134
 135 None
 136
 137 Other Deployer Impact
 138 ---------------------
 139
 140 None
 141
 142 Developer Impact
 143 ----------------
 144
 145 None
 146
 147 Implementation
 148 ==============
 149
 150 Assignee(s)
 151 -----------
 152
 153  * cgoncalves
 154
 155 Work Items
 156 ----------
 157
 158  * New 'dp-down' attribute in 'ports' database table
 159  * API extension to introduce new field to port
 160  * Client changes to allow for data plane status (i.e. 'dp-down' attribute')
 161    being set
 162  * Policy (tenants read-only; admins read-write)
 163
 164
 165 Documentation Impact
 166 ====================
 167
 168 Documentation for both administrators and end users will have to be
 169 contemplated. Administrators will need to know how to set/unset the data plane
 170 status field.
 171
 172
 173 References
 174 ==========
 175
 176 .. [1] RFE: Port status update,
 177    https://bugs.launchpad.net/neutron/+bug/1598081
 178
 179 .. [2] RFE: ovs port status should the same as physnet
 180    https://bugs.launchpad.net/neutron/+bug/1575146
 181
 182 .. [3] Neutron Drivers meeting, July 21, 2016
 183    http://eavesdrop.openstack.org/meetings/neutron_drivers/2016/neutron_drivers.2016-07-21-22.00.html