Browse Source

Network Segment Range Management

Currently, network segment ranges are configured as an entry in ML2
config file [1]_ that is statically defined for tenant network
allocation and therefore must be managed as part of the host deployment
and management. When a normal tenant user creates a network, Neutron
assigns the next free segmentation ID (VLAN ID, VNI etc.) from the
configured segment ranges; only an administrator can assign a specific
segment ID via the provider extension.

This spec introduces an extension which exposes the segment range
management to be administered via the Neutron API. In addition, it
introduces the ability for the administrator to control the segment
ranges globally or on a per-tenant basis.

[1] /etc/neutron/plugins/ml2/ml2_conf.ini

Co-Authored-By: Matt Peters <matt.peters@windriver.com>

Implements: blueprint network-segment-range-management
Change-Id: I2e586bb6d51d32c0ac2a28b2429512cea036f363
Kailun Qin 7 months ago
parent
commit
4c8156c804
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