summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGoutham Pacha Ravi <gouthampravi@gmail.com>2018-12-21 16:15:52 -0800
committerGoutham Pacha Ravi <gouthampravi@gmail.com>2018-12-26 12:31:44 -0800
commite1619c46260b3f65cb95fa7f030d2b2e36115675 (patch)
treebc34198d66a429a72d08254ab8b6ffa2c51b436d
parenta724e3c27644715779b2ea1b8969894c4a94b8f3 (diff)
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
Notes
Notes (review): Code-Review+2: Tom Barron <tpb@dyncloud.net> Code-Review+2: Thomas Bechtold <tbechtold@suse.com> Workflow+1: Thomas Bechtold <tbechtold@suse.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Wed, 02 Jan 2019 09:27:03 +0000 Reviewed-on: https://review.openstack.org/627020 Project: openstack/manila Branch: refs/heads/master
-rw-r--r--doc/source/contributor/development-environment-devstack.rst199
-rw-r--r--doc/source/contributor/samples/cephfs_local.conf39
-rw-r--r--doc/source/contributor/samples/container_local.conf35
-rw-r--r--doc/source/contributor/samples/generic_local.conf42
-rw-r--r--doc/source/contributor/samples/lvm_local.conf36
-rw-r--r--doc/source/contributor/samples/zfsonlinux_local.conf36
6 files changed, 336 insertions, 51 deletions
diff --git a/doc/source/contributor/development-environment-devstack.rst b/doc/source/contributor/development-environment-devstack.rst
index f22d647..4d60506 100644
--- a/doc/source/contributor/development-environment-devstack.rst
+++ b/doc/source/contributor/development-environment-devstack.rst
@@ -17,90 +17,187 @@ Setting up a development environment with devstack
17 17
18This page describes how to setup a working development 18This page describes how to setup a working development
19environment that can be used in deploying manila on latest releases 19environment that can be used in deploying manila on latest releases
20of Ubuntu or Fedora. These instructions assume you are already familiar 20of Ubuntu, Fedora or CentOS. These instructions assume you are already familiar
21with git. Refer to `Getting the code`_ for additional information. 21with git.
22 22
23.. _Getting the code: http://wiki.openstack.org/GettingTheCode 23We recommend using devstack to develop and test code changes to
24manila or to simply evaluate the manila project. Devstack is a shell script
25to build complete OpenStack development environments on a virtual machine.
26If you are not familar with devstack, these pages can give you context:
24 27
25Following these instructions will allow you to have a fully functional manila 28* `Testing Changes with DevStack <https://docs.openstack.org/contributors/code-and-documentation/devstack.html>`_
26environment using the devstack project (a shell script to build 29* `Devstack project documentation <https://docs.openstack.org/devstack/latest>`_
27complete OpenStack development environments).
28 30
29Configuring devstack with manila 31Be aware that manila is not enabled in devstack by default; you will need to
30-------------------------------- 32add a few lines to the devstack ``local.conf`` file to let devstack deploy and
33configure manila on your virtual machine.
31 34
32Manila 35Getting devstack
33`````` 36----------------
34 37
35Manila can be enabled in devstack by using the plug-in based interface it 38Start by cloning the devstack repository::
36offers.
37 39
38Start by cloning the devstack repository: 40 git clone https://git.openstack.org/openstack-dev/devstack
39 41
40:: 42Change to devstack directory::
41 43
42 git clone https://git.openstack.org/openstack-dev/devstack 44 cd devstack/
43 45
44Change to devstack directory:
45 46
46:: 47You're now on ``master`` branch of devstack, switch to the branch you want
48to test or develop against.
47 49
48 cd devstack/ 50Sample local.conf files that get you started
51--------------------------------------------
49 52
50Copy the local.conf sample file to the upper level directory: 53Now that you have cloned the devstack repository, you need to
54configure devstack before deploying it. This is done with a ``local.conf``
55file. For manila, the local.conf file can also determine which back end(s)
56are 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
56Enable the manila plugin adding the following line to the end of the local.conf file: 65DHSS=False (`driver_handles_share_servers=False`) mode:
66`````````````````````````````````````````````````````````
67This is the easier mode for new contributors. Manila share back-end drivers
68that operate in ``driver_handles_share_servers=False`` mode do not allow
69creating shares on private project networks. On the resulting stack, all
70manila shares created by you are exported on the host network and hence are
71accessible to any compute resource (e.g.: virtual machine, baremetal,
72container) 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 78DHSS=True (`driver_handles_share_servers=True`) mode:
79```````````````````````````````````````````````````````
61 80
62If you would like to install python-manilaclient from git, add to local.conf: 81You may use the following setups if you are familiar with manila,
82and would like to test with the project (tenant) isolation that manila
83provides on the network and data path. Manila share back-end drivers that
84operate in ``driver_handles_share_servers=True`` mode create shares on
85isolated project networks if told to do so. On the resulting stack, when
86creating a share, you must specify a share network to export the share to,
87and the share will be accessible to any compute resource (e.g.: Virtual
88machine, baremetal, containers) that is able to reach the share network you
89indicated.
63 90
64:: 91Typically, new contributors take a while to understand OpenStack networking,
92and we recommend that you familiarize yourself with the DHSS=False mode
93setup 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
68Manila UI
69`````````
70 98
71In order to use the manila UI you will need to enable the UI plugin separately. 99Building your devstack
100----------------------
72 101
73This 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
75Make sure you have horizon enabled (enabled by default in current devstack). 111 ./stack.sh
76 112
77Then, enable the manila UI plugin adding the following line to the end of the local.conf file, 113* After the script completes, you should have manila services running. You can
78just after manila plugin enablement: 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
84Running devstack 123* You may also use your "demo" credentials to invoke the command line
85---------------- 124 clients::
86 125
87Run 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
143More devstack customizations
144----------------------------
145
146Testing branches and changes submitted for review
147`````````````````````````````````````````````````
148
149To test a patch in review::
150
151 enable_plugin manila git://git.openstack.org/openstack/manila <ref>
152
153If 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
157For example, if you want to test patchset 4 of https://review.openstack.org/#/c/614170/,
158you can provide this in your ``local.conf``::
159
160 enable_plugin manila git://git.openstack.org/openstack/manila refs/changes/70/614170/4
161
162ref can also simply be a stable branch name, for example::
163
164 enable_plugin manila git://git.openstack.org/openstack/manila stable/rocky
165
166Limiting the services enabled in your stack
167````````````````````````````````````````````
168
169Manila needs only a message queue (rabbitmq) and a database (mysql,
170postgresql) to operate. Additionally, keystone service provides project
171administration if necessary, all other OpenStack services are not necessary
172to set up a basic test system. [#f1]_ [#f2]_
173
174You can add the following to your ``local.conf`` to deploy your stack in a
175minimal fashion. This saves you a lot of time and resources, but could limit
176your testing::
177
178 ENABLED_SERVICES=key,mysql,rabbit,tempest,manila,m-api,m-sch,m-shr,m-dat
179
180Optionally, 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
93After it completes, you should have manila services running. 189Bootstrapping Tempest
94You can check if they are running by attaching to the screen: 190`````````````````````
95 191
96:: 192Add 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
100And navigating to the manila service tabs (use ctrl+a n, ctrl+a p,
101ctrl+a " <screen number> to navigate,
102ctrl+a esc to enter scrollback mode
103and ctrl+a d to detach from the screen).
104 199
105If you enabled manila UI as well, you should be able to access manila UI 200.. [#f1] The Generic driver cannot be run without deploying Cinder, Nova,
106from the dashboard. 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.
diff --git a/doc/source/contributor/samples/cephfs_local.conf b/doc/source/contributor/samples/cephfs_local.conf
new file mode 100644
index 0000000..99f85a0
--- /dev/null
+++ b/doc/source/contributor/samples/cephfs_local.conf
@@ -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]]
10ADMIN_PASSWORD=secret
11DATABASE_PASSWORD=$ADMIN_PASSWORD
12RABBIT_PASSWORD=$ADMIN_PASSWORD
13SERVICE_PASSWORD=$ADMIN_PASSWORD
14DEST=/opt/stack
15DATA_DIR=/opt/stack/data
16LOGFILE=/opt/stack/devstacklog.txt
17
18
19# Enabling manila services
20LIBS_FROM_GIT=python-manilaclient
21enable_plugin manila git://git.openstack.org/openstack/manila
22enable_plugin manila-ui https://github.com/openstack/manila-ui
23enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
24
25
26# Enabling ceph
27enable_plugin devstack-plugin-ceph git://git.openstack.org/openstack/devstack-plugin-ceph
28ENABLE_CEPH_MANILA=True
29
30
31# IMPORTANT - Comment out / remove the following line to use
32# the CEPH driver with the native CEPHFS protocol
33MANILA_CEPH_DRIVER=cephfsnfs
34
35
36# CEPHFS backend options
37MANILA_SERVICE_IMAGE_ENABLED=False
38MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=False'
39MANILA_CONFIGURE_DEFAULT_TYPES=True \ No newline at end of file
diff --git a/doc/source/contributor/samples/container_local.conf b/doc/source/contributor/samples/container_local.conf
new file mode 100644
index 0000000..89c54a3
--- /dev/null
+++ b/doc/source/contributor/samples/container_local.conf
@@ -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]]
8ADMIN_PASSWORD=secret
9DATABASE_PASSWORD=$ADMIN_PASSWORD
10RABBIT_PASSWORD=$ADMIN_PASSWORD
11SERVICE_PASSWORD=$ADMIN_PASSWORD
12DEST=/opt/stack
13DATA_DIR=/opt/stack/data
14LOGFILE=/opt/stack/devstacklog.txt
15
16
17# Enabling manila services
18LIBS_FROM_GIT=python-manilaclient
19enable_plugin manila git://git.openstack.org/openstack/manila
20enable_plugin manila-ui https://github.com/openstack/manila-ui
21enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
22
23
24# Container Backend config options
25MANILA_SERVICE_IMAGE_ENABLED=False
26SHARE_DRIVER=manila.share.drivers.container.driver.ContainerShareDriver
27MANILA_ENABLED_BACKENDS=vienna,prague
28MANILA_BACKEND1_CONFIG_GROUP_NAME=vienna
29MANILA_BACKEND2_CONFIG_GROUP_NAME=prague
30MANILA_SHARE_BACKEND1_NAME=VIENNA
31MANILA_SHARE_BACKEND2_NAME=PRAGUE
32MANILA_OPTGROUP_vienna_driver_handles_share_servers=True
33MANILA_OPTGROUP_prague_driver_handles_share_servers=True
34MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=false'
35MANILA_CONFIGURE_DEFAULT_TYPES=True
diff --git a/doc/source/contributor/samples/generic_local.conf b/doc/source/contributor/samples/generic_local.conf
new file mode 100644
index 0000000..92c8f2f
--- /dev/null
+++ b/doc/source/contributor/samples/generic_local.conf
@@ -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]]
9ADMIN_PASSWORD=secret
10DATABASE_PASSWORD=$ADMIN_PASSWORD
11RABBIT_PASSWORD=$ADMIN_PASSWORD
12SERVICE_PASSWORD=$ADMIN_PASSWORD
13DEST=/opt/stack
14DATA_DIR=/opt/stack/data
15LOGFILE=/opt/stack/devstacklog.txt
16
17
18# Enabling manila services
19LIBS_FROM_GIT=python-manilaclient
20enable_plugin manila git://git.openstack.org/openstack/manila
21enable_plugin manila-ui https://github.com/openstack/manila-ui
22enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
23
24
25# Generic Back end config options
26SHARE_DRIVER=manila.share.drivers.generic.GenericShareDriver
27MANILA_ENABLED_BACKENDS=tokyo,shanghai
28MANILA_BACKEND1_CONFIG_GROUP_NAME=tokyo
29MANILA_BACKEND2_CONFIG_GROUP_NAME=shanghai
30MANILA_SHARE_BACKEND1_NAME=TOKYO
31MANILA_SHARE_BACKEND2_NAME=SHANGHAI
32MANILA_OPTGROUP_tokyo_driver_handles_share_servers=True
33MANILA_OPTGROUP_shanghai_driver_handles_share_servers=True
34MANILA_OPTGROUP_tokyo_connect_share_server_to_tenant_network=True
35MANILA_OPTGROUP_shanghai_connect_share_server_to_tenant_network=True
36MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=True create_share_from_snapshot_support=True'
37MANILA_CONFIGURE_DEFAULT_TYPES=True
38
39
40# Storage Virtual Machine settings for the generic driver
41MANILA_SERVICE_IMAGE_ENABLED=True
42MANILA_USE_SERVICE_INSTANCE_PASSWORD=True \ No newline at end of file
diff --git a/doc/source/contributor/samples/lvm_local.conf b/doc/source/contributor/samples/lvm_local.conf
new file mode 100644
index 0000000..4b427e4
--- /dev/null
+++ b/doc/source/contributor/samples/lvm_local.conf
@@ -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]]
8ADMIN_PASSWORD=secret
9DATABASE_PASSWORD=$ADMIN_PASSWORD
10RABBIT_PASSWORD=$ADMIN_PASSWORD
11SERVICE_PASSWORD=$ADMIN_PASSWORD
12DEST=/opt/stack
13DATA_DIR=/opt/stack/data
14LOGFILE=/opt/stack/devstacklog.txt
15
16
17# Enabling manila services
18LIBS_FROM_GIT=python-manilaclient
19enable_plugin manila git://git.openstack.org/openstack/manila
20enable_plugin manila-ui https://github.com/openstack/manila-ui
21enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
22
23
24# LVM Backend config options
25MANILA_SERVICE_IMAGE_ENABLED=False
26SHARE_DRIVER=manila.share.drivers.lvm.LVMShareDriver
27MANILA_ENABLED_BACKENDS=chicago,denver
28MANILA_BACKEND1_CONFIG_GROUP_NAME=chicago
29MANILA_BACKEND2_CONFIG_GROUP_NAME=denver
30MANILA_SHARE_BACKEND1_NAME=CHICAGO
31MANILA_SHARE_BACKEND2_NAME=DENVER
32MANILA_OPTGROUP_chicago_driver_handles_share_servers=False
33MANILA_OPTGROUP_denver_driver_handles_share_servers=False
34SHARE_BACKING_FILE_SIZE=32000M
35MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=True create_share_from_snapshot_support=True revert_to_snapshot_support=True mount_snapshot_support=True'
36MANILA_CONFIGURE_DEFAULT_TYPES=True
diff --git a/doc/source/contributor/samples/zfsonlinux_local.conf b/doc/source/contributor/samples/zfsonlinux_local.conf
new file mode 100644
index 0000000..19fad73
--- /dev/null
+++ b/doc/source/contributor/samples/zfsonlinux_local.conf
@@ -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]]
8ADMIN_PASSWORD=secret
9DATABASE_PASSWORD=$ADMIN_PASSWORD
10RABBIT_PASSWORD=$ADMIN_PASSWORD
11SERVICE_PASSWORD=$ADMIN_PASSWORD
12DEST=/opt/stack
13DATA_DIR=/opt/stack/data
14LOGFILE=/opt/stack/devstacklog.txt
15
16
17# Enabling manila services
18LIBS_FROM_GIT=python-manilaclient
19enable_plugin manila git://git.openstack.org/openstack/manila
20enable_plugin manila-ui https://github.com/openstack/manila-ui
21enable_plugin manila-tempest-plugin git://git.openstack.org/openstack/manila-tempest-plugin
22
23
24# ZfsOnLinux Back end config options
25MANILA_SERVICE_IMAGE_ENABLED=False
26SHARE_DRIVER=manila.share.drivers.zfsonlinux.driver.ZFSonLinuxShareDriver
27MANILA_ENABLED_BACKENDS=bangalore,mumbai
28MANILA_BACKEND1_CONFIG_GROUP_NAME=bangalore
29MANILA_BACKEND2_CONFIG_GROUP_NAME=mumbai
30MANILA_SHARE_BACKEND1_NAME=BANGALORE
31MANILA_SHARE_BACKEND2_NAME=MUMBAI
32MANILA_OPTGROUP_bangalore_driver_handles_share_servers=False
33MANILA_OPTGROUP_mumbai_driver_handles_share_servers=False
34MANILA_REPLICA_STATE_UPDATE_INTERVAL=60
35MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=True create_share_from_snapshot_support=True replication_type=readable'
36MANILA_CONFIGURE_DEFAULT_TYPES=True