Browse Source

Add devstack instructions and local.conf samples

Restructure the development environment documentation
and include sample devstack config to get folks
started easy when they're coding manila changes.

Change-Id: If2df8bdf88e77eec32e8795020b8ef349b55b41b
Goutham Pacha Ravi 4 months ago
parent
commit
e1619c4626

+ 148
- 51
doc/source/contributor/development-environment-devstack.rst View File

@@ -17,90 +17,187 @@ Setting up a development environment with devstack
17 17
 
18 18
 This page describes how to setup a working development
19 19
 environment that can be used in deploying manila on latest releases
20
-of Ubuntu or Fedora. These instructions assume you are already familiar
21
-with git. Refer to `Getting the code`_ for additional information.
20
+of Ubuntu, Fedora or CentOS. These instructions assume you are already familiar
21
+with git.
22 22
 
23
-.. _Getting the code: http://wiki.openstack.org/GettingTheCode
23
+We recommend using devstack to develop and test code changes to
24
+manila or to simply evaluate the manila project. Devstack is a shell script
25
+to build complete OpenStack development environments on a virtual machine.
26
+If you are not familar with devstack, these pages can give you context:
24 27
 
25
-Following these instructions will allow you to have a fully functional manila
26
-environment using the devstack project (a shell script to build
27
-complete OpenStack development environments).
28
+* `Testing Changes with DevStack <https://docs.openstack.org/contributors/code-and-documentation/devstack.html>`_
29
+* `Devstack project documentation <https://docs.openstack.org/devstack/latest>`_
28 30
 
29
-Configuring devstack with manila
30
---------------------------------
31
+Be aware that manila is not enabled in devstack by default; you will need to
32
+add a few lines to the devstack ``local.conf`` file to let devstack deploy and
33
+configure manila on your virtual machine.
31 34
 
32
-Manila
33
-``````
35
+Getting devstack
36
+----------------
34 37
 
35
-Manila can be enabled in devstack by using the plug-in based interface it
36
-offers.
38
+Start by cloning the devstack repository::
37 39
 
38
-Start by cloning the devstack repository:
40
+    git clone https://git.openstack.org/openstack-dev/devstack
39 41
 
40
-::
42
+Change to devstack directory::
41 43
 
42
-    git clone https://git.openstack.org/openstack-dev/devstack
44
+    cd devstack/
43 45
 
44
-Change to devstack directory:
45 46
 
46
-::
47
+You're now on ``master`` branch of devstack, switch to the branch you want
48
+to test or develop against.
47 49
 
48
-    cd devstack/
50
+Sample local.conf files that get you started
51
+--------------------------------------------
49 52
 
50
-Copy the local.conf sample file to the upper level directory:
53
+Now that you have cloned the devstack repository, you need to
54
+configure devstack before deploying it.  This is done with a ``local.conf``
55
+file.  For manila, the local.conf file can also determine which back end(s)
56
+are set up.
51 57
 
52
-::
58
+.. caution::
53 59
 
54
-    cp samples/local.conf .
60
+    When using devstack with the below configurations, be aware that you will
61
+    be setting up fake storage. The `LVM`, `Generic`, `ZFSOnLinux` drivers
62
+    have not been developed for production use. They exist to provide a
63
+    vanilla development and testing environment for manila contributors.
55 64
 
56
-Enable the manila plugin adding the following line to the end of the local.conf file:
65
+DHSS=False (`driver_handles_share_servers=False`) mode:
66
+`````````````````````````````````````````````````````````
67
+This is the easier mode for new contributors. Manila share back-end drivers
68
+that operate in ``driver_handles_share_servers=False`` mode do not allow
69
+creating shares on private project networks. On the resulting stack, all
70
+manila shares created by you are exported on the host network and hence are
71
+accessible to any compute resource (e.g.: virtual machine, baremetal,
72
+container) that is able to reach the devstack host.
57 73
 
58
-::
74
+* :download:`LVM driver <samples/lvm_local.conf>`
75
+* :download:`ZFSOnLinux driver <samples/zfsonlinux_local.conf>`
76
+* :download:`CEPHFS driver <samples/cephfs_local.conf>`
59 77
 
60
-    enable_plugin manila https://git.openstack.org/openstack/manila
78
+DHSS=True (`driver_handles_share_servers=True`) mode:
79
+```````````````````````````````````````````````````````
61 80
 
