summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKailun Qin <kailun.qin@intel.com>2019-02-26 07:35:49 +0800
committerKailun Qin <kailun.qin@intel.com>2019-03-12 07:16:24 +0800
commit59600afc5a838ef011d8493fa02678a01ab42f7b (patch)
tree90804bcf4f90bbc2944719faa167159943745c73
parent590002728d4686cb947391911534c4d42f36cfb5 (diff)
[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
Notes
Notes (review): Code-Review+2: Slawek Kaplonski <skaplons@redhat.com> Code-Review+2: LIU Yulong <i@liuyulong.me> Workflow+1: LIU Yulong <i@liuyulong.me> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Tue, 12 Mar 2019 08:26:42 +0000 Reviewed-on: https://review.openstack.org/639110 Project: openstack/neutron Branch: refs/heads/master
-rw-r--r--doc/source/admin/config-network-segment-ranges.rst341
-rw-r--r--doc/source/admin/config.rst1
2 files changed, 342 insertions, 0 deletions
diff --git a/doc/source/admin/config-network-segment-ranges.rst b/doc/source/admin/config-network-segment-ranges.rst
new file mode 100644
index 0000000..3dafe78
--- /dev/null
+++ b/doc/source/admin/config-network-segment-ranges.rst
@@ -0,0 +1,341 @@
1.. _config-network-segment-ranges:
2
3======================
4Network segment ranges
5======================
6
7The network segment range service exposes the segment range management to be
8administered via the Neutron API. In addition, it introduces the ability for
9the administrator to control the segment ranges globally or on a per-tenant
10basis.
11
12Why you need it
13~~~~~~~~~~~~~~~
14
15Before Stein, network segment ranges were configured as an entry in ML2
16config file ``ml2_conf.ini`` that was statically defined for tenant network
17allocation and therefore had to be managed as part of the host deployment and
18management. When a regular tenant user creates a network, Neutron assigns the
19next free segmentation ID (VLAN ID, VNI etc.) from the configured segment
20ranges. Only an administrator can assign a specific segment ID via the
21provider extension.
22
23The network segment range management service provides the following
24capabilities 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
46How it works
47~~~~~~~~~~~~
48
49A network segment range manages a set of segments from which self-service
50networks can be allocated. The network segment range management service is
51admin-only.
52
53As a regular project in an OpenStack cloud, you can not create a network
54segment range of your own and you just create networks in regular way.
55
56If you are an admin, you can create a network segment range which can be
57shared (i.e. used by any regular project) or tenant-specific (i.e.
58assignment on a per-tenant basis). Your network segment ranges will not be
59visible to any other regular projects. Other CRUD operations are also
60supported.
61
62When a tenant allocates a segment, it will first be allocated from an available
63segment range assigned to the tenant, and then a shared range if no tenant
64specific allocation is possible.
65
66Default network segment ranges
67~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68
69A set of ``default`` network segment ranges are created out of the values
70defined 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
73server starts or restarts. The ``default`` network segment ranges are
74``read-only``, but will be treated as any other ``shared`` ranges on segment
75allocation.
76
77The administrator can use the default network segment range information to
78make shared and/or per-tenant range creation and assignment.
79
80Example configuration
81~~~~~~~~~~~~~~~~~~~~~
82
83Controller 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
98Verify 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
121Workflow
122~~~~~~~~
123
124At a high level, the basic workflow for a network segment range creation is
125the 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
137At a high level, the basic workflow for a network segment range update is
138the 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
150List the network segment ranges or show a network segment range
151---------------------------------------------------------------
152
153As 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
170The network segment ranges with ``Default`` as ``True`` are the ranges
171specified by the operators in the ML2 config file. Besides, there
172are also shared and tenant specific network segment ranges created by the
173admin previously.
174
175The admin is also able to check/show the detailed information (e.g.
176availability 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
198Create or update the network segment range
199------------------------------------------
200
201As 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
224Update 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
231Create a tenant network
232-----------------------
233
234Now, as project ``demo`` (to source the client environment script
235``demo-openrc`` for ``demo`` project according to
236https://docs.openstack.org/keystone/latest/install/keystone-openrc-rdo.html),
237create 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
277Then, switch back to the admin to check the segmentation ID of the tenant
278network 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
317The tenant network created automatically allocates a segment with
318segmentation ID ``137`` from the network segment range with segmentation
319ID range ``120-140`` that is assigned to the tenant.
320
321If no more available segment in the network segment range assigned to this
322tenant, then the segment allocation would refer to the ``shared`` segment
323ranges to check whether there's one segment available. If still there is no
324segment 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
332In this case, the admin is advised to check the availability and usage
333statistics of the related network segment ranges in order to take further
334actions (e.g. enlarging a segment range etc.).
335
336Known 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.
diff --git a/doc/source/admin/config.rst b/doc/source/admin/config.rst
index 19436eb..222305e 100644
--- a/doc/source/admin/config.rst
+++ b/doc/source/admin/config.rst
@@ -25,6 +25,7 @@ Configuration
25 config-logging 25 config-logging
26 config-macvtap 26 config-macvtap
27 config-mtu 27 config-mtu
28 config-network-segment-ranges
28 config-ovs-dpdk 29 config-ovs-dpdk
29 config-ovs-offload 30 config-ovs-offload
30 config-ovsfwdriver 31 config-ovsfwdriver