diff --git a/.gitignore b/.gitignore index c5deeffcf3..7ccb8ba6cb 100644 --- a/.gitignore +++ b/.gitignore @@ -39,6 +39,9 @@ api-ref/build # Files created by releasenotes build releasenotes/build +# Files created by install-guide builds +install-guide/build + # Development environment files .project .pydevproject diff --git a/install-guide/source/common/controller-node-common-configuration.rst b/install-guide/source/common/controller-node-common-configuration.rst new file mode 100644 index 0000000000..d4f257c6a7 --- /dev/null +++ b/install-guide/source/common/controller-node-common-configuration.rst @@ -0,0 +1,71 @@ +3. Complete the rest of the configuration in ``manila.conf``: + + * In the ``[DEFAULT]`` and ``[oslo_messaging_rabbit]`` sections, configure + ``RabbitMQ`` message queue access: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace ``RABBIT_PASS`` with the password you chose for the ``openstack`` + account in ``RabbitMQ``. + + * In the ``[DEFAULT]`` section, set the following config values: + + .. code-block:: ini + + [DEFAULT] + ... + default_share_type = default_share_type + share_name_template = share-%s + rootwrap_config = /etc/manila/rootwrap.conf + api_paste_config = /etc/manila/api-paste.ini + + * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections, configure + Identity service access: + + .. code-block:: ini + + [DEFAULT] + ... + auth_strategy = keystone + + [keystone_authtoken] + ... + memcached_servers = controller:11211 + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + auth_type = password + project_domain_id = default + user_domain_id = default + project_name = service + username = manila + password = MANILA_PASS + + Replace ``MANILA_PASS`` with the password you chose for the ``manila`` + user in the Identity service. + + * In the ``[DEFAULT]`` section, configure the ``my_ip`` option to use the + management interface IP address of the controller node: + + .. code-block:: ini + + [DEFAULT] + ... + my_ip = 10.0.0.11 + + * In the ``[oslo_concurrency]`` section, configure the lock path: + + .. code-block:: ini + + [oslo_concurrency] + ... + lock_path = /var/lock/manila diff --git a/install-guide/source/common/controller-node-prerequisites.rst b/install-guide/source/common/controller-node-prerequisites.rst new file mode 100644 index 0000000000..f30838f138 --- /dev/null +++ b/install-guide/source/common/controller-node-prerequisites.rst @@ -0,0 +1,208 @@ +Prerequisites +------------- + +Before you install and configure the Shared File Systems service, you +must create a database, service credentials, and `API endpoints`. + +#. To create the database, complete these steps: + + * Use the database access client to connect to the database server as the + ``root`` user: + + .. code-block:: console + + $ mysql -u root -p + + * Create the `manila` database: + + .. code-block:: console + + CREATE DATABASE manila; + + * Grant proper access to the ``manila`` database: + + .. code-block:: console + + GRANT ALL PRIVILEGES ON manila.* TO 'manila'@'localhost' \ + IDENTIFIED BY 'MANILA_DBPASS'; + GRANT ALL PRIVILEGES ON manila.* TO 'manila'@'%' \ + IDENTIFIED BY 'MANILA_DBPASS'; + + Replace ``MANILA_DBPASS`` with a suitable password. + + * Exit the database access client. + +#. Source the ``admin`` credentials to gain access to admin CLI commands: + + .. code-block:: console + + $ . admin-openrc.sh + +#. To create the service credentials, complete these steps: + + * Create a ``manila`` user: + + .. code-block:: console + + $ openstack user create --domain default --password-prompt manila + User Password: + Repeat User Password: + +-----------+----------------------------------+ + | Field | Value | + +-----------+----------------------------------+ + | domain_id | e0353a670a9e496da891347c589539e9 | + | enabled | True | + | id | 83a3990fc2144100ba0e2e23886d8acc | + | name | manila | + +-----------+----------------------------------+ + + * Add the ``admin`` role to the ``manila`` user: + + .. code-block:: console + + $ openstack role add --project service --user manila admin + + .. note:: + + This command provides no output. + + * Create the ``manila`` and ``manilav2`` service entities: + + .. code-block:: console + + $ openstack service create --name manila \ + --description "OpenStack Shared File Systems" share + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | OpenStack Shared File Systems | + | enabled | True | + | id | 82378b5a16b340aa9cc790cdd46a03ba | + | name | manila | + | type | share | + +-------------+----------------------------------+ + + .. code-block:: console + + $ openstack service create --name manilav2 \ + --description "OpenStack Shared File Systems" sharev2 + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | OpenStack Shared File Systems | + | enabled | True | + | id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | name | manilav2 | + | type | sharev2 | + +-------------+----------------------------------+ + + .. note:: + + The Shared File Systems services require two service entities. + +#. Create the Shared File Systems service API endpoints: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + share public http://controller:8786/v1/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | 0bd2bbf8d28b433aaea56a254c69f69d | + | interface | public | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 82378b5a16b340aa9cc790cdd46a03ba | + | service_name | manila | + | service_type | share | + | url | http://controller:8786/v1/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + share internal http://controller:8786/v1/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | a2859b5732cc48b5b083dd36dafb6fd9 | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 82378b5a16b340aa9cc790cdd46a03ba | + | service_name | manila | + | service_type | share | + | url | http://controller:8786/v1/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + share admin http://controller:8786/v1/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | f7f46df93a374cc49c0121bef41da03c | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 82378b5a16b340aa9cc790cdd46a03ba | + | service_name | manila | + | service_type | share | + | url | http://controller:8786/v1/%(tenant_id)s | + +--------------+-----------------------------------------+ + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + sharev2 public http://controller:8786/v2/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | d63cc0d358da4ea680178657291eddc1 | + | interface | public | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | service_name | manilav2 | + | service_type | sharev2 | + | url | http://controller:8786/v2/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + sharev2 internal http://controller:8786/v2/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | afc86e5f50804008add349dba605da54 | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | service_name | manilav2 | + | service_type | sharev2 | + | url | http://controller:8786/v2/%(tenant_id)s | + +--------------+-----------------------------------------+ + + $ openstack endpoint create --region RegionOne \ + sharev2 admin http://controller:8786/v2/%\(tenant_id\)s + +--------------+-----------------------------------------+ + | Field | Value | + +--------------+-----------------------------------------+ + | enabled | True | + | id | e814a0cec40546e98cf0c25a82498483 | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 30d92a97a81a4e5d8fd97a32bafd7b88 | + | service_name | manilav2 | + | service_type | sharev2 | + | url | http://controller:8786/v2/%(tenant_id)s | + +--------------+-----------------------------------------+ + + .. note:: + + The Shared File Systems services require endpoints for each service + entity. diff --git a/install-guide/source/common/dhss-false-mode-configuration.rst b/install-guide/source/common/dhss-false-mode-configuration.rst new file mode 100644 index 0000000000..b8d6e2cf6f --- /dev/null +++ b/install-guide/source/common/dhss-false-mode-configuration.rst @@ -0,0 +1,98 @@ +2. Create the LVM physical volume ``/dev/sdc``: + + .. code-block:: console + + # pvcreate /dev/sdc + Physical volume "/dev/sdc" successfully created + +#. Create the LVM volume group ``manila-volumes``: + + .. code-block:: console + + # vgcreate manila-volumes /dev/sdc + Volume group "manila-volumes" successfully created + + The Shared File Systems service creates logical volumes in this volume + group. + +#. Only instances can access Shared File Systems service volumes. However, + the underlying operating system manages the devices associated with + the volumes. By default, the LVM volume scanning tool scans the + ``/dev`` directory for block storage devices that + contain volumes. If projects use LVM on their volumes, the scanning + tool detects these volumes and attempts to cache them which can cause + a variety of problems with both the underlying operating system + and project volumes. You must reconfigure LVM to scan only the devices + that contain the ``cinder-volume`` and ``manila-volumes`` volume groups. + Edit the ``/etc/lvm/lvm.conf`` file and complete the following actions: + + * In the ``devices`` section, add a filter that accepts the + ``/dev/sdb`` and ``/dev/sdc`` devices and rejects all other devices: + + .. code-block:: ini + + devices { + ... + filter = [ "a/sdb/", "a/sdc", "r/.*/"] + + .. warning:: + + If your storage nodes use LVM on the operating system disk, you + must also add the associated device to the filter. For example, + if the ``/dev/sda`` device contains the operating system: + + .. code-block:: ini + + filter = [ "a/sda/", "a/sdb/", "a/sdc", "r/.*/"] + + Similarly, if your compute nodes use LVM on the operating + system disk, you must also modify the filter in the + ``/etc/lvm/lvm.conf`` file on those nodes to include only + the operating system disk. For example, if the ``/dev/sda`` + device contains the operating system: + + .. code-block:: ini + + filter = [ "a/sda/", "r/.*/"] + +Configure components +-------------------- + +#. Edit the ``/etc/manila/manila.conf`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, enable the LVM driver and the NFS/CIFS + protocols: + + .. code-block:: ini + + [DEFAULT] + ... + enabled_share_backends = lvm + enabled_share_protocols = NFS,CIFS + + .. note:: + + Back end names are arbitrary. As an example, this guide uses the name + of the driver. + + * In the ``[lvm]`` section, configure the LVM driver: + + .. code-block:: ini + + [lvm] + share_backend_name = LVM + share_driver = manila.share.drivers.lvm.LVMShareDriver + driver_handles_share_servers = False + lvm_share_volume_group = manila-volumes + lvm_share_export_ip = MANAGEMENT_INTERFACE_IP_ADDRESS + + Replace ``MANAGEMENT_INTERFACE_IP_ADDRESS`` with the IP address + of the management network interface on your storage node, + typically 10.0.0.41 for the first node in the the example architecture + shown below: + + .. figure:: figures/hwreqs.png + :alt: Hardware requirements + + **Hardware requirements**. diff --git a/install-guide/source/common/dhss-false-mode-intro.rst b/install-guide/source/common/dhss-false-mode-intro.rst new file mode 100644 index 0000000000..fa611163ec --- /dev/null +++ b/install-guide/source/common/dhss-false-mode-intro.rst @@ -0,0 +1,7 @@ +Shared File Systems Option 1: No driver support for share servers management +---------------------------------------------------------------------------- +For simplicity, this configuration references the same storage node +configuration for the Block Storage service. However, the LVM driver +requires a separate empty local block storage device to avoid conflict +with the Block Storage service. The instructions use ``/dev/sdc``, but +you can substitute a different value for your particular node. diff --git a/install-guide/source/common/dhss-true-mode-configuration.rst b/install-guide/source/common/dhss-true-mode-configuration.rst new file mode 100644 index 0000000000..e2318c53bf --- /dev/null +++ b/install-guide/source/common/dhss-true-mode-configuration.rst @@ -0,0 +1,84 @@ +Configure components +-------------------- + +#. Edit the ``/etc/manila/manila.conf`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, enable the generic driver and the NFS/CIFS + protocols: + + .. code-block:: ini + + [DEFAULT] + ... + enabled_share_backends = generic + enabled_share_protocols = NFS,CIFS + + .. note:: + + Back end names are arbitrary. As an example, this guide uses the name + of the driver. + + * In the ``[neutron]``, ``[nova]``, and ``[cinder]`` sections, enable + authentication for those services: + + .. code-block:: ini + + [neutron] + ... + url = http://controller:9696 + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + memcached_servers = controller:11211 + auth_type = password + project_domain_name = default + user_domain_name = default + region_name = RegionOne + project_name = service + username = neutron + password = NEUTRON_PASS + + [nova] + ... + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + memcached_servers = controller:11211 + auth_type = password + project_domain_name = default + user_domain_name = default + region_name = RegionOne + project_name = service + username = nova + password = NOVA_PASS + + [cinder] + ... + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + memcached_servers = controller:11211 + auth_type = password + project_domain_name = default + user_domain_name = default + region_name = RegionOne + project_name = service + username = cinder + password = CINDER_PASS + + * In the ``[generic]`` section, configure the generic driver: + + .. code-block:: ini + + [generic] + share_backend_name = GENERIC + share_driver = manila.share.drivers.generic.GenericShareDriver + driver_handles_share_servers = True + service_instance_flavor_id = 100 + service_image_name = manila-service-image + service_instance_user = manila + service_instance_password = manila + interface_driver = manila.network.linux.interface.BridgeInterfaceDriver + + .. note:: + + You can also use SSH keys instead of password authentication for + service instance credentials. diff --git a/install-guide/source/common/dhss-true-mode-intro.rst b/install-guide/source/common/dhss-true-mode-intro.rst new file mode 100644 index 0000000000..fa775e5411 --- /dev/null +++ b/install-guide/source/common/dhss-true-mode-intro.rst @@ -0,0 +1,15 @@ +Shared File Systems Option 2: Driver support for share servers management +------------------------------------------------------------------------- + +For simplicity, this configuration references the same storage node +configuration for the Block Storage service. + +.. note:: + + This guide describes how to configure the Shared File Systems service to + use the ``generic`` driver with the driver handles share server mode + (DHSS) enabled. This mode requires Compute (nova), Networking (neutron) and + Block storage (cinder) services for managing share servers. The information + used for creating share servers is configured as share networks. Generic + driver with DHSS enabled also requires network to be attached to a public + router. \ No newline at end of file diff --git a/install-guide/source/common/share-node-common-configuration.rst b/install-guide/source/common/share-node-common-configuration.rst new file mode 100644 index 0000000000..1a6eeeedc6 --- /dev/null +++ b/install-guide/source/common/share-node-common-configuration.rst @@ -0,0 +1,77 @@ +4. Complete the rest of the configuration in ``manila.conf``. + + * In the ``[DEFAULT]`` and ``[oslo_messaging_rabbit]`` sections, + configure ``RabbitMQ`` message queue access: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace ``RABBIT_PASS`` with the password you chose for the + ``openstack`` account in ``RabbitMQ``. + + * In the ``[DEFAULT]`` section, set the following config values: + + .. code-block:: ini + + [DEFAULT] + ... + default_share_type = default_share_type + rootwrap_config = /etc/manila/rootwrap.conf + + * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections, configure + Identity service access: + + .. code-block:: ini + + [DEFAULT] + ... + auth_strategy = keystone + + [keystone_authtoken] + ... + memcached_servers = controller:11211 + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + auth_type = password + project_domain_id = default + user_domain_id = default + project_name = service + username = manila + password = MANILA_PASS + + Replace ``MANILA_PASS`` with the password you chose for the ``manila`` + user in the Identity service. + + * In the ``[DEFAULT]`` section, configure the ``my_ip`` option: + + .. code-block:: ini + + [DEFAULT] + ... + my_ip = MANAGEMENT_INTERFACE_IP_ADDRESS + + Replace ``MANAGEMENT_INTERFACE_IP_ADDRESS`` with the IP address of the + management network interface on your share node, typically 10.0.0.41 for + the first node in the example architecture shown below: + + .. figure:: figures/hwreqs.png + :alt: Hardware requirements + + **Hardware requirements** + + * In the ``[oslo_concurrency]`` section, configure the lock path: + + .. code-block:: ini + + [oslo_concurrency] + ... + lock_path = /var/lib/manila/tmp diff --git a/install-guide/source/common/share-node-share-server-modes.rst b/install-guide/source/common/share-node-share-server-modes.rst new file mode 100644 index 0000000000..ed1a1d9beb --- /dev/null +++ b/install-guide/source/common/share-node-share-server-modes.rst @@ -0,0 +1,36 @@ +The share node can support two modes, with and without the handling of +share servers. The mode depends on driver support. + +Option 1 +-------- +Deploying the service without driver support for share management. +In this mode, the service does not do anything related to networking. The +operator must ensure network connectivity between instances and the NFS +server. This tutorial demonstrates setting up the LVM driver to support this +driver mode. It requires LVM and NFS packages as well as an additional disk +for the ``manila-share`` LVM volume group. This driver +mode may be referred to as ``driver_handles_share_servers = False`` mode, or +simply ``DHSS=False`` mode. + +Option 2 +-------- +Deploying the service with driver support for share management. In +this mode, the service runs with a back end driver that creates and manages +share servers. This tutorial demonstrates setting up the Generic driver. +This driver requires Compute (nova), Networking (neutron) and Block +storage (cinder) services for managing share servers. The information used for +creating share servers is configured with the help of share networks. This +option uses the generic driver with the handling of share servers capacity +and requires attaching the ``selfservice`` network to a router. This driver +mode may be referred to as ``driver_handles_share_servers = True`` mode, or +simply ``DHSS=True`` mode. + +.. warning:: + + When running the generic driver in ``DHSS=True`` driver mode, the share + service should be run on the same node as the networking service. + However, such a service may not be able to run the LVM driver that runs + in ``DHSS=False`` driver mode effectively, due to a bug in some + distributions of Linux. For more information, see LVM Driver section in the + `Configuration Reference Guide + `_. \ No newline at end of file diff --git a/install-guide/source/conf.py b/install-guide/source/conf.py new file mode 100644 index 0000000000..0a012b6df2 --- /dev/null +++ b/install-guide/source/conf.py @@ -0,0 +1,306 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os + + +import openstackdocstheme + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' +# extensions = + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Installation Guide for Shared File Systems Service' +bug_tag = u'install-guide' +copyright = u'2016, OpenStack contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# A few variables have to be set for the log-a-bug feature. +# giturl: The location of conf.py on Git. Must be set manually. +# gitsha: The SHA checksum of the bug description. Automatically +# extracted from git log. +# bug_tag: Tag for categorizing the bug. Must be set manually. +# These variables are passed to the logabug code via html_context. +giturl = u'http://git.openstack.org/cgit/openstack/manila/tree/install-guide/source' +git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '" +gitsha = os.popen(git_cmd).read().strip('\n') +# source tree +pwd = os.getcwd() +html_context = { + "pwd": pwd, + "gitsha": gitsha, + "bug_tag": bug_tag, + "giturl": giturl, + "bug_project": "manila", +} + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["common/*.rst"] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'openstackdocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = [openstackdocstheme.get_html_theme_path()] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = [] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# So that we can enable "log-a-bug" links from each output HTML page, this +# variable must be set to a format that includes year, month, day, hours and +# minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'install-guide' + +# If true, publish source files +html_copy_source = False + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # 'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'InstallGuide.tex', u'Install Guide', + u'OpenStack contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'installguide', u'Install Guide', + [u'OpenStack contributors'], 1) +] + +# If true, show URL addresses after external links. +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'InstallGuide', u'Install Guide', + u'OpenStack contributors', 'InstallGuide', + 'This guide shows OpenStack end users how to install ' + 'an OpenStack cloud.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + +# -- Options for Internationalization output ------------------------------ +locale_dirs = ['locale/'] + +# -- Options for PDF output -------------------------------------------------- + +pdf_documents = [ + ('index', u'InstallGuide', u'Install Guide', + u'OpenStack contributors') +] diff --git a/install-guide/source/figures/hwreqs.graffle b/install-guide/source/figures/hwreqs.graffle new file mode 100644 index 0000000000..522bb03cba Binary files /dev/null and b/install-guide/source/figures/hwreqs.graffle differ diff --git a/install-guide/source/figures/hwreqs.png b/install-guide/source/figures/hwreqs.png new file mode 100644 index 0000000000..5c7e2d0e8b Binary files /dev/null and b/install-guide/source/figures/hwreqs.png differ diff --git a/install-guide/source/figures/hwreqs.svg b/install-guide/source/figures/hwreqs.svg new file mode 100644 index 0000000000..0b58db752f --- /dev/null +++ b/install-guide/source/figures/hwreqs.svg @@ -0,0 +1,3 @@ + + + Produced by OmniGraffle 6.5.2 2016-04-26 14:57:28 +0000Canvas 1Layer 1Controller NodeCompute Node 11-2CPUBlock Storage Node 1Object Storage Node 1Object Storage Node 2Hardware RequirementsCore componentOptional component8 GBRAM100 GBStorage2-4+CPU8+ GBRAM100+ GBStorage1-2CPU4 GBRAM2NIC2NIC1NIC1NIC4+ GBRAM1-2CPU1NIC100+ GBStorage100+ GBStorage/dev/sdb/dev/sdb/dev/sdc/dev/sdb/dev/sdc1-2CPU4+ GBRAM100+ GBStorage/dev/sdc diff --git a/install-guide/source/get-started-with-shared-file-systems.rst b/install-guide/source/get-started-with-shared-file-systems.rst new file mode 100644 index 0000000000..b5b8e49624 --- /dev/null +++ b/install-guide/source/get-started-with-shared-file-systems.rst @@ -0,0 +1,39 @@ +==================================== +Shared File Systems service overview +==================================== + +The OpenStack Shared File Systems service (manila) provides file storage to a +virtual machine. The Shared File Systems service provides an infrastructure +for managing and provisioning of file shares. The service also enables +management of share types as well as share snapshots if a driver supports +them. + +The Shared File Systems service consists of the following components: + +manila-api + A WSGI app that authenticates and routes requests throughout the Shared File + Systems service. It supports the OpenStack APIs. + +manila-data + A standalone service whose purpose is to receive requests, process data + operations such as copying, share migration or backup, and send back a + response after an operation has been completed. + +manila-scheduler + Schedules and routes requests to the appropriate share service. The + scheduler uses configurable filters and weighers to route requests. The + Filter Scheduler is the default and enables filters on things like Capacity, + Availability Zone, Share Types, and Capabilities as well as custom filters. + +manila-share + Manages back-end devices that provide shared file systems. A manila-share + process can run in one of two modes, with or without handling of share + servers. Share servers export file shares via share networks. When share + servers are not used, the networking requirements are handled outside of + Manila. + +Messaging queue + Routes information between the Shared File Systems processes. + +For more information, see `Configuration Reference Guide +`_. diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst new file mode 100644 index 0000000000..8f8282070f --- /dev/null +++ b/install-guide/source/index.rst @@ -0,0 +1,46 @@ +========================================= +Shared File Systems Installation Tutorial +========================================= + +.. toctree:: + :maxdepth: 2 + + get-started-with-shared-file-systems.rst + install-controller-node.rst + install-share-node.rst + verify.rst + post-install.rst + next-steps.rst + + +The OpenStack Shared File Systems service (manila) provides coordinated +access to shared or distributed file systems. The method in which the share is +provisioned and consumed is determined by the Shared File Systems driver, or +drivers in the case of a multi-backend configuration. There are a variety of +drivers that support NFS, CIFS, HDFS, GlusterFS, CEPHFS and other protocols +as well. + +The Shared File Systems API and scheduler services typically run on the +controller nodes. Depending upon the drivers used, the share service can run +on controllers, compute nodes, or storage nodes. + +.. important:: + + For simplicity, this guide describes configuring the Shared File Systems + service to use the ``generic`` back end with the driver handles + share server mode (DHSS) enabled that uses the `Compute service` + (`nova`), `Networking service` (`neutron`) and `Block storage service` + (`cinder`). + + Networking service configuration requires the capability of networks being + attached to a public router in order to create share networks. + + Before you proceed, ensure that Compute, Networking and Block storage + services are properly working. For networking service, ensure that option + 2 is properly configured. + +For more information, see the `Configuration Reference +`_. + +This chapter assumes a working setup of OpenStack following the `OpenStack +Installation Tutorial `_ diff --git a/install-guide/source/install-controller-debian.rst b/install-guide/source/install-controller-debian.rst new file mode 100644 index 0000000000..3fb0a2cbaa --- /dev/null +++ b/install-guide/source/install-controller-debian.rst @@ -0,0 +1,56 @@ +.. _manila-controller-debian: + +Install and configure controller node on Debian +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Shared File Systems +service, code-named manila, on the controller node that runs a Debian +distribution. This service requires at least one additional share node that +manages file storage back ends. + +.. include:: common/controller-node-prerequisites.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install manila-api manila-scheduler python-manilaclient + +#. Edit the ``/etc/manila/manila.conf`` file and complete the following + actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://manila:MANILA_DBPASS@controller/manila + + Replace ``MANILA_DBPASS`` with the password you chose for the Shared + File Systems database. + +.. include:: common/controller-node-common-configuration.rst + +#. Populate the Shared File Systems database: + + .. code-block:: console + + # su -s /bin/sh -c "manila-manage db sync" manila + + .. note:: + + Ignore any deprecation messages in this output. + +Finalize installation +--------------------- + +#. Restart the Shared File Systems services: + + .. code-block:: console + + # service manila-scheduler restart + # service manila-api restart diff --git a/install-guide/source/install-controller-node.rst b/install-guide/source/install-controller-node.rst new file mode 100644 index 0000000000..e68c20d355 --- /dev/null +++ b/install-guide/source/install-controller-node.rst @@ -0,0 +1,22 @@ +.. _manila-controller: + +Install and configure controller node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Shared File Systems +service, code-named manila, on the controller node. This service requires at +least one additional share node that manages file storage back ends. + +This section assumes that you already have a working OpenStack +environment with at least the following components installed: +Compute, Image Service, Identity. + +Note that installation and configuration vary by distribution. + +.. toctree:: + :maxdepth: 1 + + install-controller-obs.rst + install-controller-rdo.rst + install-controller-ubuntu.rst + install-controller-debian.rst diff --git a/install-guide/source/install-controller-obs.rst b/install-guide/source/install-controller-obs.rst new file mode 100644 index 0000000000..d7750222d7 --- /dev/null +++ b/install-guide/source/install-controller-obs.rst @@ -0,0 +1,47 @@ +.. _manila-controller-obs: + +Install and configure controller node on openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Shared File Systems +service, code-named manila, on the controller node that runs openSUSE and SUSE +Linux Enterprise. This service requires at least one additional share node +that manages file storage back ends. + +.. include:: common/controller-node-prerequisites.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # zypper install openstack-manila-api openstack-manila-scheduler python-manilaclient + +#. Edit the ``/etc/manila/manila.conf`` file and complete the + following actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://manila:MANILA_DBPASS@controller/manila + + Replace ``MANILA_DBPASS`` with the password you chose for the Shared + File Systems database. + +.. include:: common/controller-node-common-configuration.rst + +Finalize installation +--------------------- + +#. Start the Shared File Systems services and configure them to start when + the system boots: + + .. code-block:: console + + # systemctl enable openstack-manila-api.service openstack-manila-scheduler.service + # systemctl start openstack-manila-api.service openstack-manila-scheduler.service diff --git a/install-guide/source/install-controller-rdo.rst b/install-guide/source/install-controller-rdo.rst new file mode 100644 index 0000000000..e783cad49a --- /dev/null +++ b/install-guide/source/install-controller-rdo.rst @@ -0,0 +1,57 @@ +.. _manila-controller-rdo: + +Install and configure controller node on Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Shared File Systems +service, code-named manila, on the controller node that runs Red Hat +Enterprise Linux or CentOS. This service requires at least one additional +share node that manages file storage back ends. + +.. include:: common/controller-node-prerequisites.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # yum install openstack-manila python-manilaclient + +#. Edit the ``/etc/manila/manila.conf`` file and complete the + following actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://manila:MANILA_DBPASS@controller/manila + + Replace ``MANILA_DBPASS`` with the password you chose for the Shared + File Systems database. + +.. include:: common/controller-node-common-configuration.rst + +#. Populate the Shared File Systems database: + + .. code-block:: console + + # su -s /bin/sh -c "manila-manage db sync" manila + + .. note:: + + Ignore any deprecation messages in this output. + +Finalize installation +--------------------- + +#. Start the Shared File Systems services and configure them to start when + the system boots: + + .. code-block:: console + + # systemctl enable openstack-manila-api.service openstack-manila-scheduler.service + # systemctl start openstack-manila-api.service openstack-manila-scheduler.service diff --git a/install-guide/source/install-controller-ubuntu.rst b/install-guide/source/install-controller-ubuntu.rst new file mode 100644 index 0000000000..72f19505f2 --- /dev/null +++ b/install-guide/source/install-controller-ubuntu.rst @@ -0,0 +1,64 @@ +.. _manila-controller-ubuntu: + +Install and configure controller node on Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the Shared File Systems +service, code-named manila, on the controller node that runs Ubuntu. This +service requires at least one additional share node that manages file +storage back ends. + +.. include:: common/controller-node-prerequisites.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install manila-api manila-scheduler python-manilaclient + +#. Edit the ``/etc/manila/manila.conf`` file and complete the + following actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://manila:MANILA_DBPASS@controller/manila + + Replace ``MANILA_DBPASS`` with the password you chose for the Shared + File Systems database. + +.. include:: common/controller-node-common-configuration.rst + +#. Populate the Shared File Systems database: + + .. code-block:: console + + # su -s /bin/sh -c "manila-manage db sync" manila + + .. note:: + + Ignore any deprecation messages in this output. + +Finalize installation +--------------------- + +#. Restart the Shared File Systems services: + + .. code-block:: console + + # service manila-scheduler restart + # service manila-api restart + +#. By default, the Ubuntu packages create an SQLite database. Because this + configuration uses an SQL database server, you can remove the SQLite + database file: + + .. code-block:: console + + # rm -f /var/lib/manila/manila.sqlite diff --git a/install-guide/source/install-share-debian.rst b/install-guide/source/install-share-debian.rst new file mode 100644 index 0000000000..b9f979c031 --- /dev/null +++ b/install-guide/source/install-share-debian.rst @@ -0,0 +1,91 @@ +.. _share-node-install-debian: + +Install and configure a share node running Debian +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure a share node for the +Shared File Systems service. For simplicity, this configuration references one +storage node with the generic driver managing the share servers. The +generic backend manages share servers using compute, networking and block +services for provisioning shares. + +Note that installation and configuration vary by distribution. This section +describes the instructions for a share node running a Debian distribution. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install manila-share python-pymysql + +#. Edit the ``/etc/manila/manila.conf`` file and complete the following + actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://manila:MANILA_DBPASS@controller/manila + + Replace ``MANILA_DBPASS`` with the password you chose for the Shared + File Systems database. + +.. include:: common/share-node-common-configuration.rst + +Two driver modes +---------------- + +.. include:: common/share-node-share-server-modes.rst + +Choose one of the following options to configure the share driver: + +.. include:: common/dhss-false-mode-intro.rst + +Prerequisites +------------- + +.. note:: + + Perform these steps on the storage node. + +#. Install the supporting utility packages: + + * Install LVM and NFS server packages: + + .. code-block:: console + + # apt-get install lvm2 nfs-kernel-server + +.. include:: common/dhss-false-mode-configuration.rst + +.. include:: common/dhss-true-mode-intro.rst + +Prerequisites +------------- + +Before you proceed, verify operation of the Compute, Networking, and Block +Storage services. This options requires implementation of Networking option 2 +and requires installation of some Networking service components on the storage +node. + +* Install the Networking service components: + + .. code-block:: console + + # apt-get install neutron-plugin-linuxbridge-agent + +.. include:: common/dhss-true-mode-configuration.rst + +Finalize installation +--------------------- +#. Prepare manila-share as start/stop service. Start the Shared File Systems + service including its dependencies: + + .. code-block:: console + + # service manila-share restart diff --git a/install-guide/source/install-share-node.rst b/install-guide/source/install-share-node.rst new file mode 100644 index 0000000000..0be037fdea --- /dev/null +++ b/install-guide/source/install-share-node.rst @@ -0,0 +1,21 @@ +.. _share-node-install: + +Install and configure a share node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure a share node for the +Shared File Systems service. + +.. Note:: + The manila-share process can run in two modes, with and without handling of + share servers. In general it depends of the driver support. + +Note that installation and configuration vary by distribution. + +.. toctree:: + :maxdepth: 1 + + install-share-obs.rst + install-share-rdo.rst + install-share-ubuntu.rst + install-share-debian.rst diff --git a/install-guide/source/install-share-obs.rst b/install-guide/source/install-share-obs.rst new file mode 100644 index 0000000000..2b12dddc3e --- /dev/null +++ b/install-guide/source/install-share-obs.rst @@ -0,0 +1,90 @@ +.. _share-node-install-obs: + +Install and configure a share node running openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure a share node for the +Shared File Systems service. + +Note that installation and configuration vary by distribution. This section +describes the instructions for a share node running openSUSE and SUSE Linux +Enterprise. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # zypper install openstack-manila-share python-PyMySQL + +#. Edit the ``/etc/manila/manila.conf`` file and complete the following + actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://manila:MANILA_DBPASS@controller/manila + + Replace ``MANILA_DBPASS`` with the password you chose for + the Shared File Systems database. + +.. include:: common/share-node-common-configuration.rst + +Two driver modes +---------------- + +.. include:: common/share-node-share-server-modes.rst + +Choose one of the following options to configure the share driver: + +.. include:: common/dhss-false-mode-intro.rst + +Prerequisites +------------- + +.. note:: + Perform these steps on the storage node. + +#. Install the supporting utility packages: + + * Install LVM and NFS server packages: + + .. code-block:: console + + # zypper install lvm2 nfs-kernel-server + +.. include:: common/dhss-false-mode-configuration.rst + +.. include:: common/dhss-true-mode-intro.rst + +Prerequisites +------------- + +Before you proceed, verify operation of the Compute, Networking, and Block +Storage services. This options requires implementation of Networking option 2 +and requires installation of some Networking service components on the storage +node. + +* Install the Networking service components: + + .. code-block:: console + + # zypper install --no-recommends openstack-neutron-linuxbridge-agent + +.. include:: common/dhss-true-mode-configuration.rst + +Finalize installation +--------------------- +#. Prepare manila-share as start/stop service. Start the Shared File Systems + service including its dependencies and configure them to start when the + system boots: + + .. code-block:: console + + # systemctl enable openstack-manila-share.service tgtd.service + # systemctl start openstack-manila-share.service tgtd.service diff --git a/install-guide/source/install-share-rdo.rst b/install-guide/source/install-share-rdo.rst new file mode 100644 index 0000000000..70de997577 --- /dev/null +++ b/install-guide/source/install-share-rdo.rst @@ -0,0 +1,103 @@ +.. _share-node-install-rdo: + +Install and configure a share node running Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure a share node for the +Shared File Systems service. For simplicity, this configuration references one +storage node with the generic driver managing the share servers. The +generic backend manages share servers using compute, networking and block +services for provisioning shares. + +Note that installation and configuration vary by distribution. This section +describes the instructions for a share node running Red Hat Enterprise Linux +or CentOS. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # yum install openstack-manila-share python2-PyMySQL + +#. Edit the ``/etc/manila/manila.conf`` file and complete the following + actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql://manila:MANILA_DBPASS@controller/manila + + + Replace ``MANILA_DBPASS`` with the password you chose for + the Shared File Systems database. + +.. include:: common/share-node-common-configuration.rst + +Two driver modes +---------------- + +.. include:: common/share-node-share-server-modes.rst + +Choose one of the following options to configure the share driver: + +.. include:: common/dhss-false-mode-intro.rst + +Prerequisites +------------- + +.. note:: + + Perform these steps on the storage node. + +#. Install the supporting utility packages: + + * Install LVM and NFS server packages: + + .. code-block:: console + + # yum install lvm2 nfs-utils nfs4-acl-tools portmap + + * Start the LVM metadata service and configure it to start when the + system boots: + + .. code-block:: console + + # systemctl enable lvm2-lvmetad.service + # systemctl start lvm2-lvmetad.service + +.. include:: common/dhss-false-mode-configuration.rst + +.. include:: common/dhss-true-mode-intro.rst + +Prerequisites +------------- + +Before you proceed, verify operation of the Compute, Networking, and Block +Storage services. This options requires implementation of Networking option 2 +and requires installation of some Networking service components on the storage +node. + +* Install the Networking service components: + + .. code-block:: console + + # yum install openstack-neutron openstack-neutron-linuxbridge ebtables + +.. include:: common/dhss-true-mode-configuration.rst + +Finalize installation +--------------------- +#. Prepare manila-share as start/stop service. Start the Shared File Systems + service including its dependencies and configure them to start when the + system boots: + + .. code-block:: console + + # systemctl enable openstack-manila-share.service target.service + # systemctl start openstack-manila-share.service target.service diff --git a/install-guide/source/install-share-ubuntu.rst b/install-guide/source/install-share-ubuntu.rst new file mode 100644 index 0000000000..3c8d1b42be --- /dev/null +++ b/install-guide/source/install-share-ubuntu.rst @@ -0,0 +1,99 @@ +.. _share-node-install-ubuntu: + +Install and configure a share node running Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure a share node for the +Shared File Systems service. For simplicity, this configuration references one +storage node with the generic driver managing the share servers. The +generic backend manages share servers using compute, networking and block +services for provisioning shares. + +Note that installation and configuration vary by distribution. This section +describes the instructions for a share node running Ubuntu. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install manila-share python-pymysql + +#. Edit the ``/etc/manila/manila.conf`` file and complete the following + actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://manila:MANILA_DBPASS@controller/manila + + Replace ``MANILA_DBPASS`` with the password you chose for + the Shared File Systems database. + +.. include:: common/share-node-common-configuration.rst + +Two driver modes +---------------- + +.. include:: common/share-node-share-server-modes.rst + +Choose one of the following options to configure the share driver: + +.. include:: common/dhss-false-mode-intro.rst + +Prerequisites +------------- + +.. note:: + + Perform these steps on the storage node. + +#. Install the supporting utility packages: + + * Install LVM and NFS server packages: + + .. code-block:: console + + # apt-get install lvm2 nfs-kernel-server + +.. include:: common/dhss-false-mode-configuration.rst + +.. include:: common/dhss-true-mode-intro.rst + +Prerequisites +------------- + +Before you proceed, verify operation of the Compute, Networking, and Block +Storage services. This options requires implementation of Networking option 2 +and requires installation of some Networking service components on the storage +node. + +* Install the Networking service components: + + .. code-block:: console + + # apt-get install neutron-plugin-linuxbridge-agent + +.. include:: common/dhss-true-mode-configuration.rst + +Finalize installation +--------------------- +#. Prepare manila-share as start/stop service. Start the Shared File Systems + service including its dependencies: + + .. code-block:: console + + # service manila-share restart + +#. By default, the Ubuntu packages create an SQLite database. Because this + configuration uses an SQL database server, remove the SQLite database + file: + + .. code-block:: console + + # rm -f /var/lib/manila/manila.sqlite diff --git a/install-guide/source/next-steps.rst b/install-guide/source/next-steps.rst new file mode 100644 index 0000000000..21b282b2b8 --- /dev/null +++ b/install-guide/source/next-steps.rst @@ -0,0 +1,14 @@ +.. _next-steps: + +========== +Next steps +========== + +Your OpenStack environment now includes the Shared File Systems service. + +To add more services, see the `additional documentation on installing +OpenStack services `_ + +Continue to evaluate the Shared File Systems service by creating the service +image and running the service with the correct driver mode that you chose +while configuring the share node. diff --git a/install-guide/source/post-install.rst b/install-guide/source/post-install.rst new file mode 100644 index 0000000000..8a93f12690 --- /dev/null +++ b/install-guide/source/post-install.rst @@ -0,0 +1,196 @@ +.. _post-install: + +Creating shared file systems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before being able to create a share, manila with the generic driver and +the DHSS mode enabled requires the definition of at least an image, +a network and a share-network for being used to create a share server. +For that `back end` configuration, the share server is an instance where +NFS/CIFS shares are served. + +.. note:: + + This configuration automatically creates a cinder volume for every share. + The cinder volumes are attached to share servers according to the + definition of a share network. + +Determine the configuration of the share server +----------------------------------------------- + +#. Source the admin credentials to gain access to admin-only CLI commands: + + .. code-block:: console + + $ . admin-openrc.sh + +#. Create a default share type before running manila-share service: + + .. code-block:: console + + $ manila type-create default_share_type True + +--------------------------------------+--------------------+------------+------------+-------------------------------------+-------------------------+ + | ID | Name | Visibility | is_default | required_extra_specs | optional_extra_specs | + +--------------------------------------+--------------------+------------+------------+-------------------------------------+-------------------------+ + | 8a35da28-0f74-490d-afff-23664ecd4f01 | default_share_type | public | - | driver_handles_share_servers : True | snapshot_support : True | + +--------------------------------------+--------------------+------------+------------+-------------------------------------+-------------------------+ + +#. Create a manila share server image to the Image service: + + .. code-block:: console + + $ glance image-create \ + --copy-from http://tarballs.openstack.org/manila-image-elements/images/manila-service-image-master.qcow2 \ + --name "manila-service-image" \ + --disk-format qcow2 \ + --container-format bare \ + --visibility public --progress + [=============================>] 100% + +------------------+--------------------------------------+ + | Property | Value | + +------------------+--------------------------------------+ + | checksum | 48a08e746cf0986e2bc32040a9183445 | + | container_format | bare | + | created_at | 2016-01-26T19:52:24Z | + | disk_format | qcow2 | + | id | 1fc7f29e-8fe6-44ef-9c3c-15217e83997c | + | min_disk | 0 | + | min_ram | 0 | + | name | manila-service-image | + | owner | e2c965830ecc4162a002bf16ddc91ab7 | + | protected | False | + | size | 306577408 | + | status | active | + | tags | [] | + | updated_at | 2016-01-26T19:52:28Z | + | virtual_size | None | + | visibility | public | + +------------------+--------------------------------------+ + +#. List available networks in order to get id and subnets of the private + network: + + .. code-block:: console + + $ neutron net-list + +--------------------------------------+---------+----------------------------------------------------+ + | id | name | subnets | + +--------------------------------------+---------+----------------------------------------------------+ + | 0e62efcd-8cee-46c7-b163-d8df05c3c5ad | public | 5cc70da8-4ee7-4565-be53-b9c011fca011 10.3.31.0/24 | + | 7c6f9b37-76b4-463e-98d8-27e5686ed083 | private | 3482f524-8bff-4871-80d4-5774c2730728 172.16.1.0/24 | + +--------------------------------------+---------+----------------------------------------------------+ + +#. Source the ``demo`` credentials to perform + the following steps as a non-administrative project: + + .. code-block:: console + + $ . demo-openrc.sh + + .. code-block:: console + + $ manila share-network-create --name demo-share-network1 \ + --neutron-net-id PRIVATE_NETWORK_ID \ + --neutron-subnet-id PRIVATE_NETWORK_SUBNET_ID + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | name | demo-share-network1 | + | segmentation_id | None | + | created_at | 2016-01-26T20:03:41.877838 | + | neutron_subnet_id | 3482f524-8bff-4871-80d4-5774c2730728 | + | updated_at | None | + | network_type | None | + | neutron_net_id | 7c6f9b37-76b4-463e-98d8-27e5686ed083 | + | ip_version | None | + | nova_net_id | None | + | cidr | None | + | project_id | e2c965830ecc4162a002bf16ddc91ab7 | + | id | 58b2f0e6-5509-4830-af9c-97f525a31b14 | + | description | None | + +-------------------+--------------------------------------+ + +Create a share +-------------- + +#. Create a NFS share using the share network: + + .. code-block:: console + + $ manila create NFS 1 --name demo-share1 --share-network demo-share-network1 + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | None | + | share_type_name | None | + | description | None | + | availability_zone | None | + | share_network_id | None | + | export_locations | [] | + | host | None | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 016ca18f-bdd5-48e1-88c0-782e4c1aa28c | + | size | 1 | + | name | demo-share1 | + | share_type | None | + | created_at | 2016-01-26T20:08:50.502877 | + | export_location | None | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 48e8c35b2ac6495d86d4be61658975e7 | + | metadata | {} | + +-----------------------------+--------------------------------------+ + +#. After some time, the share status should change from ``creating`` + to ``available``: + + .. code-block:: console + + $ manila list + +--------------------------------------+-------------+------+-------------+-----------+-----------+--------------------------------------+---------------------------------------------------------------+-----------------------------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type | Export location | Host | Availability Zone | + +--------------------------------------+-------------+------+-------------+-----------+-----------+--------------------------------------+---------------------------------------------------------------+-----------------------------+-------------------+ + | 5f8a0574-a95e-40ff-b898-09fd8d6a1fac | demo-share1 | 1 | NFS | available | False | 8a35da28-0f74-490d-afff-23664ecd4f01 | 10.254.0.6:/shares/share-0bfd69a1-27f0-4ef5-af17-7cd50bce6550 | storagenode@generic#GENERIC | nova | + +--------------------------------------+-------------+------+-------------+-----------+-----------+--------------------------------------+---------------------------------------------------------------+-----------------------------+-------------------+ + +#. Configure user access to the new share before attempting to mount it via + the network: + + .. important :: + + The image used for launching an instance and mounting a share must have + the NFS packages provided by the distro. Example: The cirros image + created at the image service section is not enough. + + .. important :: + + Use an instance that is connected to the private network used to create + the share-network. + + .. code-block:: console + + $ manila access-allow demo-share1 ip INSTANCE_PRIVATE_NETWORK_IP + +Mount the share from an instance +-------------------------------- + +#. Create a folder where the mount will be placed: + + .. code-block:: console + + $ mkdir ~/test_folder + +#. Mount the NFS share in the instance using the export location of the share: + + .. code-block:: console + + $ mount -v 10.254.0.6:/shares/share-0bfd69a1-27f0-4ef5-af17-7cd50bce6550 ~/test_folder + + +For more information about how to manage shares, see the +`OpenStack User Guide +`__. diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst new file mode 100644 index 0000000000..2312a90395 --- /dev/null +++ b/install-guide/source/verify.rst @@ -0,0 +1,29 @@ +.. _verify: + +Verify operation +~~~~~~~~~~~~~~~~ + +Verify operation of the Shared File Systems service. + +.. note:: + + Perform these commands on the controller node. + +#. Source the ``admin`` credentials to gain access to + admin-only CLI commands: + + .. code-block:: console + + $ . admin-openrc.sh + +#. List service components to verify successful launch of each process: + + .. code-block:: console + + $ manila service-list + +------------------+----------------+------+---------+-------+----------------------------+-----------------+ + | Binary | Host | Zone | Status | State | Updated_at | Disabled Reason | + +------------------+----------------+------+---------+-------+----------------------------+-----------------+ + | manila-scheduler | controller | nova | enabled | up | 2014-10-18T01:30:54.000000 | None | + | manila-share | share1@generic | nova | enabled | up | 2014-10-18T01:30:57.000000 | None | + +------------------+----------------+------+---------+-------+----------------------------+-----------------+ diff --git a/tox.ini b/tox.ini index 6efbf79f0e..19296d1a00 100644 --- a/tox.ini +++ b/tox.ini @@ -18,6 +18,10 @@ commands = commands = sphinx-build -a -E -W -d releasenotes/build/doctrees \ -b html releasenotes/source releasenotes/build/html +[testenv:install-guide] +# builds to install-guide/build/html +commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html + [testenv:debug] commands = oslo_debug_helper {posargs} @@ -94,7 +98,7 @@ commands = alembic -c manila/db/migrations/alembic.ini revision -m ""{posargs} # Following checks are ignored on purpose: ignore = builtins = _ -exclude = .git,.tox,.testrepository,.venv,build,cover,dist,doc,*egg,api-ref/build +exclude = .git,.tox,.testrepository,.venv,build,cover,dist,doc,*egg,api-ref/build,*/source/conf.py [hacking] import_exceptions =