Browse Source

[doc] Add network segment ranges into admin guide

Add a new networking guide section for "Network segment ranges" into
admin guide.

Co-authored-by: Allain Legacy <Allain.legacy@windriver.com>

Partially-implements: blueprint network-segment-range-management
Change-Id: I22fd32627d732b3bac9fc7d58e58a13784fda5f1
tags/14.0.0.0rc1
Kailun Qin 3 months ago
parent
commit
59600afc5a
2 changed files with 342 additions and 0 deletions
  1. 341
    0
      doc/source/admin/config-network-segment-ranges.rst
  2. 1
    0
      doc/source/admin/config.rst

+ 341
- 0
doc/source/admin/config-network-segment-ranges.rst View File

@@ -0,0 +1,341 @@
1
+.. _config-network-segment-ranges:
2
+
3
+======================
4
+Network segment ranges
5
+======================
6
+
7
+The network segment range service exposes the segment range management to be
8
+administered via the Neutron API. In addition, it introduces the ability for
9
+the administrator to control the segment ranges globally or on a per-tenant
10
+basis.
11
+
12
+Why you need it
13
+~~~~~~~~~~~~~~~
14
+
15
+Before Stein, network segment ranges were configured as an entry in ML2
16
+config file ``ml2_conf.ini`` that was statically defined for tenant network
17
+allocation and therefore had to be managed as part of the host deployment and
18
+management. When a regular tenant user creates a network, Neutron assigns the
19
+next free segmentation ID (VLAN ID, VNI etc.) from the configured segment
20
+ranges. Only an administrator can assign a specific segment ID via the
21
+provider extension.
22
+
23
+The network segment range management service provides the following
24
+capabilities that the administrator may be interested in:
25
+
26
+#. To check out the network segment ranges defined by the operators in the
27
+   ML2 config file so that the admin can use this information to make segment
28
+   range allocation.
29
+
30
+#. To dynamically create and assign network segment ranges, which can help
31
+   with the distribution of the underlying network connection mapping for
32
+   privacy or dedicated business connection needs. This includes:
33
+
34
+   * global shared network segment ranges
35
+   * tenant-specific network segment ranges
36
+
37
+#. To dynamically update a network segment range to offer the ability to adapt
38
+   to the connection mapping changes.
39
+
40
+#. To dynamically manage a network segment range when there are no segment
41
+   ranges defined within the ML2 config file ``ml2_conf.ini`` and no restart
42
+   of the Neutron server is required in this situation.
43
+
44
+#. To check the availability and usage statistics of network segment ranges.
45
+
46
+How it works
47
+~~~~~~~~~~~~
48
+
49
+A network segment range manages a set of segments from which self-service
50
+networks can be allocated. The network segment range management service is
51
+admin-only.
52
+
53
+As a regular project in an OpenStack cloud, you can not create a network
54
+segment range of your own and you just create networks in regular way.
55
+
56
+If you are an admin, you can create a network segment range which can be
57
+shared (i.e. used by any regular project) or tenant-specific (i.e.
58
+assignment on a per-tenant basis). Your network segment ranges will not be
59
+visible to any other regular projects. Other CRUD operations are also
60
+supported.
61
+
62
+When a tenant allocates a segment, it will first be allocated from an available
63
+segment range assigned to the tenant, and then a shared range if no tenant
64
+specific allocation is possible.
65
+
66
+Default network segment ranges
67
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68
+
69
+A set of ``default`` network segment ranges are created out of the values
70
+defined in the ML2 config file: ``network_vlan_ranges`` for ml2_type_vlan,
71
+``vni_ranges`` for ml2_type_vxlan, ``tunnel_id_ranges`` for ml2_type_gre and
72
+``vni_ranges`` for ml2_type_geneve. They will be reloaded when Neutron
73
+server starts or restarts. The ``default`` network segment ranges are
74
+``read-only``, but will be treated as any other ``shared`` ranges on segment
75
+allocation.
76
+
77
+The administrator can use the default network segment range information to
78
+make shared and/or per-tenant range creation and assignment.
79
+
80
+Example configuration
81
+~~~~~~~~~~~~~~~~~~~~~
82
+
83
+Controller node
84
+---------------
85
+
86
+#. Enable the network segment range service plugin by appending
87
+   ``network_segment_range`` to the list of ``service_plugins`` in the
88
+   ``neutron.conf`` file on all nodes running the ``neutron-server`` service:
89
+
90
+   .. code-block:: ini
91
+
92
+      [DEFAULT]
93
+      # ...
94
+      service_plugins = ...,network_segment_range,...
95
+
96
+#. Restart the ``neutron-server`` service.
97
+
98
+Verify service operation
99
+------------------------
100
+
101
+#. Source the administrative project credentials and list the enabled
102
+   extensions.
103
+
104
+#. Use the command :command:`openstack extension list --network` to verify
105
+   that the ``Neutron Network Segment Range`` extension with Alias
106
+   ``network-segment-range`` is enabled.
107
+
108
+.. code-block:: console
109
+
110
+    $ openstack extension list --network
111
+    +-------------------------------+-----------------------+-----------------------------------------------------------+
112
+    | Name                          | Alias                 | Description                                               |
113
+    +-------------------------------+-----------------------+-----------------------------------------------------------+
114
+    | ......                        | ......                | ......                                                    |
115
+    +-------------------------------+-----------------------+-----------------------------------------------------------+
116
+    | Neutron Network Segment Range | network-segment-range | Provides support for the network segment range management |
117
+    +-------------------------------+-----------------------+-----------------------------------------------------------+
118
+    | ......                        | ......                | ......                                                    |
119
+    +-------------------------------+-----------------------+-----------------------------------------------------------+
120
+
121
+Workflow
122
+~~~~~~~~
123
+
124
+At a high level, the basic workflow for a network segment range creation is
125
+the following:
126
+
127
+#. The Cloud administrator:
128
+
129
+   * Lists the existing network segment ranges.
130
+   * Creates a shared or a tenant-specific network segment range based on the
131
+     requirement.
132
+
133
+#. A regular tenant creates a network in regular way. The network created
134
+   will automatically allocate a segment from the segment ranges assigned to
135
+   the tenant or shared if no tenant specific range available.
136
+
137
+At a high level, the basic workflow for a network segment range update is
138
+the following:
139
+
140
+#. The Cloud administrator:
141
+
142
+   * Lists the existing network segment ranges and identifies the one that
143
+     needs to be updated.
144
+   * Updates the network segment range based on the requirement.
145
+
146
+#. A regular tenant creates a network in regular way. The network created
147
+   will automatically allocate a segment from the updated network segment
148
+   ranges available.
149
+
150
+List the network segment ranges or show a network segment range
151
+---------------------------------------------------------------
152
+
153
+As admin, list the existing network segment ranges:
154
+
155
+.. code-block:: console
156
+
157
+    $ openstack network segment range list
158
+    +--------------------------------------+-------------------+---------+--------+----------------------------------+--------------+------------------+------------+------------+
159
+    | ID                                   | Name              | Default | Shared | Project ID                       | Network Type | Physical Network | Minimum ID | Maximum ID |
160
+    +--------------------------------------+-------------------+---------+--------+----------------------------------+--------------+------------------+------------+------------+
161
+    | 20ce94e1-4e51-4aa0-a5f1-26bdfb5bd90e |                   | True    | True   | None                             | vxlan        | None             |          1 |        200 |
162
+    | 4b7af684-ec97-422d-ba38-8b9c2919ae67 | test_range_3      | False   | False  | 7011dc7fccac4efda89dc3b7f0d0975a | gre          | None             |        100 |        120 |
163
+    | a021e582-6b0f-49f5-90cb-79a670c61973 |                   | True    | True   | None                             | vlan         | default          |          1 |        100 |
164
+    | a3373630-969b-4ce9-bae7-dff0f8fa2f92 | test_range_2      | False   | True   | None                             | vxlan        | None             |        501 |        505 |
165
+    | a5707a8f-76f0-4f90-9aa7-c42bf54e94b5 |                   | True    | True   | None                             | gre          | None             |          1 |        150 |
166
+    | aad1b55b-43f1-46f9-8c35-85f270863ed6 |                   | True    | True   | None                             | geneve       | None             |          1 |        120 |
167
+    | e3233178-2866-4f40-b794-7c6fecdc8655 | test_range_1      | False   | False  | 7011dc7fccac4efda89dc3b7f0d0975a | vlan         | group0-data0     |         11 |         11 |
168
+    +--------------------------------------+-------------------+---------+--------+----------------------------------+--------------+------------------+------------+------------+
169
+
170
+The network segment ranges with ``Default`` as ``True`` are the ranges
171
+specified by the operators in the ML2 config file. Besides, there
172
+are also shared and tenant specific network segment ranges created by the
173
+admin previously.
174
+
175
+The admin is also able to check/show the detailed information (e.g.
176
+availability and usage statistics) of a network segment range:
177
+
178
+.. code-block:: console
179
+
180
+    $ openstack network segment range show test_range_1
181
+    +------------------+-----------------------------------------------+
182
+    | Field            | Value                                         |
183
+    +------------------+-----------------------------------------------+
184
+    | available        | []                                            |
185
+    | default          | False                                         |
186
+    | id               | e3233178-2866-4f40-b794-7c6fecdc8655          |
187
+    | location         | None                                          |
188
+    | maximum          | 11                                            |
189
+    | minimum          | 11                                            |
190
+    | name             | test_range_1                                  |
191
+    | network_type     | vlan                                          |
192
+    | physical_network | group0-data0                                  |
193
+    | project_id       | 7011dc7fccac4efda89dc3b7f0d0975a              |
194
+    | shared           | False                                         |
195
+    | used             | {u'7011dc7fccac4efda89dc3b7f0d0975a': ['11']} |
196
+    +------------------+-----------------------------------------------+
197
+
198
+Create or update the network segment range
199
+------------------------------------------
200
+
201
+As admin, create a network segment range based on your requirement:
202
+
203
+.. code-block:: console
204
+
205
+    $ openstack network segment range create --private --project demo \
206
+    --network-type vxlan --minimum 120 --maximum 140 test_range_4
207
+    +------------------+--------------------------------------+
208
+    | Field            | Value                                |
209
+    +------------------+--------------------------------------+
210
+    | available        | ['120-140']                          |
211
+    | default          | False                                |
212
+    | id               | c016dcda-5bc3-4e98-b41f-6773e92fcd2d |
213
+    | location         | None                                 |
214
+    | maximum          | 140                                  |
215
+    | minimum          | 120                                  |
216
+    | name             | test_range_4                         |
217
+    | network_type     | vxlan                                |
218
+    | physical_network | None                                 |
219
+    | project_id       | 7011dc7fccac4efda89dc3b7f0d0975a     |
220
+    | shared           | False                                |
221
+    | used             | {}                                   |
222
+    +------------------+--------------------------------------+
223
+
224
+Update a network segment range based on your requirement:
225
+
226
+.. code-block:: console
227
+
228
+    $ openstack network segment range set --minimum 100 --maximum 150 \
229
+    test_range_4
230
+
231
+Create a tenant network
232
+-----------------------
233
+
234
+Now, as project ``demo`` (to source the client environment script
235
+``demo-openrc`` for ``demo`` project according to
236
+https://docs.openstack.org/keystone/latest/install/keystone-openrc-rdo.html),
237
+create a network in a regular way.
238
+
239
+.. code-block:: console
240
+
241
+    $ source demo-openrc
242
+    $ openstack network create test_net
243
+    +---------------------------+--------------------------------------+
244
+    | Field                     | Value                                |
245
+    +---------------------------+--------------------------------------+
246
+    | admin_state_up            | UP                                   |
247
+    | availability_zone_hints   |                                      |
248
+    | availability_zones        |                                      |
249
+    | created_at                | 2019-02-25T23:20:36Z                 |
250
+    | description               |                                      |
251
+    | dns_domain                |                                      |
252
+    | id                        | 39e5b95c-ad7a-40b5-9ec1-a4b4a8a43f14 |
253
+    | ipv4_address_scope        | None                                 |
254
+    | ipv6_address_scope        | None                                 |
255
+    | is_default                | False                                |
256
+    | is_vlan_transparent       | None                                 |
257
+    | location                  | None                                 |
258
+    | mtu                       | 1450                                 |
259
+    | name                      | test_net                             |
260
+    | port_security_enabled     | True                                 |
261
+    | project_id                | 7011dc7fccac4efda89dc3b7f0d0975a     |
262
+    | provider:network_type     | vxlan                                |
263
+    | provider:physical_network | None                                 |
264
+    | provider:segmentation_id  | None                                  |
265
+    | qos_policy_id             | None                                 |
266
+    | revision_number           | 2                                    |
267
+    | router:external           | Internal                             |
268
+    | segments                  | None                                 |
269
+    | shared                    | False                                |
270
+    | status                    | ACTIVE                               |
271
+    | subnets                   |                                      |
272
+    | tags                      |                                      |
273
+    | updated_at                | 2019-02-25T23:20:36Z                 |
274
+    +---------------------------+--------------------------------------+
275
+
276
+
277
+Then, switch back to the admin to check the segmentation ID of the tenant
278
+network created.
279
+
280
+.. code-block:: console
281
+
282
+    $ source admin-openrc
283
+    $ openstack network show test_net
284
+    +---------------------------+--------------------------------------+
285
+    | Field                     | Value                                |
286
+    +---------------------------+--------------------------------------+
287
+    | admin_state_up            | UP                                   |
288
+    | availability_zone_hints   |                                      |
289
+    | availability_zones        |                                      |
290
+    | created_at                | 2019-02-25T23:20:36Z                 |
291
+    | description               |                                      |
292
+    | dns_domain                |                                      |
293
+    | id                        | 39e5b95c-ad7a-40b5-9ec1-a4b4a8a43f14 |
294
+    | ipv4_address_scope        | None                                 |
295
+    | ipv6_address_scope        | None                                 |
296
+    | is_default                | False                                |
297
+    | is_vlan_transparent       | None                                 |
298
+    | location                  | None                                 |
299
+    | mtu                       | 1450                                 |
300
+    | name                      | test_net                             |
301
+    | port_security_enabled     | True                                 |
302
+    | project_id                | 7011dc7fccac4efda89dc3b7f0d0975a     |
303
+    | provider:network_type     | vxlan                                |
304
+    | provider:physical_network | None                                 |
305
+    | provider:segmentation_id  | 137                                  |
306
+    | qos_policy_id             | None                                 |
307
+    | revision_number           | 2                                    |
308
+    | router:external           | Internal                             |
309
+    | segments                  | None                                 |
310
+    | shared                    | False                                |
311
+    | status                    | ACTIVE                               |
312
+    | subnets                   |                                      |
313
+    | tags                      |                                      |
314
+    | updated_at                | 2019-02-25T23:20:36Z                 |
315
+    +---------------------------+--------------------------------------+
316
+
317
+The tenant network created automatically allocates a segment with
318
+segmentation ID ``137`` from the network segment range with segmentation
319
+ID range ``120-140`` that is assigned to the tenant.
320
+
321
+If no more available segment in the network segment range assigned to this
322
+tenant, then the segment allocation would refer to the ``shared`` segment
323
+ranges to check whether there's one segment available. If still there is no
324
+segment available, the allocation will fail as follows:
325
+
326
+.. code-block:: console
327
+
328
+    $ openstack network create test_net
329
+    $ Unable to create the network. No tenant network is available for
330
+      allocation.
331
+
332
+In this case, the admin is advised to check the availability and usage
333
+statistics of the related network segment ranges in order to take further
334
+actions (e.g. enlarging a segment range etc.).
335
+
336
+Known limitations
337
+~~~~~~~~~~~~~~~~~
338
+
339
+* This service plugin is only compatible with ML2 core plugin for now.
340
+  However, it is possible for other core plugins to support this feature
341
+  with a follow-on effort.

+ 1
- 0
doc/source/admin/config.rst View File

@@ -25,6 +25,7 @@ Configuration
25 25
    config-logging
26 26
    config-macvtap
27 27
    config-mtu
28
+   config-network-segment-ranges
28 29
    config-ovs-dpdk
29 30
    config-ovs-offload
30 31
    config-ovsfwdriver

Loading…
Cancel
Save