From 90060722a9c33176f705705dd071052cddf4d3dd Mon Sep 17 00:00:00 2001 From: Tom Barron Date: Fri, 4 Aug 2017 14:20:33 -0400 Subject: [PATCH] doc migration: new directory layout This patch introduces a new directory layout in doc/source in conformance with the OpenStack manuals project migration spec [1], moves the existing content in manila/doc/source into the new directories, and adjusts index files accordingly. This is the first step in the migration process as outlined in the spec. [1] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html Partial-Bug: #1706181 Needed-By: I7924d94b82e7c8d9716bad7a219fc38c57970773 Depends-On: Ifc80fc56648cef74c85464321d1850e8c68449a0 Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Change-Id: Ieea33262101a1d2459492c1c8aaac5fe042279f6 --- doc/.gitignore | 2 - doc/source/{adminref => admin}/index.rst | 1 - doc/source/{adminref => admin}/intro.rst | 0 .../{adminref => admin}/multi_backends.rst | 0 .../{adminref => admin}/network_plugins.rst | 0 doc/source/adminref/quick_start.rst | 612 ------------------ doc/source/cli/index.rst | 21 + doc/source/{man => cli}/manila-manage.rst | 0 doc/source/configuration/README.rst | 17 + doc/source/configuration/index.rst | 21 + .../adding_release_notes.rst | 0 .../addmethod.openstackapi.rst | 0 doc/source/{devref => contributor}/api.rst | 0 .../api_microversion_dev.rst | 0 .../api_microversion_history.rst | 0 .../{devref => contributor}/architecture.rst | 0 doc/source/{devref => contributor}/auth.rst | 0 .../capabilities_and_extra_specs.rst | 0 .../{devref => contributor}/cephfs_driver.rst | 0 .../commit_message_tags.rst | 0 .../container_driver.rst | 0 .../{devref => contributor}/database.rst | 0 .../development-environment-devstack.rst | 0 .../development.environment.rst | 0 .../documenting_your_work.rst | 0 .../driver_filter_goodness_weigher.rst | 0 .../driver_requirements.rst | 0 .../emc_isilon_driver.rst | 0 .../emc_unity_driver.rst | 0 .../emc_vnx_driver.rst | 0 .../experimental_apis.rst | 0 .../export_location_metadata.rst | 0 doc/source/{devref => contributor}/fakes.rst | 0 .../{devref => contributor}/ganesha.rst | 0 .../generic_driver.rst | 0 doc/source/{devref => contributor}/gerrit.rst | 0 .../glusterfs_driver.rst | 0 .../glusterfs_native_driver.rst | 0 .../{devref => contributor}/gpfs_driver.rst | 0 .../guru_meditation_report.rst | 0 .../hdfs_native_driver.rst | 0 .../hitachi_hnas_driver.rst | 0 .../hpe_3par_driver.rst | 0 .../huawei_nas_driver.rst | 0 doc/source/{devref => contributor}/i18n.rst | 0 doc/source/{devref => contributor}/index.rst | 6 +- doc/source/{devref => contributor}/intro.rst | 0 .../{devref => contributor}/launchpad.rst | 0 doc/source/{devref => contributor}/manila.rst | 0 .../netapp_cluster_mode_driver.rst | 0 .../pool-aware-manila-scheduler.rst | 0 doc/source/{devref => contributor}/rpc.rst | 0 .../{devref => contributor}/scheduler.rst | 0 .../{devref => contributor}/services.rst | 0 doc/source/{devref => contributor}/share.rst | 0 ...hare_back_ends_feature_support_mapping.rst | 0 .../{devref => contributor}/share_hooks.rst | 0 .../share_migration.rst | 0 .../share_replication.rst | 0 .../{devref => contributor}/tegile_driver.rst | 0 .../{devref => contributor}/tempest_tests.rst | 0 .../{devref => contributor}/threading.rst | 0 .../{devref => contributor}/unit_tests.rst | 0 .../{devref => contributor}/user_messages.rst | 0 .../zfs_on_linux_driver.rst | 0 doc/source/index.rst | 56 +- doc/source/install/README.rst | 5 + doc/source/install/index.rst | 22 + doc/source/man/index.rst | 11 - doc/source/{ => reference}/glossary.rst | 0 doc/source/reference/index.rst | 21 + doc/source/user/API.rst | 8 + doc/source/user/index.rst | 21 + 73 files changed, 180 insertions(+), 644 deletions(-) rename doc/source/{adminref => admin}/index.rst (97%) rename doc/source/{adminref => admin}/intro.rst (100%) rename doc/source/{adminref => admin}/multi_backends.rst (100%) rename doc/source/{adminref => admin}/network_plugins.rst (100%) delete mode 100644 doc/source/adminref/quick_start.rst create mode 100644 doc/source/cli/index.rst rename doc/source/{man => cli}/manila-manage.rst (100%) create mode 100644 doc/source/configuration/README.rst create mode 100644 doc/source/configuration/index.rst rename doc/source/{devref => contributor}/adding_release_notes.rst (100%) rename doc/source/{devref => contributor}/addmethod.openstackapi.rst (100%) rename doc/source/{devref => contributor}/api.rst (100%) rename doc/source/{devref => contributor}/api_microversion_dev.rst (100%) rename doc/source/{devref => contributor}/api_microversion_history.rst (100%) rename doc/source/{devref => contributor}/architecture.rst (100%) rename doc/source/{devref => contributor}/auth.rst (100%) rename doc/source/{devref => contributor}/capabilities_and_extra_specs.rst (100%) rename doc/source/{devref => contributor}/cephfs_driver.rst (100%) rename doc/source/{devref => contributor}/commit_message_tags.rst (100%) rename doc/source/{devref => contributor}/container_driver.rst (100%) rename doc/source/{devref => contributor}/database.rst (100%) rename doc/source/{devref => contributor}/development-environment-devstack.rst (100%) rename doc/source/{devref => contributor}/development.environment.rst (100%) rename doc/source/{devref => contributor}/documenting_your_work.rst (100%) rename doc/source/{devref => contributor}/driver_filter_goodness_weigher.rst (100%) rename doc/source/{devref => contributor}/driver_requirements.rst (100%) rename doc/source/{devref => contributor}/emc_isilon_driver.rst (100%) rename doc/source/{devref => contributor}/emc_unity_driver.rst (100%) rename doc/source/{devref => contributor}/emc_vnx_driver.rst (100%) rename doc/source/{devref => contributor}/experimental_apis.rst (100%) rename doc/source/{devref => contributor}/export_location_metadata.rst (100%) rename doc/source/{devref => contributor}/fakes.rst (100%) rename doc/source/{devref => contributor}/ganesha.rst (100%) rename doc/source/{devref => contributor}/generic_driver.rst (100%) rename doc/source/{devref => contributor}/gerrit.rst (100%) rename doc/source/{devref => contributor}/glusterfs_driver.rst (100%) rename doc/source/{devref => contributor}/glusterfs_native_driver.rst (100%) rename doc/source/{devref => contributor}/gpfs_driver.rst (100%) rename doc/source/{devref => contributor}/guru_meditation_report.rst (100%) rename doc/source/{devref => contributor}/hdfs_native_driver.rst (100%) rename doc/source/{devref => contributor}/hitachi_hnas_driver.rst (100%) rename doc/source/{devref => contributor}/hpe_3par_driver.rst (100%) rename doc/source/{devref => contributor}/huawei_nas_driver.rst (100%) rename doc/source/{devref => contributor}/i18n.rst (100%) rename doc/source/{devref => contributor}/index.rst (94%) rename doc/source/{devref => contributor}/intro.rst (100%) rename doc/source/{devref => contributor}/launchpad.rst (100%) rename doc/source/{devref => contributor}/manila.rst (100%) rename doc/source/{devref => contributor}/netapp_cluster_mode_driver.rst (100%) rename doc/source/{devref => contributor}/pool-aware-manila-scheduler.rst (100%) rename doc/source/{devref => contributor}/rpc.rst (100%) rename doc/source/{devref => contributor}/scheduler.rst (100%) rename doc/source/{devref => contributor}/services.rst (100%) rename doc/source/{devref => contributor}/share.rst (100%) rename doc/source/{devref => contributor}/share_back_ends_feature_support_mapping.rst (100%) rename doc/source/{devref => contributor}/share_hooks.rst (100%) rename doc/source/{devref => contributor}/share_migration.rst (100%) rename doc/source/{devref => contributor}/share_replication.rst (100%) rename doc/source/{devref => contributor}/tegile_driver.rst (100%) rename doc/source/{devref => contributor}/tempest_tests.rst (100%) rename doc/source/{devref => contributor}/threading.rst (100%) rename doc/source/{devref => contributor}/unit_tests.rst (100%) rename doc/source/{devref => contributor}/user_messages.rst (100%) rename doc/source/{devref => contributor}/zfs_on_linux_driver.rst (100%) create mode 100644 doc/source/install/README.rst create mode 100644 doc/source/install/index.rst delete mode 100644 doc/source/man/index.rst rename doc/source/{ => reference}/glossary.rst (100%) create mode 100644 doc/source/reference/index.rst create mode 100644 doc/source/user/API.rst create mode 100644 doc/source/user/index.rst diff --git a/doc/.gitignore b/doc/.gitignore index 291b04e45d..88f9974bd7 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,3 +1 @@ _build/* -source/api/* -.autogenerated diff --git a/doc/source/adminref/index.rst b/doc/source/admin/index.rst similarity index 97% rename from doc/source/adminref/index.rst rename to doc/source/admin/index.rst index aacf6ca517..9a348f3eec 100644 --- a/doc/source/adminref/index.rst +++ b/doc/source/admin/index.rst @@ -18,6 +18,5 @@ Admin Reference :maxdepth: 3 intro - quick_start multi_backends network_plugins diff --git a/doc/source/adminref/intro.rst b/doc/source/admin/intro.rst similarity index 100% rename from doc/source/adminref/intro.rst rename to doc/source/admin/intro.rst diff --git a/doc/source/adminref/multi_backends.rst b/doc/source/admin/multi_backends.rst similarity index 100% rename from doc/source/adminref/multi_backends.rst rename to doc/source/admin/multi_backends.rst diff --git a/doc/source/adminref/network_plugins.rst b/doc/source/admin/network_plugins.rst similarity index 100% rename from doc/source/adminref/network_plugins.rst rename to doc/source/admin/network_plugins.rst diff --git a/doc/source/adminref/quick_start.rst b/doc/source/adminref/quick_start.rst deleted file mode 100644 index 11da16722c..0000000000 --- a/doc/source/adminref/quick_start.rst +++ /dev/null @@ -1,612 +0,0 @@ -.. - 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. - -Quick start -=========== -This document describes how to install manila from the OpenStack `Mitaka` -release. Note that the process differs from previous releases and is likely to -change again in subsequent releases. - -Manila consists of the following main services, which are similar to those of -the OpenStack cinder project: - -- manila-api -- manila-data -- manila-scheduler -- manila-share - -Installations of `manila-api` and `manila-scheduler` are common -for almost all deployments. But configuration of `manila-share` is -backend-specific and can differ from deployment to deployment. This -document will cover only a single use case, configuring the "Generic" driver -that uses the cinder project as its backend. - -Note that the `manila-share` service can run in two modes, with and without -handling of `share servers`. In most cases share servers are virtual machines -that export file shares via various network file systems. The example in this -document describes a backend that manages share servers using network resources -provided by neutron. - -.. note:: - Manila supports any network architecture. When a driver is managing its own - share servers, it can use any of several network plug-ins that provide - network resources. Manila includes plug-ins for neutron and nova-network, - as well as a `StandaloneNetworkPlugin` for simple networks. When a driver - is not managing share servers, it has no need for network plug-ins. - -Prerequisites -------------- -- MySQL database -- RabbitMQ message bus -- OpenStack keystone -- Git - -For Generic driver: - -- OpenStack cinder -- OpenStack glance -- OpenStack neutron -- OpenStack nova - -Steps to perform -================ -- Installation of manila binaries -- Installation of manila client -- Registration in keystone -- Preparation of external files (configs, etc...) -- Basic configuration of manila -- Database setup -- Running manila services -- Creation of pilot share - -Installation of manila binaries -------------------------------- -Manila binaries may be installed using various distribution packages or from -source code. In our case we will use the latter, installation by cloning a git -repository. - -Clone repo:: - - $ git clone -b stable/mitaka https://github.com/openstack/manila - -Then run the installation script:: - - $ sudo python setup.py install - -It will install the manila binaries and their dependencies. -These are the expected binaries: - -- manila-all -- manila-api -- manila-data -- manila-manage -- manila-scheduler -- manila-share - -Installation of manila client ------------------------------ - -To send requests to manila we need to install the manila client. - -Install it using PIP: - -.. code-block:: console - - $ sudo pip install python-manilaclient>=1.8.1 - -.. note:: - The starting version of the manila client for Mitaka release is 1.8.1 - -The above will install the manila binary that will be used for issuing -manila requests. - -Registration in keystone ------------------------- - -Like all other OpenStack projects, manila should be registered with keystone. -Here are the registration steps, similar to those of cinder: - -1) Create manila service user: - -.. code-block:: console - - $ openstack user create --password %PASSWORD% manila - -2) Add the admin role to the manila user: - -.. code-block:: console - - $ openstack role add --user manila --project service admin - -.. note:: - Tenant/project may differ, but it should be the same as for all other - service users such as ‘cinder’, ‘nova’, etc. - -3) Create the manila service entities: - -.. code-block:: console - - $ openstack service create \ - --name manila \ - --description "OpenStack Shared Filesystems"\ - share - - $ openstack service create \ - --name manilav2 \ - --description "OpenStack Shared Filesystems V2"\ - sharev2 - - -Result:: - - +-------------+----------------------------------+ - | Property | Value | - +-------------+----------------------------------+ - | description | OpenStack Shared Filesystems | - | enabled | True | - | id | 4c13e9ff7ec04f4e95a26f72ecdf9919 | - | name | manila | - | type | share | - +-------------+----------------------------------+ - - +-------------+----------------------------------+ - | Property | Value | - +-------------+----------------------------------+ - | description | OpenStack Shared Filesystems V2 | - | enabled | True | - | id | 2840d1e7b033437f8776a7bd5045b28d | - | name | manilav2 | - | type | sharev2 | - +-------------+----------------------------------+ - - -4) Create the Share Filesystems service API endpoints: - -.. code-block:: console - - $ openstack endpoint create \ - --region RegionOne \ - --publicurl http://%controller%:8786/v1/%\(tenant_id\)s \ - --internalurl http://%controller%:8786/v1/%\(tenant_id\)s \ - --adminurl http://%controller%:8786/v1/%\(tenant_id\)s \ - share - - -Result should be similar to:: - - +--------------+--------------------------------------------------------------+ - | Field | Value | - +--------------+--------------------------------------------------------------+ - | adminurl | http://%controller%:8786/v1/%(tenant_id)s | - | id | 118230f5aa514809a9866ae411636b43 | - | internalurl | http://%controller%:8786/v1/%(tenant_id)s | - | publicurl | http://%controller%:8786/v1/%(tenant_id)s | - | region | RegionOne | - | service_id | 4c13e9ff7ec04f4e95a26f72ecdf9919 | - | service_name | manila | - | service_type | share | - +--------------+--------------------------------------------------------------+ - - $ openstack endpoint create \ - --region RegionOne \ - --publicurl http://%controller%:8786/v2/%\(tenant_id\)s \ - --internalurl http://%controller%:8786/v2/%\(tenant_id\)s \ - --adminurl http://%controller%:8786/v2/%\(tenant_id\)s \ - sharev2 - - -Result should be similar to:: - - +--------------+--------------------------------------------------------------+ - | Field | Value | - +--------------+--------------------------------------------------------------+ - | adminurl | http://%controller%:8786/v2/%(tenant_id)s | - | id | 228230f5aa514809a9866ae411636b8d | - | internalurl | http://%controller%:8786/v2/%(tenant_id)s | - | publicurl | http://%controller%:8786/v2/%(tenant_id)s | - | region | RegionOne | - | service_id | 2840d1e7b033437f8776a7bd5045b28d | - | service_name | manilav2 | - | service_type | sharev2 | - +--------------+--------------------------------------------------------------+ - -.. note:: - Port ‘8786’ is the default port for manila. It may be changed to any - other port, but this change should also be made in the manila configuration - file using opt ‘osapi_share_listen_port’ which defaults to ‘8786’. - -Preparation of external files ------------------------------ -Copy files from %git_dir%/etc/manila -to dir ‘/etc/manila’:: - - policy.json - api-paste.ini - rootwrap.conf - rootwrap.d/share.filters - - -Then generate a config sample file using tox: - -.. code-block:: console - - $ tox -e genconfig - -This will create a file with the latest config options and their descriptions:: - - ‘%git_dir%/etc/manila/manila.conf.sample’ - -Copy this file to the same directory as the above files, removing the suffix -‘.sample’ from its name: - -.. code-block:: console - - $ cp %git_dir%/etc/manila/manila.conf.sample /etc/manila/manila.conf - -.. note:: - Manila configuration file may be used from different places. - `/etc/manila/manila.conf` is one of expected paths by default. - -Basic configuration of manila ------------------------------ -In our case we will set up one backend with generic driver (using cinder -as its backend) configured to manage its own share servers. -Below is an example of the configuration file, `/etc/manila/manila.conf`, -outlining some core sections. - -.. code-block:: ini - - [keystone_authtoken] - signing_dir = /var/cache/manila - admin_password = %password_we_used_with_user_creation_operation% - admin_user = manila - admin_tenant_name = %service_project_name_we_used_with_user_creation_operation% - auth_protocol = http - auth_port = 35357 - auth_host = %address_of_machine_with_keystone_endpoint% - - [DATABASE] - # Set up MySQL connection. In following ‘foo’ is username, - # ‘bar’ is password and ‘quuz’ is host name or address: - connection = mysql+pymysql://foo:bar@quuz/manila?charset=utf8 - - [oslo_concurrency] - # Following opt defines directory to be used for lock files creation. - # Should be owned by user that runs manila-share processes. - # Defaults to env var ‘OSLO_LOCK_PATH’. It is used by manila-share services - # and is required to be set up. Make sure this dir is created and owned - # by user that run manila-share services. - lock_path = /etc/manila/custom_manila_lock_path - - [DEFAULT] - # Set pretty logging output. Not required, but may be useful. - logging_exception_prefix = %(color)s%(asctime)s.%(msecs)d TRACE %(name)s ^[[01;35m%(instance)s^[[00m - logging_debug_format_suffix = ^[[00;33mfrom (pid=%(process)d) %(funcName)s %(pathname)s:%(lineno)d^[[00m - logging_default_format_string = %(asctime)s.%(msecs)d %(color)s%(levelname)s %(name)s [^[[00;36m-%(color)s] ^[[01;35m%(instance)s%(color)s%(message)s^[[00m - logging_context_format_string = %(asctime)s.%(msecs)d %(color)s%(levelname)s %(name)s [^[[01;36m%(request_id)s ^[[00;36m%(user_id)s %(project_id)s%(color)s] ^[[01;35m%(instance)s%(color)s%(message)s^[[00m - - # Set auth strategy for usage of keystone - auth_strategy = keystone - - # Set message bus creds - rabbit_userid = %rabbit_username% - rabbit_password = %rabbit_user_password% - rabbit_hosts = %address_of_machine_with_rabbit% - rpc_backend = rabbit - - # Following opt is used for definition of share backends that should be enabled. - # Values are conf groupnames that contain per manila-share service opts. - enabled_share_backends = london - - # Enable protocols ‘NFS’ and ‘CIFS’ as those are the only supported - # by Generic driver that we are configuring in this set up. - # All available values are (‘NFS’, ‘CIFS’, ‘GlusterFS’, ‘HDFS’, 'CEPHFS', ‘MapRFS’) - enabled_share_protocols = NFS,CIFS - - # Manila requires ‘share-type’ for share creation. - # So, set here name of some share-type that will be used by default. - default_share_type = default_share_type - - state_path = /opt/stack/data/manila - osapi_share_extension = manila.api.contrib.standard_extensions - rootwrap_config = /etc/manila/rootwrap.conf - api_paste_config = /etc/manila/api-paste.ini - share_name_template = share-%s - - # Set scheduler driver with usage of filters. Recommended. - scheduler_driver = manila.scheduler.drivers.filter.FilterScheduler - - # Set following opt to ‘True’ to get more info in logging. - debug = True - - [nova] - # Only needed by generic or windows drivers, the only drivers - # as of Mitaka that require it. - username = nova - password = %password% - project_domain_id = default - project_name = service - user_domain_id = default - auth_url = http://127.0.0.1:5000 - auth_type = password - - [neutron] - # Only needed when the networking drivers use nova and "generic" driver, - # as used in this example. - username = neutron - password = %password% - project_domain_id = default - project_name = service - user_domain_id = default - auth_url = http://127.0.0.1:5000 - auth_type = password - - [cinder] - # Only needed by generic or windows drivers, the only drivers - # as of Mitaka that require it. - username = cinder - password = %password% - project_domain_id = default - project_name = service - user_domain_id = default - auth_url = http://127.0.0.1:5000 - auth_type = password - - [london] - # This is custom opt group that is used for storing opts of share-service. - # This one is used only when enabled using opt `enabled_share_backends` - # from DEFAULT group. - - # Set usage of Generic driver which uses cinder as backend. - share_driver = manila.share.drivers.generic.GenericShareDriver - - # Generic driver supports both driver modes - with and without handling - # of share servers. So, we need to define explicitly which one we are - # enabling using this driver. - driver_handles_share_servers = True - - # Generic driver uses a glance image for building service VMs in nova. - # The following options specify the image to use. - # We use the latest build of [1]. - # [1] https://github.com/openstack/manila-image-elements - service_instance_password = manila - service_instance_user = manila - service_image_name = manila-service-image - - # These will be used for keypair creation and inserted into service VMs. - path_to_private_key = /home/stack/.ssh/id_rsa - path_to_public_key = /home/stack/.ssh/id_rsa.pub - - # Custom name for share backend. - share_backend_name = LONDON - -.. note:: - The Generic driver does not use network plugins, so none is part of the - above configuration. Other drivers that manage their own share servers may - require one of manila's network plug-ins. - -Database setup --------------- -Manila supports different SQL dialects in theory, but it is only tested with -MySQL, so this step assumes that MySQL has been installed. - -Create the database for manila: - -.. code-block:: console - - $ mysql -u%DATABASE_USER% -p%DATABASE_PASSWORD% -h%MYSQL_HOST% -e "DROP DATABASE IF EXISTS manila;" - $ mysql -u%DATABASE_USER% -p%DATABASE_PASSWORD% -h%MYSQL_HOST% -e "CREATE DATABASE manila CHARACTER SET utf8;" - -Then create manila's tables and apply all migrations: - -.. code-block:: console - - $ manila-manage db sync - -Here is the list of tables for the Mitaka release of manila:: - - +--------------------------------------------+ - | Tables_in_manila | - +--------------------------------------------+ - | alembic_version | - | availability_zones | - | cgsnapshot_members | - | cgsnapshots | - | consistency_group_share_type_mappings | - | consistency_groups | - | drivers_private_data | - | network_allocations | - | project_user_quotas | - | quota_classes | - | quota_usages | - | quotas | - | reservations | - | security_services | - | services | - | share_access_map | - | share_instance_access_map | - | share_instance_export_locations | - | share_instance_export_locations_metadata | - | share_instances | - | share_metadata | - | share_network_security_service_association | - | share_networks | - | share_server_backend_details | - | share_servers | - | share_snapshot_instances | - | share_snapshots | - | share_type_extra_specs | - | share_type_projects | - | share_types | - | shares | - +--------------------------------------------+ - -Running manila services ------------------------ - -Run manila-api first: - -.. code-block:: console - - $ manila-api \ - --config-file /etc/manila/manila.conf & \ - echo $! >/opt/stack/status/stack/m-api.pid; \ - fg || echo "m-api failed to start" | \ - tee "/opt/stack/status/stack/m-api.failure" - -Create a default share type before running `manila-share` service: - -.. code-block:: console - - $ manila type-create default_share_type True - -Where `default_share_type` is custom name of `share-type` and `True` is value -for required extra-spec `driver_handles_share_servers`. These are required -params for creation of `share-type`. - -Result:: - - +----------------------+-------------------------------------+ - | Property | Value | - +----------------------+-------------------------------------+ - | required_extra_specs | driver_handles_share_servers : True | - | Name | default_share_type | - | Visibility | public | - | is_default | - | - | ID | %some_id% | - | optional_extra_specs | snapshot_support : True | - +----------------------+-------------------------------------+ - -Service `manila-api` may be restarted to get updated information about -`default share type`. So, get list of share types after restart of -service `manila-api`: - -.. code-block:: console - - $ manila type-list - -Result:: - - +-----------+--------------------+------------+------------+-------------------------------------+-------------------------+ - | ID | Name | visibility | is_default | required_extra_specs | optional_extra_specs | - +-----------+--------------------+------------+------------+-------------------------------------+-------------------------+ - | %some_id% | default_share_type | public | YES | driver_handles_share_servers : True | snapshot_support : True | - +-----------+--------------------+------------+------------+-------------------------------------+-------------------------+ - - -Add any additional extra specs to `share-type` if needed using following command: - -.. code-block:: console - - $ manila type-key default_share_type set key=value - -This may be viewed as follows: - -.. code-block:: console - - $ manila extra-specs-list - -Run manila-scheduler: - -.. code-block:: console - - $ manila-scheduler \ - --config-file /etc/manila/manila.conf & \ - echo $! >/opt/stack/status/stack/m-sch.pid; \ - fg || echo "m-sch failed to start" | \ - tee "/opt/stack/status/stack/m-sch.failure" - -Run manila-share: - -.. code-block:: console - - $ manila-share \ - --config-file /etc/manila/manila.conf & \ - echo $! >/opt/stack/status/stack/m-shr.pid; \ - fg || echo "m-shr failed to start" | \ - tee "/opt/stack/status/stack/m-shr.failure" - -Run manila-data: - -.. code-block:: console - - $ manila-data \ - --config-file /etc/manila/manila.conf & \ - echo $! >opt/stack/status/stack/m-dat.pid; \ - fg || echo "m-dat failed to start" | \ - tee "/opt/stack/status/stack/m-dat.failure" - - -Creation of pilot share ------------------------ - -In this step we assume that the following services are running: - -- keystone -- nova (used by Generic driver, not strict dependency of manila) -- neutron (default network backend for Generic driver, used when driver handles share servers) -- cinder (used by Generic driver) - -To operate a driver that handles share servers, we must create -a `share network`, which is a set of network information that will be used -during share server creation. -In our example, to use neutron, we will do the following: - -.. code-block:: console - - $ neutron net-list - -Here we note the ID of a neutron network and one of its subnets. - -.. note:: - Some configurations of the Generic driver may require this network be - attached to a public router. It is so by default. So, if you use the - default configuration of Generic driver, make sure the network is attached - to a public router. - -Then define a share network using the neutron network and subnet IDs: - -.. code-block:: console - - $ manila share-network-create \ - --name test_share_network \ - --neutron-net-id %id_of_neutron_network% \ - --neutron-subnet-id %id_of_network_subnet% - -Now we can create a share using the following command: - -.. code-block:: console - - $ manila create NFS 1 --name testshare --share-network test_share_network - -The above command will instruct manila to schedule a share for creation. Once -created, configure user access to the new share before attempting to mount it -via the network: - -.. code-block:: console - - $ manila access-allow testshare ip 0.0.0.0/0 --access-level rw - -We added read-write access to all IP addresses. Now, you can try mounting this -NFS share onto any host. To determine the path required to mount the share onto -a host, run: - -.. code-block:: console - - # manila share-export-location-list testshare - +--------------------------------------+--------------------------------------------------------+-----------+ - | ID | Path | Preferred | - +--------------------------------------+--------------------------------------------------------+-----------+ - | 6921e862-88bc-49a5-a2df-efeed9acd583 | 10.0.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d | False | - | b6bd76ce-12a2-42a9-a30a-8a43b503867d | 10.254.0.3:/share-e1c2d35e-fe67-4028-ad7a-45f668732b1d | False | - +--------------------------------------+--------------------------------------------------------+-----------+ diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 0000000000..970fe6f44a --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,21 @@ +.. + 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. + + +Command Line Interface +---------------------- + +.. toctree:: + :maxdepth: 1 + + manila-manage diff --git a/doc/source/man/manila-manage.rst b/doc/source/cli/manila-manage.rst similarity index 100% rename from doc/source/man/manila-manage.rst rename to doc/source/cli/manila-manage.rst diff --git a/doc/source/configuration/README.rst b/doc/source/configuration/README.rst new file mode 100644 index 0000000000..ebb11a1707 --- /dev/null +++ b/doc/source/configuration/README.rst @@ -0,0 +1,17 @@ +================================== +Manila Configuration Documentation +================================== + +Introduction: +------------- + +This directory is intended to hold any documentation that relates to +how to configure Manila. Some of this content will be automatically +generated in upcoming documentation work. At the moment, however, it +is not. Changes to configuration options for Manila or its drivers +need to be put under this directory. + +The full spec for organization of documentation may be seen in the +`OS Manuals Migration Spec +`_. + diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 0000000000..42c7d84c5a --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,21 @@ +.. + 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. + + +Configuration +------------- + +.. toctree:: + :maxdepth: 1 + + README diff --git a/doc/source/devref/adding_release_notes.rst b/doc/source/contributor/adding_release_notes.rst similarity index 100% rename from doc/source/devref/adding_release_notes.rst rename to doc/source/contributor/adding_release_notes.rst diff --git a/doc/source/devref/addmethod.openstackapi.rst b/doc/source/contributor/addmethod.openstackapi.rst similarity index 100% rename from doc/source/devref/addmethod.openstackapi.rst rename to doc/source/contributor/addmethod.openstackapi.rst diff --git a/doc/source/devref/api.rst b/doc/source/contributor/api.rst similarity index 100% rename from doc/source/devref/api.rst rename to doc/source/contributor/api.rst diff --git a/doc/source/devref/api_microversion_dev.rst b/doc/source/contributor/api_microversion_dev.rst similarity index 100% rename from doc/source/devref/api_microversion_dev.rst rename to doc/source/contributor/api_microversion_dev.rst diff --git a/doc/source/devref/api_microversion_history.rst b/doc/source/contributor/api_microversion_history.rst similarity index 100% rename from doc/source/devref/api_microversion_history.rst rename to doc/source/contributor/api_microversion_history.rst diff --git a/doc/source/devref/architecture.rst b/doc/source/contributor/architecture.rst similarity index 100% rename from doc/source/devref/architecture.rst rename to doc/source/contributor/architecture.rst diff --git a/doc/source/devref/auth.rst b/doc/source/contributor/auth.rst similarity index 100% rename from doc/source/devref/auth.rst rename to doc/source/contributor/auth.rst diff --git a/doc/source/devref/capabilities_and_extra_specs.rst b/doc/source/contributor/capabilities_and_extra_specs.rst similarity index 100% rename from doc/source/devref/capabilities_and_extra_specs.rst rename to doc/source/contributor/capabilities_and_extra_specs.rst diff --git a/doc/source/devref/cephfs_driver.rst b/doc/source/contributor/cephfs_driver.rst similarity index 100% rename from doc/source/devref/cephfs_driver.rst rename to doc/source/contributor/cephfs_driver.rst diff --git a/doc/source/devref/commit_message_tags.rst b/doc/source/contributor/commit_message_tags.rst similarity index 100% rename from doc/source/devref/commit_message_tags.rst rename to doc/source/contributor/commit_message_tags.rst diff --git a/doc/source/devref/container_driver.rst b/doc/source/contributor/container_driver.rst similarity index 100% rename from doc/source/devref/container_driver.rst rename to doc/source/contributor/container_driver.rst diff --git a/doc/source/devref/database.rst b/doc/source/contributor/database.rst similarity index 100% rename from doc/source/devref/database.rst rename to doc/source/contributor/database.rst diff --git a/doc/source/devref/development-environment-devstack.rst b/doc/source/contributor/development-environment-devstack.rst similarity index 100% rename from doc/source/devref/development-environment-devstack.rst rename to doc/source/contributor/development-environment-devstack.rst diff --git a/doc/source/devref/development.environment.rst b/doc/source/contributor/development.environment.rst similarity index 100% rename from doc/source/devref/development.environment.rst rename to doc/source/contributor/development.environment.rst diff --git a/doc/source/devref/documenting_your_work.rst b/doc/source/contributor/documenting_your_work.rst similarity index 100% rename from doc/source/devref/documenting_your_work.rst rename to doc/source/contributor/documenting_your_work.rst diff --git a/doc/source/devref/driver_filter_goodness_weigher.rst b/doc/source/contributor/driver_filter_goodness_weigher.rst similarity index 100% rename from doc/source/devref/driver_filter_goodness_weigher.rst rename to doc/source/contributor/driver_filter_goodness_weigher.rst diff --git a/doc/source/devref/driver_requirements.rst b/doc/source/contributor/driver_requirements.rst similarity index 100% rename from doc/source/devref/driver_requirements.rst rename to doc/source/contributor/driver_requirements.rst diff --git a/doc/source/devref/emc_isilon_driver.rst b/doc/source/contributor/emc_isilon_driver.rst similarity index 100% rename from doc/source/devref/emc_isilon_driver.rst rename to doc/source/contributor/emc_isilon_driver.rst diff --git a/doc/source/devref/emc_unity_driver.rst b/doc/source/contributor/emc_unity_driver.rst similarity index 100% rename from doc/source/devref/emc_unity_driver.rst rename to doc/source/contributor/emc_unity_driver.rst diff --git a/doc/source/devref/emc_vnx_driver.rst b/doc/source/contributor/emc_vnx_driver.rst similarity index 100% rename from doc/source/devref/emc_vnx_driver.rst rename to doc/source/contributor/emc_vnx_driver.rst diff --git a/doc/source/devref/experimental_apis.rst b/doc/source/contributor/experimental_apis.rst similarity index 100% rename from doc/source/devref/experimental_apis.rst rename to doc/source/contributor/experimental_apis.rst diff --git a/doc/source/devref/export_location_metadata.rst b/doc/source/contributor/export_location_metadata.rst similarity index 100% rename from doc/source/devref/export_location_metadata.rst rename to doc/source/contributor/export_location_metadata.rst diff --git a/doc/source/devref/fakes.rst b/doc/source/contributor/fakes.rst similarity index 100% rename from doc/source/devref/fakes.rst rename to doc/source/contributor/fakes.rst diff --git a/doc/source/devref/ganesha.rst b/doc/source/contributor/ganesha.rst similarity index 100% rename from doc/source/devref/ganesha.rst rename to doc/source/contributor/ganesha.rst diff --git a/doc/source/devref/generic_driver.rst b/doc/source/contributor/generic_driver.rst similarity index 100% rename from doc/source/devref/generic_driver.rst rename to doc/source/contributor/generic_driver.rst diff --git a/doc/source/devref/gerrit.rst b/doc/source/contributor/gerrit.rst similarity index 100% rename from doc/source/devref/gerrit.rst rename to doc/source/contributor/gerrit.rst diff --git a/doc/source/devref/glusterfs_driver.rst b/doc/source/contributor/glusterfs_driver.rst similarity index 100% rename from doc/source/devref/glusterfs_driver.rst rename to doc/source/contributor/glusterfs_driver.rst diff --git a/doc/source/devref/glusterfs_native_driver.rst b/doc/source/contributor/glusterfs_native_driver.rst similarity index 100% rename from doc/source/devref/glusterfs_native_driver.rst rename to doc/source/contributor/glusterfs_native_driver.rst diff --git a/doc/source/devref/gpfs_driver.rst b/doc/source/contributor/gpfs_driver.rst similarity index 100% rename from doc/source/devref/gpfs_driver.rst rename to doc/source/contributor/gpfs_driver.rst diff --git a/doc/source/devref/guru_meditation_report.rst b/doc/source/contributor/guru_meditation_report.rst similarity index 100% rename from doc/source/devref/guru_meditation_report.rst rename to doc/source/contributor/guru_meditation_report.rst diff --git a/doc/source/devref/hdfs_native_driver.rst b/doc/source/contributor/hdfs_native_driver.rst similarity index 100% rename from doc/source/devref/hdfs_native_driver.rst rename to doc/source/contributor/hdfs_native_driver.rst diff --git a/doc/source/devref/hitachi_hnas_driver.rst b/doc/source/contributor/hitachi_hnas_driver.rst similarity index 100% rename from doc/source/devref/hitachi_hnas_driver.rst rename to doc/source/contributor/hitachi_hnas_driver.rst diff --git a/doc/source/devref/hpe_3par_driver.rst b/doc/source/contributor/hpe_3par_driver.rst similarity index 100% rename from doc/source/devref/hpe_3par_driver.rst rename to doc/source/contributor/hpe_3par_driver.rst diff --git a/doc/source/devref/huawei_nas_driver.rst b/doc/source/contributor/huawei_nas_driver.rst similarity index 100% rename from doc/source/devref/huawei_nas_driver.rst rename to doc/source/contributor/huawei_nas_driver.rst diff --git a/doc/source/devref/i18n.rst b/doc/source/contributor/i18n.rst similarity index 100% rename from doc/source/devref/i18n.rst rename to doc/source/contributor/i18n.rst diff --git a/doc/source/devref/index.rst b/doc/source/contributor/index.rst similarity index 94% rename from doc/source/devref/index.rst rename to doc/source/contributor/index.rst index d146469e48..90b3c26178 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/contributor/index.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations under the License. -Developer Guide -=============== +Contributor/Developer Guide +=========================== -In this section you will find information on manila's lower level programming APIs. +In this section you will find information helpful for contributing to manila. Programming HowTos and Tutorials diff --git a/doc/source/devref/intro.rst b/doc/source/contributor/intro.rst similarity index 100% rename from doc/source/devref/intro.rst rename to doc/source/contributor/intro.rst diff --git a/doc/source/devref/launchpad.rst b/doc/source/contributor/launchpad.rst similarity index 100% rename from doc/source/devref/launchpad.rst rename to doc/source/contributor/launchpad.rst diff --git a/doc/source/devref/manila.rst b/doc/source/contributor/manila.rst similarity index 100% rename from doc/source/devref/manila.rst rename to doc/source/contributor/manila.rst diff --git a/doc/source/devref/netapp_cluster_mode_driver.rst b/doc/source/contributor/netapp_cluster_mode_driver.rst similarity index 100% rename from doc/source/devref/netapp_cluster_mode_driver.rst rename to doc/source/contributor/netapp_cluster_mode_driver.rst diff --git a/doc/source/devref/pool-aware-manila-scheduler.rst b/doc/source/contributor/pool-aware-manila-scheduler.rst similarity index 100% rename from doc/source/devref/pool-aware-manila-scheduler.rst rename to doc/source/contributor/pool-aware-manila-scheduler.rst diff --git a/doc/source/devref/rpc.rst b/doc/source/contributor/rpc.rst similarity index 100% rename from doc/source/devref/rpc.rst rename to doc/source/contributor/rpc.rst diff --git a/doc/source/devref/scheduler.rst b/doc/source/contributor/scheduler.rst similarity index 100% rename from doc/source/devref/scheduler.rst rename to doc/source/contributor/scheduler.rst diff --git a/doc/source/devref/services.rst b/doc/source/contributor/services.rst similarity index 100% rename from doc/source/devref/services.rst rename to doc/source/contributor/services.rst diff --git a/doc/source/devref/share.rst b/doc/source/contributor/share.rst similarity index 100% rename from doc/source/devref/share.rst rename to doc/source/contributor/share.rst diff --git a/doc/source/devref/share_back_ends_feature_support_mapping.rst b/doc/source/contributor/share_back_ends_feature_support_mapping.rst similarity index 100% rename from doc/source/devref/share_back_ends_feature_support_mapping.rst rename to doc/source/contributor/share_back_ends_feature_support_mapping.rst diff --git a/doc/source/devref/share_hooks.rst b/doc/source/contributor/share_hooks.rst similarity index 100% rename from doc/source/devref/share_hooks.rst rename to doc/source/contributor/share_hooks.rst diff --git a/doc/source/devref/share_migration.rst b/doc/source/contributor/share_migration.rst similarity index 100% rename from doc/source/devref/share_migration.rst rename to doc/source/contributor/share_migration.rst diff --git a/doc/source/devref/share_replication.rst b/doc/source/contributor/share_replication.rst similarity index 100% rename from doc/source/devref/share_replication.rst rename to doc/source/contributor/share_replication.rst diff --git a/doc/source/devref/tegile_driver.rst b/doc/source/contributor/tegile_driver.rst similarity index 100% rename from doc/source/devref/tegile_driver.rst rename to doc/source/contributor/tegile_driver.rst diff --git a/doc/source/devref/tempest_tests.rst b/doc/source/contributor/tempest_tests.rst similarity index 100% rename from doc/source/devref/tempest_tests.rst rename to doc/source/contributor/tempest_tests.rst diff --git a/doc/source/devref/threading.rst b/doc/source/contributor/threading.rst similarity index 100% rename from doc/source/devref/threading.rst rename to doc/source/contributor/threading.rst diff --git a/doc/source/devref/unit_tests.rst b/doc/source/contributor/unit_tests.rst similarity index 100% rename from doc/source/devref/unit_tests.rst rename to doc/source/contributor/unit_tests.rst diff --git a/doc/source/devref/user_messages.rst b/doc/source/contributor/user_messages.rst similarity index 100% rename from doc/source/devref/user_messages.rst rename to doc/source/contributor/user_messages.rst diff --git a/doc/source/devref/zfs_on_linux_driver.rst b/doc/source/contributor/zfs_on_linux_driver.rst similarity index 100% rename from doc/source/devref/zfs_on_linux_driver.rst rename to doc/source/contributor/zfs_on_linux_driver.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 3895b1e053..b4627e5926 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -25,7 +25,6 @@ Manila is an OpenStack project to provide "Shared Filesystems as a service". * **Fault-Tolerant**: Isolated processes avoid cascading failures * **Recoverable**: Failures should be easy to diagnose, debug, and rectify * **Open Standards**: Be a reference implementation for a community-driven api -* **API Compatibility**: Manila strives to provide API-compatible with popular systems like Amazon EC2 This documentation is generated by the Sphinx toolkit and lives in the source tree. Additional draft and project documentation on Manila and other components of OpenStack can @@ -35,14 +34,14 @@ be found on the `OpenStack wiki`_. Cloud administrators, refer to `docs.openstac .. _`docs.openstack.org`: http://docs.openstack.org -Developer Docs -============== + +Installing Manila +================= .. toctree:: :maxdepth: 1 - devref/index - man/index + install/index Admin Docs ========== @@ -50,23 +49,50 @@ Admin Docs .. toctree:: :maxdepth: 1 - adminref/index + admin/index -API Extensions -============== - -Go to http://api.openstack.org for information about Manila API extensions. - -Information -=========== +Contributor/Developer Docs +========================== .. toctree:: :maxdepth: 1 - glossary + contributor/index + +Command Line Interface Documentation +==================================== + +.. toctree:: + :maxdepth: 1 + + cli/index + + +Configuration Reference +======================= + +.. toctree:: + :maxdepth: 1 + + configuration/index + +Other Reference +=============== + +.. toctree:: + :maxdepth: 1 + + reference/index + +User Documentaton +================= + +.. toctree:: + :maxdepth: 1 + + user/index Indices and tables ================== * :ref:`genindex` -* :ref:`search` diff --git a/doc/source/install/README.rst b/doc/source/install/README.rst new file mode 100644 index 0000000000..1bee180923 --- /dev/null +++ b/doc/source/install/README.rst @@ -0,0 +1,5 @@ +Install +------- + +This is a placeholder file that will be removed when the install guide is +imported in a subsequent patch. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 0000000000..46532bda0c --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,22 @@ +.. + 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. + +Install Guide +=============== + +In this section you will find information on how to install Manila. + +.. toctree:: + :maxdepth: 1 + + README diff --git a/doc/source/man/index.rst b/doc/source/man/index.rst deleted file mode 100644 index aeb946c2aa..0000000000 --- a/doc/source/man/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Command-Line Utilities -====================== - -In this section you will find information on Manila's command-line utilities. - -Reference ---------- -.. toctree:: - :maxdepth: 3 - - manila-manage diff --git a/doc/source/glossary.rst b/doc/source/reference/glossary.rst similarity index 100% rename from doc/source/glossary.rst rename to doc/source/reference/glossary.rst diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000000..1d8fc43158 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,21 @@ +.. + 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. + + +Reference +--------- + +.. toctree:: + :maxdepth: 1 + + glossary diff --git a/doc/source/user/API.rst b/doc/source/user/API.rst new file mode 100644 index 0000000000..c961bd067f --- /dev/null +++ b/doc/source/user/API.rst @@ -0,0 +1,8 @@ +========================== +Manila API Documentation +========================== + +A full specification of the API for interacting with the shared file +systems service may be found in the `API reference +`_. + diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000000..163bfbb7eb --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,21 @@ +.. + 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. + + +User +---- + +.. toctree:: + :maxdepth: 1 + + API