Browse Source

Merge "Network Segment Range Management"

Zuul 4 months ago
parent
commit
fef5951bad
1 changed files with 582 additions and 0 deletions
  1. 582
    0
      specs/stein/network-segment-range-management.rst

+ 582
- 0
specs/stein/network-segment-range-management.rst View File

@@ -0,0 +1,582 @@
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
+Network Segment Range Management
9
+================================
10
+
11
+Launchpad blueprint:
12
+https://blueprints.launchpad.net/neutron/+spec/network-segment-range-management
13
+
14
+Currently, network segment ranges are configured as an entry in ML2 config
15
+file [1]_ that is statically defined for tenant network allocation and
16
+therefore must be managed as part of the host deployment and management. When a
17
+normal tenant user creates a network, Neutron assigns the next free
18
+segmentation ID (VLAN ID, VNI etc.) from the configured segment ranges. Only an
19
+administrator can assign a specific segment ID via the provider extension.
20
+
21
+This spec introduces an extension which exposes the segment range management to
22
+be administered via the Neutron API. In addition, it introduces the ability for
23
+the administrator to control the segment ranges globally or on a per-tenant
24
+basis.
25
+
26
+
27
+Problem Description
28
+===================
29
+
30
+Self-service networks, aka tenant networks primarily enable general
31
+(non-privileged) projects to manage networks without involving administrators.
32
+These networks are entirely virtual and require virtual routers to interact
33
+with provider and external networks such as the Internet. In most cases,
34
+self-service networks use overlay protocols such as VXLAN or GRE because they
35
+can support many more networks than layer-2 segmentation using VLAN tagging
36
+(802.1q) which typically requires additional configuration of physical network
37
+infrastructure. Nevertheless, in some other cases, OpenStack Neutron also
38
+supports the self-service network isolation using VLAN etc. [2]_.
39
+
40
+The current Neutron implementation sets entries in a config file to statically
41
+define network segment ranges for tenant network allocation. It does not
42
+support another dynamic way (e.g. at the API level) after initialization.
43
+Neutron services have to be restarted in order to make any change to the
44
+network segment ranges take effect. However, cloud network infrastructure
45
+deployments can be complex and non-homogeneous. This rigidity brings about
46
+complexity and difficulty to cloud administrators when dealing with varied
47
+requirements.
48
+
49
+Network segment range management provides an additional level of flexibility at
50
+the API level which enables full network orchestration of all the types of
51
+tenant networks using standard REST API rather than needing to interact with
52
+the host configuration directly. Apart from this, for VLAN tenant networks in
53
+particular, network segment range management enables a control over the
54
+management of the cloud/network infrastructure for tenant networks. It also
55
+facilitates per-tenant assignments (including shared). This enables a cloud
56
+administrator to directly control the VLAN tenant segment mapping, and
57
+ultimately the underlying L2/L3 path of the tenant traffic without exposing
58
+specific network segment range information to the tenant user. The segment
59
+allocations for tenant networks will refer to the network segment ranges which
60
+are assigned to that tenant by an administrator.
61
+
62
+Several sample use cases are demonstrated below.
63
+
64
+Use Case I
65
+----------
66
+
67
+Enable cloud administrators to create and assign per-tenant network segment
68
+ranges. This gives an administrator the privilege to manage the underlying
69
+network segment ranges. When a tenant creates a network, it will allocate a
70
+segment ID from the segment ranges assigned to the tenant or shared if no
71
+tenant specific range available. It helps map the VMs created by that tenant
72
+with an explicit set of existing networks, for privacy or dedicated business
73
+connection needs. One example illustration is shown below:
74
+
75
+::
76
+
77
+                             +------------------+
78
+                             | Physical Network |
79
+      +------------+---------+ Infrastructures  +-------------------+
80
+      |            |         +---------+--------+                   |
81
+      |            |                   |                            |
82
+      |            |                   |                            |
83
+ +----+----+  +----+----+         +----+----+                 +----+----+
84
+ | Tenant 0|  | Tenant 1|.........| Tenant k|.................| Tenant n|
85
+ +----+----+  +----+----+         +----+----+                 +----+----+
86
+      |            |                   |                           |
87
+      |            |                   |                           |
88
+      + range-0    + range-1           + range-k1                  + range-n
89
+                                         range-k2
90
+
91
+* One cloud is connecting and mapping with a large number of existing l2
92
+  physical network infrastructures.
93
+
94
+* n+1 tenants: Tenant 0, ...Tenant k..., Tenant n are available in this cloud.
95
+
96
+* Each tenant needs to be assigned with one (or more) network segment range(s)
97
+  respectively (range-0, ...range-k1..., ...range-k2..., range-n) by the cloud
98
+  administrator, so that the networks it creates can reach the corresponding
99
+  dedicated physical network infrastructure it would like to connect to
100
+  according to different business requirements.
101
+
102
+A possible workflow is presented as follows:
103
+
104
+1. Cloud administrator lists all network segment ranges existing::
105
+
106
+    openstack network segment range list
107
+
108
+2. If no network segment range created for one target tenant, then cloud
109
+   administrator could create one for it::
110
+
111
+    openstack network segment range create
112
+                --name <range_name>
113
+                --shared <shared>
114
+                --project <project_id>
115
+                --network_type <network_type>
116
+                --physical_network <physical_network_name>
117
+                --minimum <range_minimum>
118
+                --maximum <range_maximum>
119
+
120
+3. Now a normal tenant user can create networks in regular way [3]_. The
121
+   network created will automatically allocate a segment ID from the segment
122
+   ranges assigned to the tenant (per step 3) or shared if no tenant specific
123
+   range available.
124
+
125
+This helps deciding the correct VLAN mapping when multiple tenants exist. It
126
+also provides the possibility to dynamically create a network segment range for
127
+each tenant, even if it's not pre-deployed in the host configuration.
128
+
129
+Use Case II
130
+-----------
131
+
132
+In some VLAN tenant network scenarios, it is not uncommon that the existing
133
+physical network infrastructures’ segment configurations have been changed.
134
+Thus, it is a must for cloud administrators to update the VLAN allocation range
135
+for tenant networks at the same time in order to keep aligned with the
136
+connection or mapping. Hence offering the ability to dynamically manage segment
137
+ranges of self-service networks, as this spec proposes, is imperative for VLAN
138
+tenant networks and is definitely a plus for other overlay tenant networks.
139
+
140
+A possible workflow is presented as follows:
141
+
142
+1. Cloud administrator lists all network segment ranges existing and
143
+   identifies the one needs to update::
144
+
145
+    openstack network segment range list
146
+
147
+2. Cloud administrator updates a network segment range based on the actual
148
+   requirement changing::
149
+
150
+    openstack network segment range set
151
+                --name <range_name>
152
+                --minimum <range_minimum>
153
+                --maximum <range_maximum>
154
+                <network_segment_range-id>
155
+
156
+3. Now a normal tenant user can create networks in regular way [3]_. The network
157
+   created will automatically allocate free segment ID from the updated network
158
+   segment ranges available.
159
+
160
+
161
+Proposed Change
162
+===============
163
+
164
+To address the above use cases, this spec introduces a new resource called
165
+network_segment_ranges together with its implementation.
166
+
167
+Currently by default, all pre-configured segment information (e.g.
168
+network_vlan_ranges, vni_ranges etc. defined in [1]_) is loaded into
169
+"ml2_xxx_allocations" DB tables by ML2 type drivers once the Neutron services
170
+are up. For all self-service networks’ segmentation ID sync, allocations and
171
+releases, they will be based on this information.
172
+
173
+All this information will be maintained. The network segment ranges introduced
174
+in this spec will augment this initial allocation that is loaded from the
175
+configuration file to become part of the shared ranges. It proposes an API way
176
+that user with administrative privileges can create and manage various network
177
+segment ranges for all network types supported by ML2.
178
+
179
+Data Model Impact
180
+-----------------
181
+
182
+The following new table is added as part of the network network management
183
+feature::
184
+
185
+    CREATE TABLE network_segment_ranges (
186
+      id CHAR(36) NOT NULL PRI KEY,
187
+      name VARCHAR(255),
188
+      shared BOOL NOT NULL,
189
+      project_id VARCHAR(255) NOT NULL,
190
+      network_type ENUM('vlan', 'vxlan', 'gre', 'geneve') NOT NULL,
191
+      physical_network VARCHAR(64),
192
+      minimum INT,
193
+      maximum INT
194
+    );
195
+
196
+For different network types, the validation strategies and responses should
197
+have the following variants:
198
+
199
+* VLAN: minimum = 1, maximum = 4094.
200
+
201
+* VXLAN: minimum = 1, maximum = 2 ** 24 - 1.
202
+
203
+* GRE: minimum = 1, maximum = 2 ** 32 - 1.
204
+
205
+* Geneve: minimum = 1, maximum = 2 ** 24 - 1.
206
+
207
+Notes: Other validation rules like minimum <= maximum are always applicable and
208
+should be paid attention to. Most of the cited above have been supported in
209
+neutron_lib.plugins.utils.
210
+
211
+Mixin classes to add the network segment range management extension should be
212
+provided. The DB operation logic should be handled by the ML2 type manager and
213
+the type drivers. For the values present in the existing ML2 configuration
214
+options [1]_ (e.g. ml2_type_vlan, ml2_type_vxlan etc.), they will be loaded as
215
+`shared` segment ranges into segment_range DB in order to provide backward
216
+compatibility for initial deployment when this extension is present.
217
+
218
+Resource Extension
219
+------------------
220
+The following new resource is being introduced and its attributes maps would be
221
+like:
222
+
223
+.. code-block:: python
224
+
225
+  NETWORK_TYPE_LIST = [TYPE_VLAN, TYPE_VXLAN, TYPE_GRE, TYPE_GENEVE]
226
+  RESOURCE_ATTRIBUTE_MAPS = {
227
+    'network_segment_ranges': {
228
+      'id': {'allow_post': False, 'allow_put': False,
229
+             'validate': {'type:uuid': None},
230
+             'is_visible': True,
231
+             'is_filter': True,
232
+             'is_sort_key': True,
233
+             'primary_key': True},
234
+      'name': {'allow_post': True, 'allow_put': True,
235
+               'validate': {
236
+                 'type:string': db_const.NAME_FIELD_SIZE},
237
+               'default': '', 'is_visible': True, 'is_filter': True,
238
+               'is_sort_key': True},
239
+      'shared': {'allow_post': True, 'allow_put': False,
240
+                 'convert_to': converters.convert_to_boolean,
241
+                 'is_visible': True, 'default': True},
242
+      'project_id': {'allow_post': True, 'allow_put': False,
243
+                     'validate': {
244
+                     'type:string': db_const.PROJECT_ID_FIELD_SIZE},
245
+                     'required_by_policy': True,
246
+                     'is_filter': True,
247
+                     'is_sort_key': True,
248
+                     'is_visible': True},
249
+      'network_type': {'allow_post': True, 'allow_put': False,
250
+                       'validate': {'type:values': NETWORK_TYPE_LIST},
251
+                       'default': constants.ATTR_NOT_SPECIFIED,
252
+                       'is_filter': True,
253
+                       'is_visible': True},
254
+      'physical_network': {'allow_post': True, 'allow_put': False,
255
+                           'validate': {
256
+                             'type:string': PHYSICAL_NETWORK_MAX_LEN},
257
+                           'default': constants.ATTR_NOT_SPECIFIED,
258
+                           'is_filter': True,
259
+                           'is_visible': True},
260
+      'minimum': {'allow_post': True, 'allow_put': True,
261
+                  'convert_to': converters.convert_to_int, 'is_visible': True},
262
+      'maximum': {'allow_post': True, 'allow_put': True,
263
+                  'convert_to': converters.convert_to_int, 'is_visible': True},
264
+      'used': {'allow_post': False, 'allow_put': False,
265
+               'is_visible': True},
266
+      'available': {'allow_post': False, 'allow_put': False,
267
+                    'convert_to': attr.convert_none_to_empty_list,
268
+                    'is_visible': True},
269
+    },
270
+  }
271
+
272
+REST API Impact
273
+---------------
274
+
275
+The idea is to add a new resource extension with the below defined attributes.
276
+Resource extension network_segment_ranges:
277
+
278
++-----------------+--------+-----+--------+-----------+-----------------------+
279
+|  Attribute Name |  Type  | Req |  CRUD  | Default   |     Description       |
280
+|                 |        |     |        | Value     |                       |
281
++=================+========+=====+========+===========+=======================+
282
+| id              | String | N/A |  R     | Generated | Identifier of network |
283
+|                 |        |     |        |           | segment range         |
284
++-----------------+--------+-----+--------+-----------+-----------------------+
285
+| name            | String | No  |  CRU   | ''        | Name of network       |
286
+|                 |        |     |        |           | segment range         |
287
++-----------------+--------+-----+--------+-----------+-----------------------+
288
+| shared          | Bool   | Yes |  CR    | False     | Shared with other     |
289
+|                 |        |     |        |           | projects              |
290
++-----------------+--------+-----+--------+-----------+-----------------------+
291
+| project_id      | String | No  |  CR    | Current   | Owner of network      |
292
+|                 |        |     |        | project_id| range. Optional when  |
293
+|                 |        |     |        |           | `shared` is True.     |
294
++-----------------+--------+-----+--------+-----------+-----------------------+
295
+| network_type    | Enum   | Yes |  CR    | None      | VLAN, VxLAN, GRE      |
296
+|                 |        |     |        |           | Geneve                |
297
++-----------------+--------+-----+--------+-----------+-----------------------+
298
+| physical_network| String | No  |  CR    | None      | Optional. Only        |
299
+|                 |        |     |        |           | applicable for VLAN.  |
300
++-----------------+--------+-----+--------+-----------+-----------------------+
301
+| minimum         | INT    | Yes |  CRU   | None      | Floor integer of the  |
302
+|                 |        |     |        |           | segment range         |
303
++-----------------+--------+-----+--------+-----------+-----------------------+
304
+| maximum         | INT    | Yes |  CRU   | None      | Ceiling integer of the|
305
+|                 |        |     |        |           | segment range         |
306
++-----------------+--------+-----+--------+-----------+-----------------------+
307
+| used            | Dict   | No  |  R     | {}        | Mapping of which      |
308
+|                 |        |     |        |           | segmentation ID in the|
309
+|                 |        |     |        |           | range is used by which|
310
+|                 |        |     |        |           | tenant                |
311
++-----------------+--------+-----+--------+-----------+-----------------------+
312
+| available       | List   | No  |  R     | []        | List of available     |
313
+|                 |        |     |        |           | segmentation IDs in   |
314
+|                 |        |     |        |           | this segment range    |
315
++-----------------+--------+-----+--------+-----------+-----------------------+
316
+
317
+To specify a range with single item, min equals to max can do the trick. For
318
+discrete segment ranges of one given network type, they are represented as
319
+several ones, each with a min and a max.
320
+
321
+The following network segment range management Rest APIs will be provided in
322
+line with the new resources previously introduced:
323
+
324
+* List all network segment ranges.
325
+  GET /v2.0/network_segment_ranges
326
+
327
+::
328
+
329
+    GET /v2.0/network_segment_ranges
330
+    Accept: application/json
331
+    {
332
+      "network_segment_ranges": [
333
+        {
334
+          "id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
335
+          "name": "network_segment_range_physnet1",
336
+          "shared": False,
337
+          "project_id": "45977fa2dbd7482098dd68d0d8970117",
338
+          "network_type": "vlan",
339
+          "physical_network": "physnet1",
340
+          "minimum": 100,
341
+          "maximum": 105,
342
+          "used": {100: "07ac1127ee9647d48ce2626867104a13",
343
+                   101: "d4fa62aa47d340d98d076801aa7e6ec4"},
344
+          "available": [102, 103, 104, 105],
345
+        }
346
+      ]
347
+    }
348
+
349
+* List a network segment range information.
350
+  GET /v2.0/network_segment_ranges/<network_segment_range-id>
351
+
352
+::
353
+
354
+    GET /v2.0/network_segment_ranges/d23abc8d-2991-4a55-ba98-2aaea84cc72f
355
+    Accept: application/json
356
+    {
357
+      "network_segment_range": {
358
+        "id": "d23abc8d-2991-4a55-ba98-2aaea84cc72f",
359
+        "name": "network_segment_range_physnet1",
360
+        "shared": False,
361
+        "project_id": "45977fa2dbd7482098dd68d0d8970117",
362
+        "network_type": "vlan",
363
+        "physical_network": "physnet1",
364
+        "minimum": 100,
365
+        "maximum": 105,
366
+        "used": {100: "07ac1127ee9647d48ce2626867104a13",
367
+                 101: "d4fa62aa47d340d98d076801aa7e6ec4"},
368
+        "available": [102, 103, 104, 105],
369
+      }
370
+    }
371
+
372
+* Create a network segment range for a given tenant.
373
+  POST /v2.0/network_segment_ranges
374
+
375
+::
376
+
377
+    POST /v2.0/network_segment_ranges
378
+    Accept: application/json
379
+    {
380
+      "network_segment_range": {
381
+        "name": "network_segment_range_physnet1",
382
+        "shared": False,
383
+        "project_id": "45977fa2dbd7482098dd68d0d8970117",
384
+        "network_type": "vlan",
385
+        "physical_network": "physnet1",
386
+        "minimum": 100,
387
+        "maximum": 200,
388
+      }
389
+    }
390
+
391
+* Delete a network segment range by id.
392
+  DELETE /v2.0/network_segment_ranges/<network_segment_range-id>
393
+
394
+  Normal Response Code: 204
395
+
396
+  Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409).
397
+  The Conflict error response is returned when an operation is performed while
398
+  the network segment range has resource allocated within it.
399
+
400
+  This operation does not require a request body.
401
+
402
+  This operation does not return a response body.
403
+
404
+::
405
+
406
+    DELETE /v2.0/network_segment_ranges/d23abc8d-2991-4a55-ba98-2aaea84cc72f
407
+    Accept: application/json
408
+
409
+* Update a network segment range with given data.
410
+  PUT /v2.0/network_segment_ranges/<network_segment_range-id>
411
+
412
+::
413
+
414
+    PUT /v2.0/network_segment_ranges/d23abc8d-2991-4a55-ba98-2aaea84cc72f
415
+    Accept: application/json
416
+    {
417
+      "network_segment_range": {
418
+        "minimum": 200,
419
+        "maximum": 300,
420
+      }
421
+    }
422
+
423
+Command Line Client Impact
424
+--------------------------
425
+
426
+Openstack Client would add network segment range management related CLIs. They
427
+should be admin only CLI commands. For example::
428
+
429
+    openstack network segment range list
430
+                [--used | --not-used]
431
+                [--available | --not-available]
432
+
433
+    openstack network segment range show <network_segment_range-id>
434
+
435
+    openstack network segment range create
436
+                --shared <shared>
437
+                --network_type <network_type>
438
+                --minimum <range_minimum>
439
+                --maximum <range_maximum>
440
+                [--name <range_name>]
441
+                [--project_id <project_id>]
442
+                [--physical_network <physical_network>]
443
+
444
+    Notes: Arguments --name, --project_id are optional, the project_id can be
445
+           taken from the context if not given; --physical_network is optional
446
+           and only applicable for VLAN. All the other parameters should be
447
+           required.
448
+
449
+    openstack network segment range set
450
+                [--name <range_name>]
451
+                [--minimum <range_minimum>]
452
+                [--maximum <range_maximum>]
453
+                <network_segment_range-id>
454
+
455
+    openstack network segment range delete <network_segment_range-id>
456
+
457
+Other Impact
458
+------------
459
+
460
+* ML2 plugin, plugin manager and type drivers will need to be refined and added
461
+  with several new methods correspondingly in order to support this feature.
462
+
463
+* The existing ML2 configuration will populate the proposed
464
+  network_segment_ranges as a shared range. When this extension is loaded, a
465
+  change is expected in the processing of the ML2 configuration.
466
+
467
+* Validation work is needed for quite a few cases, including but not limited
468
+  to:
469
+
470
+  * Admin privilege should always be checked before performing any network
471
+    segment range operation cited previously.
472
+
473
+  * When deleting one network segment range, the operation should be rejected
474
+    if one of the network segments is in use.
475
+
476
+  * It is allowed to update one network segment range if it does not impact the
477
+    in-use segment allocated within the range (e.g. enlarging that range).
478
+    Otherwise, we should fail the updating.
479
+
480
+  * We're maintaining the consistency by "ml2_xxx_allocations" DB tables and
481
+    relying on them to do the eventual validation and the underlying segment
482
+    allocation. This means network segment ranges can be configured before
483
+    agents are actually mapped to specific physical network mappings.
484
+
485
+* Theoretically, multiple network segment ranges can be created for one
486
+  tenant (while one network segment range cannot be owned by several tenants).
487
+  If a tenant has more than one segment range configured, it would pick up the
488
+  next free segmentation ID (VLAN ID, VNI etc.) from all its owned network
489
+  segment ranges.
490
+
491
+  Backwards compatibility comes from having the default behavior of segment
492
+  ranges being assigned as a `shared` resource to tenants. If both of `shared`
493
+  and `specified` segment range resources are exposed to a tenant, the
494
+  `specified` should override the `shared`.
495
+
496
+* The extension will be optional (an option in [4]_ with functionality disabled
497
+  by default should be added), in which case the existing ML2 configuration
498
+  options will be applicable.
499
+
500
+Other End User Impact
501
+---------------------
502
+
503
+Users with admin privileges will be able to dynamically manage network segment
504
+ranges for which supports segmentation, all tenants and tenant networks. If no
505
+dynamic network segment range is created for a given tenant, or the feature is
506
+disabled due to the backwards compatibility consideration, there will be no
507
+impact to end users.
508
+
509
+Other Deployer Impact
510
+---------------------
511
+
512
+Deployers should have an option available to enable or disable this
513
+functionality so that they can continue to use the configuration file as
514
+before. They also need to be strongly warned to update their operational
515
+documentation to ensure that the new network segment information is managed
516
+using the correct facility. If the feature is disabled, nothing at the
517
+deployment level would be impacted.
518
+
519
+Performance Impact
520
+------------------
521
+
522
+Performance testing must be conducted to see what is the overhead of enabling
523
+this feature, of course if the feature is disabled no performance impact should
524
+be noticed.
525
+
526
+
527
+Implementation
528
+==============
529
+
530
+Assignee(s)
531
+-----------
532
+
533
+* Kailun Qin <kailun.qin@intel.com>
534
+
535
+Work Items
536
+----------
537
+
538
+* Adjust the DB model and add the new table.
539
+* Extend current API.
540
+* Modify type drivers and all related references.
541
+* Add related tests.
542
+* Add CLI openstackclient.
543
+* Documentation.
544
+
545
+
546
+Dependencies
547
+============
548
+
549
+None
550
+
551
+
552
+Testing
553
+=======
554
+
555
+Unit tests, functional tests, API tests and scenario tests are necessary.
556
+
557
+
558
+Documentation Impact
559
+====================
560
+
561
+The Neutron API reference will need to be updated.
562
+
563
+
564
+References
565
+==========
566
+
567
+.. [1] `ml2_conf.ini`:
568
+       /etc/neutron/plugins/ml2/ml2_conf.ini
569
+
570
+.. [2] `OpenStack Networking`:
571
+       https://docs.openstack.org/neutron/latest/admin/intro-os-networking.html
572
+
573
+.. [3] `Self-service network`:
574
+       https://docs.openstack.org/newton/install-guide-rdo/launch-instance-networks-selfservice.html
575
+
576
+.. [4] `neutron.conf`:
577
+       /etc/neutron/neutron.conf
578
+
579
+Related Information
580
+-------------------
581
+
582
+Neutron v2 API: https://developer.openstack.org/api-ref/network/v2/

Loading…
Cancel
Save