62
-If you would like to install python-manilaclient from git, add to local.conf:
81
+You may use the following setups if you are familiar with manila,
82
+and would like to test with the project (tenant) isolation that manila
83
+provides on the network and data path. Manila share back-end drivers that
84
+operate in ``driver_handles_share_servers=True`` mode create shares on
85
+isolated project networks if told to do so. On the resulting stack, when
86
+creating a share, you must specify a share network to export the share to,
87
+and the share will be accessible to any compute resource (e.g.: Virtual
88
+machine, baremetal, containers) that is able to reach the share network you
89
+indicated.
63 90
 
64
-::
91
+Typically, new contributors take a while to understand OpenStack networking,
92
+and we recommend that you familiarize yourself with the DHSS=False mode
93
+setup before attempting DHSS=True.
65 94
 
66
-    LIBS_FROM_GIT="python-manilaclient"
95
+* :download:`Generic driver <samples/generic_local.conf>`
96
+* :download:`Container driver <samples/container_local.conf>`
67 97
 
68
-Manila UI
69
-`````````
70 98
 
71
-In order to use the manila UI you will need to enable the UI plugin separately.
99
+Building your devstack
100
+----------------------
72 101
 
73
-This is done in a similar fashion than enabling manila for devstack.
102
+* Copy the appropriate sample local.conf file into the devstack folder on your
103
+  virtual machine, make sure to name it ``local.conf``
104
+* Make sure to read inline comments and customize values where necessary
105
+* If you would like to run minimal services in your stack, or allow devstack
106
+  to bootstrap tempest testing framework for you, see :ref:`more-customization`
107
+* Finally, run the stack.sh script from within the devstack directory. We
108
+  recommend that your run this inside a screen or tmux session because it
109
+  could take a while::
74 110
 
75
-Make sure you have horizon enabled (enabled by default in current devstack).
111
+    ./stack.sh
76 112
 
77
-Then, enable the manila UI plugin adding the following line to the end of the local.conf file,
78
-just after manila plugin enablement:
113
+* After the script completes, you should have manila services running. You can
114
+  verify that the services are running with the following commands::
79 115
 
80
-::
116
+    $ systemctl status devstack@m-sch
117
+    $ systemctl status devstack@m-shr
118
+    $ systemctl status devstack@m-dat
81 119
 
82
-    enable_plugin manila-ui https://git.openstack.org/openstack/manila-ui
120
+* By default, devstack sets up manila-api behind apache. The service name is
121
+  ``httpd`` on Red Hat based systems and ``apache2`` on Debian based systems.
83 122
 
84
-Running devstack
85
-----------------
123
+* You may also use your "demo" credentials to invoke the command line
124
+  clients::
86 125
 
87
-Run the stack.sh script:
126
+    $ source DEVSTACK_DIR/openrc admin demo
127
+    $ manila service-list
128
+
129
+* The logs are accessible through ``journalctl``. The following commands let
130
+  you query logs. You may use the ``-f`` option to tail these logs::
131
+
132
+    $ journalctl -a -o short-precise --unit devstack@m-sch
133
+    $ journalctl -a -o short-precise --unit devstack@m-shr
134
+    $ journalctl -a -o short-precise --unit devstack@m-dat
135
+
136
+* If running behind apache, the manila-api logs will be in
137
+  ``/var/log/httpd/manila_api.log`` (Red Hat) or
138
+  in ``/var/log/apache2/manila_api.log`` (Debian).
139
+
140
+
141
+.. _more-customization:
142
+
143
+More devstack customizations
144
+----------------------------
145
+
146
+Testing branches and changes submitted for review
147
+`````````````````````````````````````````````````
148
+
149
+To test a patch in review::
150
+
151
+    enable_plugin manila git://git.openstack.org/openstack/manila <ref>
152
+
153
+If the ref is from review.openstack.org, it is structured as::
154
+
155
+    refs/changes/<last two digits of review number>/<review number>/<patchset number>
156
+
157
+For example, if you want to test patchset 4 of https://review.openstack.org/#/c/614170/,
158
+you can provide this in your ``local.conf``::
159
+
160
+    enable_plugin manila git://git.openstack.org/openstack/manila refs/changes/70/614170/4
161
+
162
+ref can also simply be a stable branch name, for example::
163
+
164
+    enable_plugin manila git://git.openstack.org/openstack/manila stable/rocky
165
+
166
+Limiting the services enabled in your stack
167
+````````````````````````````````````````````
168
+
169
+Manila needs only a message queue (rabbitmq) and a database (mysql,
170
+postgresql) to operate. Additionally, keystone service provides project
171
+administration if necessary, all other OpenStack services are not necessary
172
+to set up a basic test system. [#f1]_ [#f2]_
173
+
174
+You can add the following to your ``local.conf`` to deploy your stack in a
175
+minimal fashion. This saves you a lot of time and resources, but could limit
176
+your testing::
177
+
178
+    ENABLED_SERVICES=key,mysql,rabbit,tempest,manila,m-api,m-sch,m-shr,m-dat
179
+
180
+Optionally, you can deploy with Manila, Nova, Neutron, Glance and Tempest::
181
+
182
+    ENABLED_SERVICES=key,mysql,rabbit,tempest,g-api,g-reg
183
+    ENABLED_SERVICES+=n-api,n-cpu,n-cond,n-sch,n-crt,n-cauth,n-obj,placement-api,placement-client
184
+    ENABLED_SERVICES+=q-svc,q-dhcp,q-meta,q-l3,q-agt
185
+    ENABLED_SERVICES+=tempest
88 186
 
89
-::
90 187
 
91
-    ./stack.sh
92 188
 
93
-After it completes, you should have manila services running.
94
-You can check if they are running by attaching to the screen:
189
+Bootstrapping Tempest
190
+`````````````````````
95 191
 
96
-::
192
+Add the following options in your ``local.conf`` to set up tempest::
97 193
 
98
-    screen -r stack
194
+    ENABLE_ISOLATED_METADATA=True
195
+    TEMPEST_USE_TEST_ACCOUNTS=True
196
+    TEMPEST_ALLOW_TENANT_ISOLATION=False
197
+    TEMPEST_CONCURRENCY=8
99 198
 
100
-And navigating to the manila service tabs (use ctrl+a n, ctrl+a p,
101
-ctrl+a " <screen number> to navigate,
102
-ctrl+a esc to enter scrollback mode
103
-and ctrl+a d to detach from the screen).
104 199
 
105
-If you enabled manila UI as well, you should be able to access manila UI
106
-from the dashboard.
200
+.. [#f1] The Generic driver cannot be run without deploying Cinder, Nova,
201
+         Glance and Neutron.
202
+.. [#f2] You must enable Horizon to use manila-ui. Horizon will not work
203
+         well when Nova, Cinder, Glance and Neutron are not enabled.

+ 39
- 0
doc/source/contributor/samples/cephfs_local.conf View File

@@ -0,0 +1,39 @@
1
+######################################################################
2
+# This local.conf sets up Devstack with manila enabling the CEPHFS
3
+# driver which operates in driver_handles_share_services=False
4
+# mode. Pay attention to the storage protocol configuration to run
5
+# the cephfs driver with either the native CEPHFS protocol or the NFS
6
+# protocol
7
+#######################################################################
8
+
9
+[[local|localrc]]
10
+ADMIN_PASSWORD=secret
11
+DATABASE_PASSWORD=$ADMIN_PASSWORD
12
+RABBIT_PASSWORD=$ADMIN_PASSWORD
13
+SERVICE_PASSWORD=$ADMIN_PASSWORD
14
+DEST=/opt/stack
15
+DATA_DIR=/opt/stack/data
16
+LOGFILE=/opt/stack/devstacklog.txt
17
+
18
+
19
+# Enabling manila services
20
+LIBS_FROM_GIT=python-manilaclient
21
+enable_plugin manila git://git.openstack.org/openstack/manila
22
+enable_plugin manila-ui https://github.com/openstack/manila-ui
23
+enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
24
+
25
+
26
+# Enabling ceph
27
+enable_plugin devstack-plugin-ceph git://git.openstack.org/openstack/devstack-plugin-ceph
28
+ENABLE_CEPH_MANILA=True
29
+
30
+
31
+# IMPORTANT - Comment out / remove the following line to use
32
+# the CEPH driver with the native CEPHFS protocol
33
+MANILA_CEPH_DRIVER=cephfsnfs
34
+
35
+
36
+# CEPHFS backend options
37
+MANILA_SERVICE_IMAGE_ENABLED=False
38
+MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=False'
39
+MANILA_CONFIGURE_DEFAULT_TYPES=True

+ 35
- 0
doc/source/contributor/samples/container_local.conf View File

@@ -0,0 +1,35 @@
1
+######################################################################
2
+# This local.conf sets up Devstack with manila enabling the Container
3
+# driver that uses Docker and operates in
4
+# driver_handles_share_services=True mode
5
+#######################################################################
6
+
7
+[[local|localrc]]
8
+ADMIN_PASSWORD=secret
9
+DATABASE_PASSWORD=$ADMIN_PASSWORD
10
+RABBIT_PASSWORD=$ADMIN_PASSWORD
11
+SERVICE_PASSWORD=$ADMIN_PASSWORD
12
+DEST=/opt/stack
13
+DATA_DIR=/opt/stack/data
14
+LOGFILE=/opt/stack/devstacklog.txt
15
+
16
+
17
+# Enabling manila services
18
+LIBS_FROM_GIT=python-manilaclient
19
+enable_plugin manila git://git.openstack.org/openstack/manila
20
+enable_plugin manila-ui https://github.com/openstack/manila-ui
21
+enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
22
+
23
+
24
+# Container Backend config options
25
+MANILA_SERVICE_IMAGE_ENABLED=False
26
+SHARE_DRIVER=manila.share.drivers.container.driver.ContainerShareDriver
27
+MANILA_ENABLED_BACKENDS=vienna,prague
28
+MANILA_BACKEND1_CONFIG_GROUP_NAME=vienna
29
+MANILA_BACKEND2_CONFIG_GROUP_NAME=prague
30
+MANILA_SHARE_BACKEND1_NAME=VIENNA
31
+MANILA_SHARE_BACKEND2_NAME=PRAGUE
32
+MANILA_OPTGROUP_vienna_driver_handles_share_servers=True
33
+MANILA_OPTGROUP_prague_driver_handles_share_servers=True
34
+MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=false'
35
+MANILA_CONFIGURE_DEFAULT_TYPES=True

+ 42
- 0
doc/source/contributor/samples/generic_local.conf View File

@@ -0,0 +1,42 @@
1
+######################################################################
2
+# This local.conf sets up Devstack with manila enabling the Generic
3
+# driver that uses Cinder to provide back-end storage and Nova to
4
+# serve storage virtual machines (share servers) in the tenant's domain.
5
+# This driver operates in driver_handles_share_services=True mode
6
+#######################################################################
7
+
8
+[[local|localrc]]
9
+ADMIN_PASSWORD=secret
10
+DATABASE_PASSWORD=$ADMIN_PASSWORD
11
+RABBIT_PASSWORD=$ADMIN_PASSWORD
12
+SERVICE_PASSWORD=$ADMIN_PASSWORD
13
+DEST=/opt/stack
14
+DATA_DIR=/opt/stack/data
15
+LOGFILE=/opt/stack/devstacklog.txt
16
+
17
+
18
+# Enabling manila services
19
+LIBS_FROM_GIT=python-manilaclient
20
+enable_plugin manila git://git.openstack.org/openstack/manila
21
+enable_plugin manila-ui https://github.com/openstack/manila-ui
22
+enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
23
+
24
+
25
+# Generic Back end config options
26
+SHARE_DRIVER=manila.share.drivers.generic.GenericShareDriver
27
+MANILA_ENABLED_BACKENDS=tokyo,shanghai
28
+MANILA_BACKEND1_CONFIG_GROUP_NAME=tokyo
29
+MANILA_BACKEND2_CONFIG_GROUP_NAME=shanghai
30
+MANILA_SHARE_BACKEND1_NAME=TOKYO
31
+MANILA_SHARE_BACKEND2_NAME=SHANGHAI
32
+MANILA_OPTGROUP_tokyo_driver_handles_share_servers=True
33
+MANILA_OPTGROUP_shanghai_driver_handles_share_servers=True
34
+MANILA_OPTGROUP_tokyo_connect_share_server_to_tenant_network=True
35
+MANILA_OPTGROUP_shanghai_connect_share_server_to_tenant_network=True
36
+MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=True create_share_from_snapshot_support=True'
37
+MANILA_CONFIGURE_DEFAULT_TYPES=True
38
+
39
+
40
+# Storage Virtual Machine settings for the generic driver
41
+MANILA_SERVICE_IMAGE_ENABLED=True
42
+MANILA_USE_SERVICE_INSTANCE_PASSWORD=True

+ 36
- 0
doc/source/contributor/samples/lvm_local.conf View File

@@ -0,0 +1,36 @@
1
+################################################################
2
+# This local.conf sets up Devstack with manila enabling the LVM
3
+# driver which operates in driver_handles_share_services=False
4
+# mode
5
+################################################################
6
+
7
+[[local|localrc]]
8
+ADMIN_PASSWORD=secret
9
+DATABASE_PASSWORD=$ADMIN_PASSWORD
10
+RABBIT_PASSWORD=$ADMIN_PASSWORD
11
+SERVICE_PASSWORD=$ADMIN_PASSWORD
12
+DEST=/opt/stack
13
+DATA_DIR=/opt/stack/data
14
+LOGFILE=/opt/stack/devstacklog.txt
15
+
16
+
17
+# Enabling manila services
18
+LIBS_FROM_GIT=python-manilaclient
19
+enable_plugin manila git://git.openstack.org/openstack/manila
20
+enable_plugin manila-ui https://github.com/openstack/manila-ui
21
+enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
22
+
23
+
24
+# LVM Backend config options
25
+MANILA_SERVICE_IMAGE_ENABLED=False
26
+SHARE_DRIVER=manila.share.drivers.lvm.LVMShareDriver
27
+MANILA_ENABLED_BACKENDS=chicago,denver
28
+MANILA_BACKEND1_CONFIG_GROUP_NAME=chicago
29
+MANILA_BACKEND2_CONFIG_GROUP_NAME=denver
30
+MANILA_SHARE_BACKEND1_NAME=CHICAGO
31
+MANILA_SHARE_BACKEND2_NAME=DENVER
32
+MANILA_OPTGROUP_chicago_driver_handles_share_servers=False
33
+MANILA_OPTGROUP_denver_driver_handles_share_servers=False
34
+SHARE_BACKING_FILE_SIZE=32000M
35
+MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=True create_share_from_snapshot_support=True revert_to_snapshot_support=True mount_snapshot_support=True'
36
+MANILA_CONFIGURE_DEFAULT_TYPES=True

+ 36
- 0
doc/source/contributor/samples/zfsonlinux_local.conf View File

@@ -0,0 +1,36 @@
1
+######################################################################
2
+# This local.conf sets up Devstack with manila enabling the ZFSOnLinux
3
+# driver which operates in driver_handles_share_services=False
4
+# mode
5
+#######################################################################
6
+
7
+[[local|localrc]]
8
+ADMIN_PASSWORD=secret
9
+DATABASE_PASSWORD=$ADMIN_PASSWORD
10
+RABBIT_PASSWORD=$ADMIN_PASSWORD
11
+SERVICE_PASSWORD=$ADMIN_PASSWORD
12
+DEST=/opt/stack
13
+DATA_DIR=/opt/stack/data
14
+LOGFILE=/opt/stack/devstacklog.txt
15
+
16
+
17
+# Enabling manila services
18
+LIBS_FROM_GIT=python-manilaclient
19
+enable_plugin manila git://git.openstack.org/openstack/manila
20
+enable_plugin manila-ui https://github.com/openstack/manila-ui
21
+enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
22
+
23
+
24
+# ZfsOnLinux Back end config options
25
+MANILA_SERVICE_IMAGE_ENABLED=False
26
+SHARE_DRIVER=manila.share.drivers.zfsonlinux.driver.ZFSonLinuxShareDriver
27
+MANILA_ENABLED_BACKENDS=bangalore,mumbai
28
+MANILA_BACKEND1_CONFIG_GROUP_NAME=bangalore
29
+MANILA_BACKEND2_CONFIG_GROUP_NAME=mumbai
30
+MANILA_SHARE_BACKEND1_NAME=BANGALORE
31
+MANILA_SHARE_BACKEND2_NAME=MUMBAI
32
+MANILA_OPTGROUP_bangalore_driver_handles_share_servers=False
33
+MANILA_OPTGROUP_mumbai_driver_handles_share_servers=False
34
+MANILA_REPLICA_STATE_UPDATE_INTERVAL=60
35
+MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=True create_share_from_snapshot_support=True replication_type=readable'
36
+MANILA_CONFIGURE_DEFAULT_TYPES=True

Loading…
Cancel
Save