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

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