diff --git a/doc/source/admin/blockstorage-api-throughput.rst b/doc/source/admin/blockstorage-api-throughput.rst new file mode 100644 index 00000000000..06c7ca996ac --- /dev/null +++ b/doc/source/admin/blockstorage-api-throughput.rst @@ -0,0 +1,34 @@ +============================================= +Increase Block Storage API service throughput +============================================= + +By default, the Block Storage API service runs in one process. This +limits the number of API requests that the Block Storage service can +process at any given time. In a production environment, you should +increase the Block Storage API throughput by allowing the Block Storage +API service to run in as many processes as the machine capacity allows. + +.. note:: + + The Block Storage API service is named ``openstack-cinder-api`` on + the following distributions: CentOS, Fedora, openSUSE, Red Hat + Enterprise Linux, and SUSE Linux Enterprise. In Ubuntu and Debian + distributions, the Block Storage API service is named ``cinder-api``. + +To do so, use the Block Storage API service option ``osapi_volume_workers``. +This option allows you to specify the number of API service workers +(or OS processes) to launch for the Block Storage API service. + +To configure this option, open the ``/etc/cinder/cinder.conf`` +configuration file and set the ``osapi_volume_workers`` configuration +key to the number of CPU cores/threads on a machine. + +On distributions that include ``openstack-config``, you can configure +this by running the following command instead: + +.. code-block:: console + + # openstack-config --set /etc/cinder/cinder.conf \ + DEFAULT osapi_volume_workers CORES + +Replace ``CORES`` with the number of CPU cores/threads on a machine. diff --git a/doc/source/admin/blockstorage-backup-disks.rst b/doc/source/admin/blockstorage-backup-disks.rst new file mode 100644 index 00000000000..a4169550162 --- /dev/null +++ b/doc/source/admin/blockstorage-backup-disks.rst @@ -0,0 +1,266 @@ +=================================== +Back up Block Storage service disks +=================================== + +While you can use the LVM snapshot to create snapshots, you can also use +it to back up your volumes. By using LVM snapshot, you reduce the size +of the backup; only existing data is backed up instead of the entire +volume. + +To back up a volume, you must create a snapshot of it. An LVM snapshot +is the exact copy of a logical volume, which contains data in a frozen +state. This prevents data corruption because data cannot be manipulated +during the volume creation process. Remember that the volumes created +through an :command:`openstack volume create` command exist in an LVM +logical volume. + +You must also make sure that the operating system is not using the +volume and that all data has been flushed on the guest file systems. +This usually means that those file systems have to be unmounted during +the snapshot creation. They can be mounted again as soon as the logical +volume snapshot has been created. + +Before you create the snapshot you must have enough space to save it. +As a precaution, you should have at least twice as much space as the +potential snapshot size. If insufficient space is available, the snapshot +might become corrupted. + +For this example assume that a 100 GB volume named ``volume-00000001`` +was created for an instance while only 4 GB are used. This example uses +these commands to back up only those 4 GB: + +* :command:`lvm2` command. Directly manipulates the volumes. + +* :command:`kpartx` command. Discovers the partition table created inside the + instance. + +* :command:`tar` command. Creates a minimum-sized backup. + +* :command:`sha1sum` command. Calculates the backup checksum to check its + consistency. + +You can apply this process to volumes of any size. + +**To back up Block Storage service disks** + +#. Create a snapshot of a used volume + + * Use this command to list all volumes + + .. code-block:: console + + # lvdisplay + + * Create the snapshot; you can do this while the volume is attached + to an instance: + + .. code-block:: console + + # lvcreate --size 10G --snapshot --name volume-00000001-snapshot \ + /dev/cinder-volumes/volume-00000001 + + Use the ``--snapshot`` configuration option to tell LVM that you want a + snapshot of an already existing volume. The command includes the size + of the space reserved for the snapshot volume, the name of the snapshot, + and the path of an already existing volume. Generally, this path + is ``/dev/cinder-volumes/VOLUME_NAME``. + + The size does not have to be the same as the volume of the snapshot. + The ``--size`` parameter defines the space that LVM reserves + for the snapshot volume. As a precaution, the size should be the same + as that of the original volume, even if the whole space is not + currently used by the snapshot. + + * Run the :command:`lvdisplay` command again to verify the snapshot: + + .. code-block:: console + + --- Logical volume --- + LV Name /dev/cinder-volumes/volume-00000001 + VG Name cinder-volumes + LV UUID gI8hta-p21U-IW2q-hRN1-nTzN-UC2G-dKbdKr + LV Write Access read/write + LV snapshot status source of + /dev/cinder-volumes/volume-00000026-snap [active] + LV Status available + # open 1 + LV Size 15,00 GiB + Current LE 3840 + Segments 1 + Allocation inherit + Read ahead sectors auto + - currently set to 256 + Block device 251:13 + + --- Logical volume --- + LV Name /dev/cinder-volumes/volume-00000001-snap + VG Name cinder-volumes + LV UUID HlW3Ep-g5I8-KGQb-IRvi-IRYU-lIKe-wE9zYr + LV Write Access read/write + LV snapshot status active destination for /dev/cinder-volumes/volume-00000026 + LV Status available + # open 0 + LV Size 15,00 GiB + Current LE 3840 + COW-table size 10,00 GiB + COW-table LE 2560 + Allocated to snapshot 0,00% + Snapshot chunk size 4,00 KiB + Segments 1 + Allocation inherit + Read ahead sectors auto + - currently set to 256 + Block device 251:14 + +#. Partition table discovery + + * To exploit the snapshot with the :command:`tar` command, mount + your partition on the Block Storage service server. + + The :command:`kpartx` utility discovers and maps table partitions. + You can use it to view partitions that are created inside the + instance. Without using the partitions created inside instances, + you cannot see its content and create efficient backups. + + .. code-block:: console + + # kpartx -av /dev/cinder-volumes/volume-00000001-snapshot + + .. note:: + + On a Debian-based distribution, you can use the + :command:`apt-get install kpartx` command to install + :command:`kpartx`. + + If the tools successfully find and map the partition table, + no errors are returned. + + * To check the partition table map, run this command: + + .. code-block:: console + + $ ls /dev/mapper/nova* + + You can see the ``cinder--volumes-volume--00000001--snapshot1`` + partition. + + If you created more than one partition on that volume, you see + several partitions; for example: + ``cinder--volumes-volume--00000001--snapshot2``, + ``cinder--volumes-volume--00000001--snapshot3``, and so on. + + * Mount your partition + + .. code-block:: console + + # mount /dev/mapper/cinder--volumes-volume--volume--00000001--snapshot1 /mnt + + If the partition mounts successfully, no errors are returned. + + You can directly access the data inside the instance. If a message + prompts you for a partition or you cannot mount it, determine whether + enough space was allocated for the snapshot or the :command:`kpartx` + command failed to discover the partition table. + + Allocate more space to the snapshot and try the process again. + +#. Use the :command:`tar` command to create archives + + Create a backup of the volume: + + .. code-block:: console + + $ tar --exclude="lost+found" --exclude="some/data/to/exclude" -czf \ + volume-00000001.tar.gz -C /mnt/ /backup/destination + + This command creates a ``tar.gz`` file that contains the data, + *and data only*. This ensures that you do not waste space by backing + up empty sectors. + +#. Checksum calculation I + + You should always have the checksum for your backup files. When you + transfer the same file over the network, you can run a checksum + calculation to ensure that your file was not corrupted during its + transfer. The checksum is a unique ID for a file. If the checksums are + different, the file is corrupted. + + Run this command to run a checksum for your file and save the result + to a file: + + .. code-block:: console + + $ sha1sum volume-00000001.tar.gz > volume-00000001.checksum + + .. note:: + + Use the :command:`sha1sum` command carefully because the time it + takes to complete the calculation is directly proportional to the + size of the file. + + Depending on your CPU, the process might take a long time for + files larger than around 4 to 6 GB. + +#. After work cleaning + + Now that you have an efficient and consistent backup, use this command + to clean up the file system: + + * Unmount the volume. + + .. code-block:: console + + $ umount /mnt + + * Delete the partition table. + + .. code-block:: console + + $ kpartx -dv /dev/cinder-volumes/volume-00000001-snapshot + + * Remove the snapshot. + + .. code-block:: console + + $ lvremove -f /dev/cinder-volumes/volume-00000001-snapshot + + Repeat these steps for all your volumes. + +#. Automate your backups + + Because more and more volumes might be allocated to your Block Storage + service, you might want to automate your backups. + The `SCR_5005_V01_NUAC-OPENSTACK-EBS-volumes-backup.sh`_ script assists + you with this task. The script performs the operations from the previous + example, but also provides a mail report and runs the backup based on + the ``backups_retention_days`` setting. + + Launch this script from the server that runs the Block Storage service. + + This example shows a mail report: + + .. code-block:: console + + Backup Start Time - 07/10 at 01:00:01 + Current retention - 7 days + + The backup volume is mounted. Proceed... + Removing old backups... : /BACKUPS/EBS-VOL/volume-00000019/volume-00000019_28_09_2011.tar.gz + /BACKUPS/EBS-VOL/volume-00000019 - 0 h 1 m and 21 seconds. Size - 3,5G + + The backup volume is mounted. Proceed... + Removing old backups... : /BACKUPS/EBS-VOL/volume-0000001a/volume-0000001a_28_09_2011.tar.gz + /BACKUPS/EBS-VOL/volume-0000001a - 0 h 4 m and 15 seconds. Size - 6,9G + --------------------------------------- + Total backups size - 267G - Used space : 35% + Total execution time - 1 h 75 m and 35 seconds + + The script also enables you to SSH to your instances and run a + :command:`mysqldump` command into them. To make this work, enable + the connection to the Compute project keys. If you do not want to + run the :command:`mysqldump` command, you can add + ``enable_mysql_dump=0`` to the script to turn off this functionality. + + +.. Links +.. _`SCR_5005_V01_NUAC-OPENSTACK-EBS-volumes-backup.sh`: https://github.com/Razique/BashStuff/blob/master/SYSTEMS/OpenStack/SCR_5005_V01_NUAC-OPENSTACK-EBS-volumes-backup.sh diff --git a/doc/source/admin/blockstorage-boot-from-volume.rst b/doc/source/admin/blockstorage-boot-from-volume.rst new file mode 100644 index 00000000000..ca58dfe9545 --- /dev/null +++ b/doc/source/admin/blockstorage-boot-from-volume.rst @@ -0,0 +1,10 @@ +================ +Boot from volume +================ + +In some cases, you can store and run instances from inside volumes. +For information, see the `Launch an instance from a volume`_ section +in the `OpenStack End User Guide`_. + +.. _`Launch an instance from a volume`: https://docs.openstack.org/user-guide/cli-nova-launch-instance-from-volume.html +.. _`OpenStack End User Guide`: https://docs.openstack.org/user-guide/ diff --git a/doc/source/admin/blockstorage-consistency-groups.rst b/doc/source/admin/blockstorage-consistency-groups.rst new file mode 100644 index 00000000000..00f19f89838 --- /dev/null +++ b/doc/source/admin/blockstorage-consistency-groups.rst @@ -0,0 +1,355 @@ +================== +Consistency groups +================== + +Consistency group support is available in OpenStack Block Storage. The +support is added for creating snapshots of consistency groups. This +feature leverages the storage level consistency technology. It allows +snapshots of multiple volumes in the same consistency group to be taken +at the same point-in-time to ensure data consistency. The consistency +group operations can be performed using the Block Storage command line. + +.. note:: + + Only Block Storage V2 API supports consistency groups. You can + specify ``--os-volume-api-version 2`` when using Block Storage + command line for consistency group operations. + +Before using consistency groups, make sure the Block Storage driver that +you are running has consistency group support by reading the Block +Storage manual or consulting the driver maintainer. There are a small +number of drivers that have implemented this feature. The default LVM +driver does not support consistency groups yet because the consistency +technology is not available at the storage level. + +Before using consistency groups, you must change policies for the +consistency group APIs in the ``/etc/cinder/policy.json`` file. +By default, the consistency group APIs are disabled. +Enable them before running consistency group operations. + +Here are existing policy entries for consistency groups: + +.. code-block:: json + + { + "consistencygroup:create": "group:nobody" + "consistencygroup:delete": "group:nobody", + "consistencygroup:update": "group:nobody", + "consistencygroup:get": "group:nobody", + "consistencygroup:get_all": "group:nobody", + "consistencygroup:create_cgsnapshot" : "group:nobody", + "consistencygroup:delete_cgsnapshot": "group:nobody", + "consistencygroup:get_cgsnapshot": "group:nobody", + "consistencygroup:get_all_cgsnapshots": "group:nobody", + } + +Remove ``group:nobody`` to enable these APIs: + +.. code-block:: json + + { + "consistencygroup:create": "", + "consistencygroup:delete": "", + "consistencygroup:update": "", + "consistencygroup:get": "", + "consistencygroup:get_all": "", + "consistencygroup:create_cgsnapshot" : "", + "consistencygroup:delete_cgsnapshot": "", + "consistencygroup:get_cgsnapshot": "", + "consistencygroup:get_all_cgsnapshots": "", + } + + +Restart Block Storage API service after changing policies. + +The following consistency group operations are supported: + +- Create a consistency group, given volume types. + + .. note:: + + A consistency group can support more than one volume type. The + scheduler is responsible for finding a back end that can support + all given volume types. + + A consistency group can only contain volumes hosted by the same + back end. + + A consistency group is empty upon its creation. Volumes need to + be created and added to it later. + +- Show a consistency group. + +- List consistency groups. + +- Create a volume and add it to a consistency group, given volume type + and consistency group id. + +- Create a snapshot for a consistency group. + +- Show a snapshot of a consistency group. + +- List consistency group snapshots. + +- Delete a snapshot of a consistency group. + +- Delete a consistency group. + +- Modify a consistency group. + +- Create a consistency group from the snapshot of another consistency + group. + +- Create a consistency group from a source consistency group. + +The following operations are not allowed if a volume is in a consistency +group: + +- Volume migration. + +- Volume retype. + +- Volume deletion. + + .. note:: + + A consistency group has to be deleted as a whole with all the + volumes. + +The following operations are not allowed if a volume snapshot is in a +consistency group snapshot: + +- Volume snapshot deletion. + + .. note:: + + A consistency group snapshot has to be deleted as a whole with + all the volume snapshots. + +The details of consistency group operations are shown in the following. + +.. note:: + + Currently, no OpenStack client command is available to run in + place of the cinder consistency group creation commands. Use the + cinder commands detailed in the following examples. + +**Create a consistency group**: + +.. code-block:: console + + cinder consisgroup-create + [--name name] + [--description description] + [--availability-zone availability-zone] + volume-types + +.. note:: + + The parameter ``volume-types`` is required. It can be a list of + names or UUIDs of volume types separated by commas without spaces in + between. For example, ``volumetype1,volumetype2,volumetype3.``. + +.. code-block:: console + + $ cinder consisgroup-create --name bronzeCG2 volume_type_1 + + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | availability_zone | nova | + | created_at | 2014-12-29T12:59:08.000000 | + | description | None | + | id | 1de80c27-3b2f-47a6-91a7-e867cbe36462 | + | name | bronzeCG2 | + | status | creating | + +-------------------+--------------------------------------+ + +**Show a consistency group**: + +.. code-block:: console + + $ cinder consisgroup-show 1de80c27-3b2f-47a6-91a7-e867cbe36462 + + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | availability_zone | nova | + | created_at | 2014-12-29T12:59:08.000000 | + | description | None | + | id | 2a6b2bda-1f43-42ce-9de8-249fa5cbae9a | + | name | bronzeCG2 | + | status | available | + | volume_types | volume_type_1 | + +-------------------+--------------------------------------+ + +**List consistency groups**: + +.. code-block:: console + + $ cinder consisgroup-list + + +--------------------------------------+-----------+-----------+ + | ID | Status | Name | + +--------------------------------------+-----------+-----------+ + | 1de80c27-3b2f-47a6-91a7-e867cbe36462 | available | bronzeCG2 | + | 3a2b3c42-b612-479a-91eb-1ed45b7f2ad5 | error | bronzeCG | + +--------------------------------------+-----------+-----------+ + +**Create a volume and add it to a consistency group**: + +.. note:: + + When creating a volume and adding it to a consistency group, a + volume type and a consistency group id must be provided. This is + because a consistency group can support more than one volume type. + +.. code-block:: console + + $ openstack volume create --type volume_type_1 --consistency-group \ + 1de80c27-3b2f-47a6-91a7-e867cbe36462 --size 1 cgBronzeVol + + +---------------------------------------+--------------------------------------+ + | Field | Value | + +---------------------------------------+--------------------------------------+ + | attachments | [] | + | availability_zone | nova | + | bootable | false | + | consistencygroup_id | 1de80c27-3b2f-47a6-91a7-e867cbe36462 | + | created_at | 2014-12-29T13:16:47.000000 | + | description | None | + | encrypted | False | + | id | 5e6d1386-4592-489f-a56b-9394a81145fe | + | metadata | {} | + | name | cgBronzeVol | + | os-vol-host-attr:host | server-1@backend-1#pool-1 | + | os-vol-mig-status-attr:migstat | None | + | os-vol-mig-status-attr:name_id | None | + | os-vol-tenant-attr:tenant_id | 1349b21da2a046d8aa5379f0ed447bed | + | os-volume-replication:driver_data | None | + | os-volume-replication:extended_status | None | + | replication_status | disabled | + | size | 1 | + | snapshot_id | None | + | source_volid | None | + | status | creating | + | user_id | 93bdea12d3e04c4b86f9a9f172359859 | + | volume_type | volume_type_1 | + +---------------------------------------+--------------------------------------+ + +**Create a snapshot for a consistency group**: + +.. code-block:: console + + $ cinder cgsnapshot-create 1de80c27-3b2f-47a6-91a7-e867cbe36462 + + +---------------------+--------------------------------------+ + | Property | Value | + +---------------------+--------------------------------------+ + | consistencygroup_id | 1de80c27-3b2f-47a6-91a7-e867cbe36462 | + | created_at | 2014-12-29T13:19:44.000000 | + | description | None | + | id | d4aff465-f50c-40b3-b088-83feb9b349e9 | + | name | None | + | status | creating | + +---------------------+-------------------------------------+ + +**Show a snapshot of a consistency group**: + +.. code-block:: console + + $ cinder cgsnapshot-show d4aff465-f50c-40b3-b088-83feb9b349e9 + +**List consistency group snapshots**: + +.. code-block:: console + + $ cinder cgsnapshot-list + + +--------------------------------------+--------+----------+ + | ID | Status | Name | + +--------------------------------------+--------+----------+ + | 6d9dfb7d-079a-471e-b75a-6e9185ba0c38 | available | None | + | aa129f4d-d37c-4b97-9e2d-7efffda29de0 | available | None | + | bb5b5d82-f380-4a32-b469-3ba2e299712c | available | None | + | d4aff465-f50c-40b3-b088-83feb9b349e9 | available | None | + +--------------------------------------+--------+----------+ + +**Delete a snapshot of a consistency group**: + +.. code-block:: console + + $ cinder cgsnapshot-delete d4aff465-f50c-40b3-b088-83feb9b349e9 + +**Delete a consistency group**: + +.. note:: + + The force flag is needed when there are volumes in the consistency + group: + + .. code-block:: console + + $ cinder consisgroup-delete --force 1de80c27-3b2f-47a6-91a7-e867cbe36462 + +**Modify a consistency group**: + +.. code-block:: console + + cinder consisgroup-update + [--name NAME] + [--description DESCRIPTION] + [--add-volumes UUID1,UUID2,......] + [--remove-volumes UUID3,UUID4,......] + CG + +The parameter ``CG`` is required. It can be a name or UUID of a consistency +group. UUID1,UUID2,...... are UUIDs of one or more volumes to be added +to the consistency group, separated by commas. Default is None. +UUID3,UUID4,...... are UUIDs of one or more volumes to be removed from +the consistency group, separated by commas. Default is None. + +.. code-block:: console + + $ cinder consisgroup-update --name 'new name' \ + --description 'new description' \ + --add-volumes 0b3923f5-95a4-4596-a536-914c2c84e2db,1c02528b-3781-4e32-929c-618d81f52cf3 \ + --remove-volumes 8c0f6ae4-efb1-458f-a8fc-9da2afcc5fb1,a245423f-bb99-4f94-8c8c-02806f9246d8 \ + 1de80c27-3b2f-47a6-91a7-e867cbe36462 + +**Create a consistency group from the snapshot of another consistency +group**: + +.. code-block:: console + + $ cinder consisgroup-create-from-src + [--cgsnapshot CGSNAPSHOT] + [--name NAME] + [--description DESCRIPTION] + +The parameter ``CGSNAPSHOT`` is a name or UUID of a snapshot of a +consistency group: + +.. code-block:: console + + $ cinder consisgroup-create-from-src \ + --cgsnapshot 6d9dfb7d-079a-471e-b75a-6e9185ba0c38 \ + --name 'new cg' --description 'new cg from cgsnapshot' + +**Create a consistency group from a source consistency group**: + +.. code-block:: console + + $ cinder consisgroup-create-from-src + [--source-cg SOURCECG] + [--name NAME] + [--description DESCRIPTION] + +The parameter ``SOURCECG`` is a name or UUID of a source +consistency group: + +.. code-block:: console + + $ cinder consisgroup-create-from-src \ + --source-cg 6d9dfb7d-079a-471e-b75a-6e9185ba0c38 \ + --name 'new cg' --description 'new cloned cg' diff --git a/doc/source/admin/blockstorage-driver-filter-weighing.rst b/doc/source/admin/blockstorage-driver-filter-weighing.rst new file mode 100644 index 00000000000..f045b5576dd --- /dev/null +++ b/doc/source/admin/blockstorage-driver-filter-weighing.rst @@ -0,0 +1,373 @@ +.. _filter_weigh_scheduler: + +========================================================== +Configure and use driver filter and weighing for scheduler +========================================================== + +OpenStack Block Storage enables you to choose a volume back end based on +back-end specific properties by using the DriverFilter and +GoodnessWeigher for the scheduler. The driver filter and weigher +scheduling can help ensure that the scheduler chooses the best back end +based on requested volume properties as well as various back-end +specific properties. + +What is driver filter and weigher and when to use it +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The driver filter and weigher gives you the ability to more finely +control how the OpenStack Block Storage scheduler chooses the best back +end to use when handling a volume request. One example scenario where +using the driver filter and weigher can be if a back end that utilizes +thin-provisioning is used. The default filters use the ``free capacity`` +property to determine the best back end, but that is not always perfect. +If a back end has the ability to provide a more accurate back-end +specific value you can use that as part of the weighing. Another example +of when the driver filter and weigher can prove useful is if a back end +exists where there is a hard limit of 1000 volumes. The maximum volume +size is 500 GB. Once 75% of the total space is occupied the performance +of the back end degrades. The driver filter and weigher can provide a +way for these limits to be checked for. + +Enable driver filter and weighing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable the driver filter, set the ``scheduler_default_filters`` option in +the ``cinder.conf`` file to ``DriverFilter`` or add it to the list if +other filters are already present. + +To enable the goodness filter as a weigher, set the +``scheduler_default_weighers`` option in the ``cinder.conf`` file to +``GoodnessWeigher`` or add it to the list if other weighers are already +present. + +You can choose to use the ``DriverFilter`` without the +``GoodnessWeigher`` or vice-versa. The filter and weigher working +together, however, create the most benefits when helping the scheduler +choose an ideal back end. + +.. important:: + + The support for the ``DriverFilter`` and ``GoodnessWeigher`` is + optional for back ends. If you are using a back end that does not + support the filter and weigher functionality you may not get the + full benefit. + +Example ``cinder.conf`` configuration file: + +.. code-block:: ini + + scheduler_default_filters = DriverFilter + scheduler_default_weighers = GoodnessWeigher + +.. note:: + + It is useful to use the other filters and weighers available in + OpenStack in combination with these custom ones. For example, the + ``CapacityFilter`` and ``CapacityWeigher`` can be combined with + these. + +Defining your own filter and goodness functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can define your own filter and goodness functions through the use of +various properties that OpenStack Block Storage has exposed. Properties +exposed include information about the volume request being made, +``volume_type`` settings, and back-end specific information about drivers. +All of these allow for a lot of control over how the ideal back end for +a volume request will be decided. + +The ``filter_function`` option is a string defining an equation that +will determine whether a back end should be considered as a potential +candidate in the scheduler. + +The ``goodness_function`` option is a string defining an equation that +will rate the quality of the potential host (0 to 100, 0 lowest, 100 +highest). + +.. important:: + + The drive filter and weigher will use default values for filter and + goodness functions for each back end if you do not define them + yourself. If complete control is desired then a filter and goodness + function should be defined for each of the back ends in + the ``cinder.conf`` file. + + +Supported operations in filter and goodness functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Below is a table of all the operations currently usable in custom filter +and goodness functions created by you: + ++--------------------------------+-------------------------+ +| Operations | Type | ++================================+=========================+ +| +, -, \*, /, ^ | standard math | ++--------------------------------+-------------------------+ +| not, and, or, &, \|, ! | logic | ++--------------------------------+-------------------------+ +| >, >=, <, <=, ==, <>, != | equality | ++--------------------------------+-------------------------+ +| +, - | sign | ++--------------------------------+-------------------------+ +| x ? a : b | ternary | ++--------------------------------+-------------------------+ +| abs(x), max(x, y), min(x, y) | math helper functions | ++--------------------------------+-------------------------+ + +.. caution:: + + Syntax errors you define in filter or goodness strings + are thrown at a volume request time. + +Available properties when creating custom functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are various properties that can be used in either the +``filter_function`` or the ``goodness_function`` strings. The properties allow +access to volume info, qos settings, extra specs, and so on. + +The following properties and their sub-properties are currently +available for use: + +Host stats for a back end +------------------------- +host + The host's name + +volume\_backend\_name + The volume back end name + +vendor\_name + The vendor name + +driver\_version + The driver version + +storage\_protocol + The storage protocol + +QoS\_support + Boolean signifying whether QoS is supported + +total\_capacity\_gb + The total capacity in GB + +allocated\_capacity\_gb + The allocated capacity in GB + +reserved\_percentage + The reserved storage percentage + +Capabilities specific to a back end +----------------------------------- + +These properties are determined by the specific back end +you are creating filter and goodness functions for. Some back ends +may not have any properties available here. + +Requested volume properties +--------------------------- + +status + Status for the requested volume + +volume\_type\_id + The volume type ID + +display\_name + The display name of the volume + +volume\_metadata + Any metadata the volume has + +reservations + Any reservations the volume has + +user\_id + The volume's user ID + +attach\_status + The attach status for the volume + +display\_description + The volume's display description + +id + The volume's ID + +replication\_status + The volume's replication status + +snapshot\_id + The volume's snapshot ID + +encryption\_key\_id + The volume's encryption key ID + +source\_volid + The source volume ID + +volume\_admin\_metadata + Any admin metadata for this volume + +source\_replicaid + The source replication ID + +consistencygroup\_id + The consistency group ID + +size + The size of the volume in GB + +metadata + General metadata + +The property most used from here will most likely be the ``size`` sub-property. + +Extra specs for the requested volume type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +View the available properties for volume types by running: + +.. code-block:: console + + $ cinder extra-specs-list + +Current QoS specs for the requested volume type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +View the available properties for volume types by running: + +.. code-block:: console + + $ openstack volume qos list + +In order to access these properties in a custom string use the following +format: + +``.`` + +Driver filter and weigher usage examples +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Below are examples for using the filter and weigher separately, +together, and using driver-specific properties. + +Example ``cinder.conf`` file configuration for customizing the filter +function: + +.. code-block:: ini + + [default] + scheduler_default_filters = DriverFilter + enabled_backends = lvm-1, lvm-2 + + [lvm-1] + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = sample_LVM01 + filter_function = "volume.size < 10" + + [lvm-2] + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = sample_LVM02 + filter_function = "volume.size >= 10" + +The above example will filter volumes to different back ends depending +on the size of the requested volume. Default OpenStack Block Storage +scheduler weighing is done. Volumes with a size less than 10 GB are sent +to lvm-1 and volumes with a size greater than or equal to 10 GB are sent +to lvm-2. + +Example ``cinder.conf`` file configuration for customizing the goodness +function: + +.. code-block:: ini + + [default] + scheduler_default_weighers = GoodnessWeigher + enabled_backends = lvm-1, lvm-2 + + [lvm-1] + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = sample_LVM01 + goodness_function = "(volume.size < 5) ? 100 : 50" + + [lvm-2] + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = sample_LVM02 + goodness_function = "(volume.size >= 5) ? 100 : 25" + +The above example will determine the goodness rating of a back end based +off of the requested volume's size. Default OpenStack Block Storage +scheduler filtering is done. The example shows how the ternary if +statement can be used in a filter or goodness function. If a requested +volume is of size 10 GB then lvm-1 is rated as 50 and lvm-2 is rated as +100. In this case lvm-2 wins. If a requested volume is of size 3 GB then +lvm-1 is rated 100 and lvm-2 is rated 25. In this case lvm-1 would win. + +Example ``cinder.conf`` file configuration for customizing both the +filter and goodness functions: + +.. code-block:: ini + + [default] + scheduler_default_filters = DriverFilter + scheduler_default_weighers = GoodnessWeigher + enabled_backends = lvm-1, lvm-2 + + [lvm-1] + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = sample_LVM01 + filter_function = "stats.total_capacity_gb < 500" + goodness_function = "(volume.size < 25) ? 100 : 50" + + [lvm-2] + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = sample_LVM02 + filter_function = "stats.total_capacity_gb >= 500" + goodness_function = "(volume.size >= 25) ? 100 : 75" + +The above example combines the techniques from the first two examples. +The best back end is now decided based off of the total capacity of the +back end and the requested volume's size. + +Example ``cinder.conf`` file configuration for accessing driver specific +properties: + +.. code-block:: ini + + [default] + scheduler_default_filters = DriverFilter + scheduler_default_weighers = GoodnessWeigher + enabled_backends = lvm-1,lvm-2,lvm-3 + + [lvm-1] + volume_group = stack-volumes-lvmdriver-1 + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = lvmdriver-1 + filter_function = "volume.size < 5" + goodness_function = "(capabilities.total_volumes < 3) ? 100 : 50" + + [lvm-2] + volume_group = stack-volumes-lvmdriver-2 + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = lvmdriver-2 + filter_function = "volumes.size < 5" + goodness_function = "(capabilities.total_volumes < 8) ? 100 : 50" + + [lvm-3] + volume_group = stack-volumes-lvmdriver-3 + volume_driver = cinder.volume.drivers.LVMVolumeDriver + volume_backend_name = lvmdriver-3 + goodness_function = "55" + +The above is an example of how back-end specific properties can be used +in the filter and goodness functions. In this example the LVM driver's +``total_volumes`` capability is being used to determine which host gets +used during a volume request. In the above example, lvm-1 and lvm-2 will +handle volume requests for all volumes with a size less than 5 GB. The +lvm-1 host will have priority until it contains three or more volumes. +After than lvm-2 will have priority until it contains eight or more +volumes. The lvm-3 will collect all volumes greater or equal to 5 GB as +well as all volumes once lvm-1 and lvm-2 lose priority. diff --git a/doc/source/admin/blockstorage-get-capabilities.rst b/doc/source/admin/blockstorage-get-capabilities.rst new file mode 100644 index 00000000000..805ffafbe3e --- /dev/null +++ b/doc/source/admin/blockstorage-get-capabilities.rst @@ -0,0 +1,294 @@ +.. _get_capabilities: + + +================ +Get capabilities +================ + +When an administrator configures ``volume type`` and ``extra specs`` of storage +on the back end, the administrator has to read the right documentation that +corresponds to the version of the storage back end. Deep knowledge of +storage is also required. + +OpenStack Block Storage enables administrators to configure ``volume type`` +and ``extra specs`` without specific knowledge of the storage back end. + +.. note:: + + * ``Volume Type``: A group of volume policies. + * ``Extra Specs``: The definition of a volume type. This is a group of + policies. For example, provision type, QOS that will be used to + define a volume at creation time. + * ``Capabilities``: What the current deployed back end in Cinder is able + to do. These correspond to extra specs. + +Usage of cinder client +~~~~~~~~~~~~~~~~~~~~~~ + +When an administrator wants to define new volume types for their +OpenStack cloud, the administrator would fetch a list of ``capabilities`` +for a particular back end using the cinder client. + +First, get a list of the services: + +.. code-block:: console + + $ openstack volume service list + +------------------+-------------------+------+---------+-------+----------------------------+ + | Binary | Host | Zone | Status | State | Updated At | + +------------------+-------------------+------+---------+-------+----------------------------+ + | cinder-scheduler | controller | nova | enabled | up | 2016-10-24T13:53:35.000000 | + | cinder-volume | block1@ABC-driver | nova | enabled | up | 2016-10-24T13:53:35.000000 | + +------------------+-------------------+------+---------+-------+----------------------------+ + +With one of the listed hosts, pass that to ``get-capabilities``, then +the administrator can obtain volume stats and also back end ``capabilities`` +as listed below. + +.. code-block:: console + + $ cinder get-capabilities block1@ABC-driver + +---------------------+----------------------------------------------+ + | Volume stats | Value | + +---------------------+----------------------------------------------+ + | description | None | + | display_name | Capabilities of Cinder Vendor ABC driver | + | driver_version | 2.0.0 | + | namespace | OS::Storage::Capabilities::block1@ABC-driver | + | pool_name | None | + | replication_targets | [] | + | storage_protocol | iSCSI | + | vendor_name | Vendor ABC | + | visibility | pool | + | volume_backend_name | ABC-driver | + +---------------------+----------------------------------------------+ + +----------------------+-----------------------------------------------------+ + | Backend properties | Value | + +----------------------+-----------------------------------------------------+ + | compression | {u'type':u'boolean', u'title':u'Compression', ...} | + | ABC:compression_type | {u'enum':u'['lossy', 'lossless', 'special']', ...} | + | qos | {u'type':u'boolean', u'title':u'QoS', ...} | + | replication | {u'type':u'boolean', u'title':u'Replication', ...} | + | thin_provisioning | {u'type':u'boolean', u'title':u'Thin Provisioning'} | + | ABC:minIOPS | {u'type':u'integer', u'title':u'Minimum IOPS QoS',} | + | ABC:maxIOPS | {u'type':u'integer', u'title':u'Maximum IOPS QoS',} | + | ABC:burstIOPS | {u'type':u'integer', u'title':u'Burst IOPS QoS',..} | + +----------------------+-----------------------------------------------------+ + +Disable a service +~~~~~~~~~~~~~~~~~ + +When an administrator wants to disable a service, identify the Binary +and the Host of the service. Use the :command:` openstack volume service set` +command combined with the Binary and Host to disable the service: + +#. Determine the binary and host of the service you want to remove + initially. + + .. code-block:: console + + $ openstack volume service list + +------------------+----------------------+------+---------+-------+----------------------------+ + | Binary | Host | Zone | Status | State | Updated At | + +------------------+----------------------+------+---------+-------+----------------------------+ + | cinder-scheduler | devstack | nova | enabled | up | 2016-10-24T13:53:35.000000 | + | cinder-volume | devstack@lvmdriver-1 | nova | enabled | up | 2016-10-24T13:53:35.000000 | + +------------------+----------------------+------+---------+-------+----------------------------+ + +#. Disable the service using the Binary and Host name, placing the Host + before the Binary name. + + .. code-block:: console + + $ openstack volume service set --disable HOST_NAME BINARY_NAME + +#. Remove the service from the database. + + .. code-block:: console + + $ cinder-manage service remove BINARY_NAME HOST_NAME + +Usage of REST API +~~~~~~~~~~~~~~~~~ + +New endpoint to ``get capabilities`` list for specific storage back end +is also available. For more details, refer to the Block Storage API reference. + +API request: + +.. code-block:: console + + GET /v2/{tenant_id}/capabilities/{hostname} + +Example of return value: + +.. code-block:: json + + { + "namespace": "OS::Storage::Capabilities::block1@ABC-driver", + "volume_backend_name": "ABC-driver", + "pool_name": "pool", + "driver_version": "2.0.0", + "storage_protocol": "iSCSI", + "display_name": "Capabilities of Cinder Vendor ABC driver", + "description": "None", + "visibility": "public", + "properties": { + "thin_provisioning": { + "title": "Thin Provisioning", + "description": "Sets thin provisioning.", + "type": "boolean" + }, + "compression": { + "title": "Compression", + "description": "Enables compression.", + "type": "boolean" + }, + "ABC:compression_type": { + "title": "Compression type", + "description": "Specifies compression type.", + "type": "string", + "enum": [ + "lossy", "lossless", "special" + ] + }, + "replication": { + "title": "Replication", + "description": "Enables replication.", + "type": "boolean" + }, + "qos": { + "title": "QoS", + "description": "Enables QoS.", + "type": "boolean" + }, + "ABC:minIOPS": { + "title": "Minimum IOPS QoS", + "description": "Sets minimum IOPS if QoS is enabled.", + "type": "integer" + }, + "ABC:maxIOPS": { + "title": "Maximum IOPS QoS", + "description": "Sets maximum IOPS if QoS is enabled.", + "type": "integer" + }, + "ABC:burstIOPS": { + "title": "Burst IOPS QoS", + "description": "Sets burst IOPS if QoS is enabled.", + "type": "integer" + }, + } + } + +Usage of volume type access extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some volume types should be restricted only. For example, test volume types +where you are testing a new technology or ultra high performance volumes +(for special cases) where you do not want most users to be able to select +these volumes. An administrator/operator can then define private volume types +using cinder client. +Volume type access extension adds the ability to manage volume type access. +Volume types are public by default. Private volume types can be created by +setting the ``--private`` parameter at creation time. Access to a +private volume type can be controlled by adding or removing a project from it. +Private volume types without projects are only visible by users with the +admin role/context. + +Create a public volume type by setting ``--public`` parameter: + +.. code-block:: console + + $ openstack volume type create vol_Type1 --description test1 --public + +-------------+--------------------------------------+ + | Field | Value | + +-------------+--------------------------------------+ + | description | test1 | + | id | b7dbed9e-de78-49f8-a840-651ae7308592 | + | is_public | True | + | name | vol_Type1 | + +-------------+--------------------------------------+ + +Create a private volume type by setting ``--private`` parameter: + +.. code-block:: console + + $ openstack volume type create vol_Type2 --description test2 --private + +-------------+--------------------------------------+ + | Field | Value | + +-------------+--------------------------------------+ + | description | test2 | + | id | 154baa73-d2c4-462f-8258-a2df251b0d39 | + | is_public | False | + | name | vol_Type2 | + +-------------+--------------------------------------+ + +Get a list of the volume types: + +.. code-block:: console + + $ openstack volume type list + +--------------------------------------+-------------+ + | ID | Name | + +--------------------------------------+-------------+ + | 0a948c84-bad5-4fba-88a2-c062006e4f6b | vol_Type1 | + | 87e5be6f-9491-4ea5-9906-9ac56494bb91 | lvmdriver-1 | + | fd508846-213f-4a07-aaf2-40518fb9a23f | vol_Type2 | + +--------------------------------------+-------------+ + +Get a list of the projects: + +.. code-block:: console + + $ openstack project list + +----------------------------------+--------------------+ + | ID | Name | + +----------------------------------+--------------------+ + | 4105ead90a854100ab6b121266707f2b | alt_demo | + | 4a22a545cedd4fcfa9836eb75e558277 | admin | + | 71f9cdb1a3ab4b8e8d07d347a2e146bb | service | + | c4860af62ffe465e99ed1bc08ef6082e | demo | + | e4b648ba5108415cb9e75bff65fa8068 | invisible_to_admin | + +----------------------------------+--------------------+ + +Add volume type access for the given demo project, using its project-id: + +.. code-block:: console + + $ openstack volume type set --project c4860af62ffe465e99ed1bc08ef6082e \ + vol_Type2 + +List the access information about the given volume type: + +.. code-block:: console + + $ openstack volume type show vol_Type2 + +--------------------+--------------------------------------+ + | Field | Value | + +--------------------+--------------------------------------+ + | access_project_ids | c4860af62ffe465e99ed1bc08ef6082e | + | description | | + | id | fd508846-213f-4a07-aaf2-40518fb9a23f | + | is_public | False | + | name | vol_Type2 | + | properties | | + | qos_specs_id | None | + +--------------------+--------------------------------------+ + +Remove volume type access for the given project: + +.. code-block:: console + + $ openstack volume type unset --project c4860af62ffe465e99ed1bc08ef6082e \ + vol_Type2 + $ openstack volume type show vol_Type2 + +--------------------+--------------------------------------+ + | Field | Value | + +--------------------+--------------------------------------+ + | access_project_ids | | + | description | | + | id | fd508846-213f-4a07-aaf2-40518fb9a23f | + | is_public | False | + | name | vol_Type2 | + | properties | | + | qos_specs_id | None | + +--------------------+--------------------------------------+ diff --git a/doc/source/admin/blockstorage-glusterfs-backend.rst b/doc/source/admin/blockstorage-glusterfs-backend.rst new file mode 100644 index 00000000000..0b37f0c8293 --- /dev/null +++ b/doc/source/admin/blockstorage-glusterfs-backend.rst @@ -0,0 +1,206 @@ +============================== +Configure a GlusterFS back end +============================== + +This section explains how to configure OpenStack Block Storage to use +GlusterFS as a back end. You must be able to access the GlusterFS shares +from the server that hosts the ``cinder`` volume service. + +.. note:: + + The GlusterFS volume driver, which was deprecated in the Newton release, + has been removed in the Ocata release. + +.. note:: + + The cinder volume service is named ``openstack-cinder-volume`` on the + following distributions: + + * CentOS + + * Fedora + + * openSUSE + + * Red Hat Enterprise Linux + + * SUSE Linux Enterprise + + In Ubuntu and Debian distributions, the ``cinder`` volume service is + named ``cinder-volume``. + +Mounting GlusterFS volumes requires utilities and libraries from the +``glusterfs-fuse`` package. This package must be installed on all systems +that will access volumes backed by GlusterFS. + +.. note:: + + The utilities and libraries required for mounting GlusterFS volumes on + Ubuntu and Debian distributions are available from the ``glusterfs-client`` + package instead. + +For information on how to install and configure GlusterFS, refer to the +`GlusterFS Documentation`_ page. + +**Configure GlusterFS for OpenStack Block Storage** + +The GlusterFS server must also be configured accordingly in order to allow +OpenStack Block Storage to use GlusterFS shares: + +#. Log in as ``root`` to the GlusterFS server. + +#. Set each Gluster volume to use the same UID and GID as the ``cinder`` user: + + .. code-block:: console + + # gluster volume set VOL_NAME storage.owner-uid CINDER_UID + # gluster volume set VOL_NAME storage.owner-gid CINDER_GID + + + Where: + + * VOL_NAME is the Gluster volume name. + + * CINDER_UID is the UID of the ``cinder`` user. + + * CINDER_GID is the GID of the ``cinder`` user. + + .. note:: + + The default UID and GID of the ``cinder`` user is 165 on + most distributions. + +#. Configure each Gluster volume to accept ``libgfapi`` connections. + To do this, set each Gluster volume to allow insecure ports: + + .. code-block:: console + + # gluster volume set VOL_NAME server.allow-insecure on + +#. Enable client connections from unprivileged ports. To do this, + add the following line to ``/etc/glusterfs/glusterd.vol``: + + .. code-block:: bash + + option rpc-auth-allow-insecure on + +#. Restart the ``glusterd`` service: + + .. code-block:: console + + # service glusterd restart + + +**Configure Block Storage to use a GlusterFS back end** + +After you configure the GlusterFS service, complete these steps: + +#. Log in as ``root`` to the system hosting the Block Storage service. + +#. Create a text file named ``glusterfs`` in ``/etc/cinder/`` directory. + +#. Add an entry to ``/etc/cinder/glusterfs`` for each GlusterFS + share that OpenStack Block Storage should use for back end storage. + Each entry should be a separate line, and should use the following + format: + + .. code-block:: bash + + HOST:/VOL_NAME + + + Where: + + * HOST is the IP address or host name of the Red Hat Storage server. + + * VOL_NAME is the name of an existing and accessible volume on the + GlusterFS server. + + | + + Optionally, if your environment requires additional mount options for + a share, you can add them to the share's entry: + + .. code-block:: yaml + + HOST:/VOL_NAME -o OPTIONS + + Replace OPTIONS with a comma-separated list of mount options. + +#. Set ``/etc/cinder/glusterfs`` to be owned by the root user + and the ``cinder`` group: + + .. code-block:: console + + # chown root:cinder /etc/cinder/glusterfs + +#. Set ``/etc/cinder/glusterfs`` to be readable by members of + the ``cinder`` group: + + .. code-block:: console + + # chmod 0640 /etc/cinder/glusterfs + +#. Configure OpenStack Block Storage to use the ``/etc/cinder/glusterfs`` + file created earlier. To do so, open the ``/etc/cinder/cinder.conf`` + configuration file and set the ``glusterfs_shares_config`` configuration + key to ``/etc/cinder/glusterfs``. + + On distributions that include openstack-config, you can configure this + by running the following command instead: + + .. code-block:: console + + # openstack-config --set /etc/cinder/cinder.conf \ + DEFAULT glusterfs_shares_config /etc/cinder/glusterfs + + The following distributions include ``openstack-config``: + + * CentOS + + * Fedora + + * openSUSE + + * Red Hat Enterprise Linux + + * SUSE Linux Enterprise + + | + +#. Configure OpenStack Block Storage to use the correct volume driver, + namely ``cinder.volume.drivers.glusterfs.GlusterfsDriver``. To do so, + open the ``/etc/cinder/cinder.conf`` configuration file and set + the ``volume_driver`` configuration key to + ``cinder.volume.drivers.glusterfs.GlusterfsDriver``. + + On distributions that include ``openstack-config``, you can configure + this by running the following command instead: + + .. code-block:: console + + # openstack-config --set /etc/cinder/cinder.conf \ + DEFAULT volume_driver cinder.volume.drivers.glusterfs.GlusterfsDriver + +#. You can now restart the service to apply the configuration. + + +OpenStack Block Storage is now configured to use a GlusterFS back end. + +.. warning:: + + If a client host has SELinux enabled, the ``virt_use_fusefs`` boolean + should also be enabled if the host requires access to GlusterFS volumes + on an instance. To enable this Boolean, run the following command as + the ``root`` user: + + .. code-block:: console + + # setsebool -P virt_use_fusefs on + + This command also makes the Boolean persistent across reboots. Run + this command on all client hosts that require access to GlusterFS + volumes on an instance. This includes all compute nodes. + +.. Links +.. _`GlusterFS Documentation`: https://gluster.readthedocs.io/en/latest/ diff --git a/doc/source/admin/blockstorage-glusterfs-removal.rst b/doc/source/admin/blockstorage-glusterfs-removal.rst new file mode 100644 index 00000000000..e2ab957b96e --- /dev/null +++ b/doc/source/admin/blockstorage-glusterfs-removal.rst @@ -0,0 +1,24 @@ +.. _glusterfs_removal: + +=============================================== +Gracefully remove a GlusterFS volume from usage +=============================================== + +Configuring the ``cinder`` volume service to use GlusterFS involves creating a +shares file (for example, ``/etc/cinder/glusterfs``). This shares file +lists each GlusterFS volume (with its corresponding storage server) that +the ``cinder`` volume service can use for back end storage. + +To remove a GlusterFS volume from usage as a back end, delete the volume's +corresponding entry from the shares file. After doing so, restart the Block +Storage services. + +Restarting the Block Storage services will prevent the ``cinder`` volume +service from exporting the deleted GlusterFS volume. This will prevent any +instances from mounting the volume from that point onwards. + +However, the removed GlusterFS volume might still be mounted on an instance +at this point. Typically, this is the case when the volume was already +mounted while its entry was deleted from the shares file. +Whenever this occurs, you will have to unmount the volume as normal after +the Block Storage services are restarted. diff --git a/doc/source/admin/blockstorage-groups.rst b/doc/source/admin/blockstorage-groups.rst new file mode 100644 index 00000000000..f40058e8265 --- /dev/null +++ b/doc/source/admin/blockstorage-groups.rst @@ -0,0 +1,380 @@ +===================== +Generic volume groups +===================== + +Generic volume group support is available in OpenStack Block Storage (cinder) +since the Newton release. The support is added for creating group types and +group specs, creating groups of volumes, and creating snapshots of groups. +The group operations can be performed using the Block Storage command line. + +A group type is a type for a group just like a volume type for a volume. +A group type can also have associated group specs similar to extra specs +for a volume type. + +In cinder, there is a group construct called `consistency group`. Consistency +groups only support consistent group snapshots and only a small number of +drivers can support it. The following is a list of drivers that support +consistency groups and the release when the support was added: + +- Juno: EMC VNX + +- Kilo: EMC VMAX, IBM (GPFS, Storwize, SVC, and XIV), ProphetStor, Pure + +- Liberty: Dell Storage Center, EMC XtremIO, HPE 3Par and LeftHand + +- Mitaka: EMC ScaleIO, NetApp Data ONTAP and E-Series, SolidFire + +- Newton: CoprHD, FalconStor, Huawei + +Consistency group cannot be extended easily to serve other purposes. A tenant +may want to put volumes used in the same application together in a group so +that it is easier to manage them together, and this group of volumes may or +may not support consistent group snapshot. Generic volume group is introduced +to solve this problem. + +There is a plan to migrate existing consistency group operations to use +generic volume group operations in future releases. More information can be +found in `Cinder specs `_. + +.. note:: + + Only Block Storage V3 API supports groups. You can + specify ``--os-volume-api-version 3.x`` when using the `cinder` + command line for group operations where `3.x` contains a microversion value + for that command. The generic volume group feature was completed in several + patches. As a result, the minimum required microversion is different for + group types, groups, and group snapshots APIs. + +The following group type operations are supported: + +- Create a group type. + +- Delete a group type. + +- Set group spec for a group type. + +- Unset group spec for a group type. + +- List group types. + +- Show a group type details. + +- Update a group. + +- List group types and group specs. + +The following group and group snapshot operations are supported: + +- Create a group, given group type and volume types. + + .. note:: + + A group must have one group type. A group can support more than one + volume type. The scheduler is responsible for finding a back end that + can support the given group type and volume types. + + A group can only contain volumes hosted by the same back end. + + A group is empty upon its creation. Volumes need to be created and added + to it later. + +- Show a group. + +- List groups. + +- Delete a group. + +- Modify a group. + +- Create a volume and add it to a group. + +- Create a snapshot for a group. + +- Show a group snapshot. + +- List group snapshots. + +- Delete a group snapshot. + +- Create a group from a group snapshot. + +- Create a group from a source group. + +The following operations are not allowed if a volume is in a group: + +- Volume migration. + +- Volume retype. + +- Volume deletion. + + .. note:: + + A group has to be deleted as a whole with all the volumes. + +The following operations are not allowed if a volume snapshot is in a +group snapshot: + +- Volume snapshot deletion. + + .. note:: + + A group snapshot has to be deleted as a whole with all the volume + snapshots. + +The details of group type operations are shown in the following. The minimum +microversion to support group type and group specs is 3.11: + +**Create a group type**: + +.. code-block:: console + + cinder --os-volume-api-version 3.11 group-type-create + [--description DESCRIPTION] + [--is-public IS_PUBLIC] + NAME + +.. note:: + + The parameter ``NAME`` is required. The + ``--is-public IS_PUBLIC`` determines whether the group type is + accessible to the public. It is ``True`` by default. By default, the + policy on privileges for creating a group type is admin-only. + +**Show a group type**: + +.. code-block:: console + + cinder --os-volume-api-version 3.11 group-type-show + GROUP_TYPE + +.. note:: + + The parameter ``GROUP_TYPE`` is the name or UUID of a group type. + +**List group types**: + +.. code-block:: console + + cinder --os-volume-api-version 3.11 group-type-list + +.. note:: + + Only admin can see private group types. + +**Update a group type**: + +.. code-block:: console + + cinder --os-volume-api-version 3.11 group-type-update + [--name NAME] + [--description DESCRIPTION] + [--is-public IS_PUBLIC] + GROUP_TYPE_ID + +.. note:: + + The parameter ``GROUP_TYPE_ID`` is the UUID of a group type. By default, + the policy on privileges for updating a group type is admin-only. + +**Delete group type or types**: + +.. code-block:: console + + cinder --os-volume-api-version 3.11 group-type-delete + GROUP_TYPE [GROUP_TYPE ...] + +.. note:: + + The parameter ``GROUP_TYPE`` is name or UUID of the group type or + group types to be deleted. By default, the policy on privileges for + deleting a group type is admin-only. + +**Set or unset group spec for a group type**: + +.. code-block:: console + + cinder --os-volume-api-version 3.11 group-type-key + GROUP_TYPE ACTION KEY=VALUE [KEY=VALUE ...] + +.. note:: + + The parameter ``GROUP_TYPE`` is the name or UUID of a group type. Valid + values for the parameter ``ACTION`` are ``set`` or ``unset``. + ``KEY=VALUE`` is the group specs key and value pair to set or unset. + For unset, specify only the key. By default, the policy on privileges + for setting or unsetting group specs key is admin-only. + +**List group types and group specs**: + +.. code-block:: console + + cinder --os-volume-api-version 3.11 group-specs-list + +.. note:: + + By default, the policy on privileges for seeing group specs is admin-only. + +The details of group operations are shown in the following. The minimum +microversion to support groups operations is 3.13. + +**Create a group**: + +.. code-block:: console + + cinder --os-volume-api-version 3.13 group-create + [--name NAME] + [--description DESCRIPTION] + [--availability-zone AVAILABILITY_ZONE] + GROUP_TYPE VOLUME_TYPES + +.. note:: + + The parameters ``GROUP_TYPE`` and ``VOLUME_TYPES`` are required. + ``GROUP_TYPE`` is the name or UUID of a group type. ``VOLUME_TYPES`` + can be a list of names or UUIDs of volume types separated by commas + without spaces in between. For example, + ``volumetype1,volumetype2,volumetype3.``. + +**Show a group**: + +.. code-block:: console + + cinder --os-volume-api-version 3.13 group-show + GROUP + +.. note:: + + The parameter ``GROUP`` is the name or UUID of a group. + +**List groups**: + +.. code-block:: console + + cinder --os-volume-api-version 3.13 group-list + [--all-tenants [<0|1>]] + +.. note:: + + ``--all-tenants`` specifies whether to list groups for all tenants. + Only admin can use this option. + +**Create a volume and add it to a group**: + +.. code-block:: console + + cinder --os-volume-api-version 3.13 create + --volume-type VOLUME_TYPE + --group-id GROUP_ID SIZE + +.. note:: + + When creating a volume and adding it to a group, the parameters + ``VOLUME_TYPE`` and ``GROUP_ID`` must be provided. This is because a group + can support more than one volume type. + +**Delete a group**: + +.. code-block:: console + + cinder --os-volume-api-version 3.13 group-delete + [--delete-volumes] + GROUP [GROUP ...] + +.. note:: + + ``--delete-volumes`` allows or disallows groups to be deleted + if they are not empty. If the group is empty, it can be deleted without + ``--delete-volumes``. If the group is not empty, the flag is + required for it to be deleted. When the flag is specified, the group + and all volumes in the group will be deleted. + +**Modify a group**: + +.. code-block:: console + + cinder --os-volume-api-version 3.13 group-update + [--name NAME] + [--description DESCRIPTION] + [--add-volumes UUID1,UUID2,......] + [--remove-volumes UUID3,UUID4,......] + GROUP + +.. note:: + + The parameter ``UUID1,UUID2,......`` is the UUID of one or more volumes + to be added to the group, separated by commas. Similarly the parameter + ``UUID3,UUID4,......`` is the UUID of one or more volumes to be removed + from the group, separated by commas. + +The details of group snapshots operations are shown in the following. The +minimum microversion to support group snapshots operations is 3.14. + +**Create a snapshot for a group**: + +.. code-block:: console + + cinder --os-volume-api-version 3.14 group-snapshot-create + [--name NAME] + [--description DESCRIPTION] + GROUP + +.. note:: + + The parameter ``GROUP`` is the name or UUID of a group. + +**Show a group snapshot**: + +.. code-block:: console + + cinder --os-volume-api-version 3.14 group-snapshot-show + GROUP_SNAPSHOT + +.. note:: + + The parameter ``GROUP_SNAPSHOT`` is the name or UUID of a group snapshot. + +**List group snapshots**: + +.. code-block:: console + + cinder --os-volume-api-version 3.14 group-snapshot-list + [--all-tenants [<0|1>]] + [--status STATUS] + [--group-id GROUP_ID] + +.. note:: + + ``--all-tenants`` specifies whether to list group snapshots for + all tenants. Only admin can use this option. ``--status STATUS`` + filters results by a status. ``--group-id GROUP_ID`` filters + results by a group id. + +**Delete group snapshot**: + +.. code-block:: console + + cinder --os-volume-api-version 3.14 group-snapshot-delete + GROUP_SNAPSHOT [GROUP_SNAPSHOT ...] + +.. note:: + + The parameter ``GROUP_SNAPSHOT`` specifies the name or UUID of one or more + group snapshots to be deleted. + +**Create a group from a group snapshot or a source group**: + +.. code-block:: console + + $ cinder --os-volume-api-version 3.14 group-create-from-src + [--group-snapshot GROUP_SNAPSHOT] + [--source-group SOURCE_GROUP] + [--name NAME] + [--description DESCRIPTION] + +.. note:: + + The parameter ``GROUP_SNAPSHOT`` is a name or UUID of a group snapshot. + The parameter ``SOURCE_GROUP`` is a name or UUID of a source group. + Either ``GROUP_SNAPSHOT`` or ``SOURCE_GROUP`` must be specified, but not + both. diff --git a/doc/source/admin/blockstorage-image-volume-cache.rst b/doc/source/admin/blockstorage-image-volume-cache.rst new file mode 100644 index 00000000000..589ccd92311 --- /dev/null +++ b/doc/source/admin/blockstorage-image-volume-cache.rst @@ -0,0 +1,117 @@ +.. _image_volume_cache: + + +================== +Image-Volume cache +================== + +OpenStack Block Storage has an optional Image cache which can dramatically +improve the performance of creating a volume from an image. The improvement +depends on many factors, primarily how quickly the configured back end can +clone a volume. + +When a volume is first created from an image, a new cached image-volume +will be created that is owned by the Block Storage Internal Tenant. Subsequent +requests to create volumes from that image will clone the cached version +instead of downloading the image contents and copying data to the volume. + +The cache itself is configurable per back end and will contain the most +recently used images. + +Configure the Internal Tenant +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Image-Volume cache requires that the Internal Tenant be configured for +the Block Storage services. This project will own the cached image-volumes so +they can be managed like normal users including tools like volume quotas. This +protects normal users from having to see the cached image-volumes, but does +not make them globally hidden. + +To enable the Block Storage services to have access to an Internal Tenant, set +the following options in the ``cinder.conf`` file: + +.. code-block:: ini + + cinder_internal_tenant_project_id = PROJECT_ID + cinder_internal_tenant_user_id = USER_ID + +An example ``cinder.conf`` configuration file: + +.. code-block:: ini + + cinder_internal_tenant_project_id = b7455b8974bb4064ad247c8f375eae6c + cinder_internal_tenant_user_id = f46924c112a14c80ab0a24a613d95eef + +.. note:: + + The actual user and project that are configured for the Internal Tenant do + not require any special privileges. They can be the Block Storage service + project or can be any normal project and user. + +Configure the Image-Volume cache +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable the Image-Volume cache, set the following configuration option in +the ``cinder.conf`` file: + +.. code-block:: ini + + image_volume_cache_enabled = True + +.. note:: + + If you use Ceph as a back end, set the following configuration option in + the ``cinder.conf`` file: + + .. code-block:: ini + + [ceph] + image_volume_cache_enabled = True + +This can be scoped per back end definition or in the default options. + +There are optional configuration settings that can limit the size of the cache. +These can also be scoped per back end or in the default options in +the ``cinder.conf`` file: + +.. code-block:: ini + + image_volume_cache_max_size_gb = SIZE_GB + image_volume_cache_max_count = MAX_COUNT + +By default they will be set to 0, which means unlimited. + +For example, a configuration which would limit the max size to 200 GB and 50 +cache entries will be configured as: + +.. code-block:: ini + + image_volume_cache_max_size_gb = 200 + image_volume_cache_max_count = 50 + +Notifications +~~~~~~~~~~~~~ + +Cache actions will trigger Telemetry messages. There are several that will be +sent. + +- ``image_volume_cache.miss`` - A volume is being created from an image which + was not found in the cache. Typically this will mean a new cache entry would + be created for it. + +- ``image_volume_cache.hit`` - A volume is being created from an image which + was found in the cache and the fast path can be taken. + +- ``image_volume_cache.evict`` - A cached image-volume has been deleted from + the cache. + + +Managing cached Image-Volumes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In normal usage there should be no need for manual intervention with the cache. +The entries and their backing Image-Volumes are managed automatically. + +If needed, you can delete these volumes manually to clear the cache. +By using the standard volume deletion APIs, the Block Storage service will +clean up correctly. diff --git a/doc/source/admin/blockstorage-lio-iscsi-support.rst b/doc/source/admin/blockstorage-lio-iscsi-support.rst new file mode 100644 index 00000000000..b2d525ff98d --- /dev/null +++ b/doc/source/admin/blockstorage-lio-iscsi-support.rst @@ -0,0 +1,12 @@ +===================== +Use LIO iSCSI support +===================== + +The default mode for the ``iscsi_helper`` tool is ``tgtadm``. +To use LIO iSCSI, install the ``python-rtslib`` package, and set +``iscsi_helper=lioadm`` in the ``cinder.conf`` file. + +Once configured, you can use the :command:`cinder-rtstool` command to +manage the volumes. This command enables you to create, delete, and +verify volumes and determine targets and add iSCSI initiators to the +system. diff --git a/doc/source/admin/blockstorage-manage-volumes.rst b/doc/source/admin/blockstorage-manage-volumes.rst new file mode 100644 index 00000000000..f2d2974be4a --- /dev/null +++ b/doc/source/admin/blockstorage-manage-volumes.rst @@ -0,0 +1,82 @@ +============== +Manage volumes +============== + +The default OpenStack Block Storage service implementation is an +iSCSI solution that uses :term:`Logical Volume Manager (LVM)` for Linux. + +.. note:: + + The OpenStack Block Storage service is not a shared storage + solution like a Network Attached Storage (NAS) of NFS volumes + where you can attach a volume to multiple servers. With the + OpenStack Block Storage service, you can attach a volume to only + one instance at a time. + + The OpenStack Block Storage service also provides drivers that + enable you to use several vendors' back-end storage devices in + addition to the base LVM implementation. These storage devices can + also be used instead of the base LVM installation. + +This high-level procedure shows you how to create and attach a volume +to a server instance. + +**To create and attach a volume to an instance** + +#. Configure the OpenStack Compute and the OpenStack Block Storage + services through the ``/etc/cinder/cinder.conf`` file. +#. Use the :command:`openstack volume create` command to create a volume. + This command creates an LV into the volume group (VG) ``cinder-volumes``. +#. Use the :command:`openstack server add volume` command to attach the + volume to an instance. This command creates a unique :term:`IQN ` that is exposed to the compute node. + + * The compute node, which runs the instance, now has an active + iSCSI session and new local storage (usually a ``/dev/sdX`` + disk). + * Libvirt uses that local storage as storage for the instance. The + instance gets a new disk (usually a ``/dev/vdX`` disk). + +For this particular walkthrough, one cloud controller runs +``nova-api``, ``nova-scheduler``, ``nova-objectstore``, +``nova-network`` and ``cinder-*`` services. Two additional compute +nodes run ``nova-compute``. The walkthrough uses a custom +partitioning scheme that carves out 60 GB of space and labels it as +LVM. The network uses the ``FlatManager`` and ``NetworkManager`` +settings for OpenStack Compute. + +The network mode does not interfere with OpenStack Block Storage +operations, but you must set up networking for Block Storage to work. +For details, see :ref:`networking`. + +To set up Compute to use volumes, ensure that Block Storage is +installed along with ``lvm2``. This guide describes how to +troubleshoot your installation and back up your Compute volumes. + +.. toctree:: + + blockstorage-boot-from-volume.rst + blockstorage-nfs-backend.rst + blockstorage-glusterfs-backend.rst + blockstorage-multi-backend.rst + blockstorage-backup-disks.rst + blockstorage-volume-migration.rst + blockstorage-glusterfs-removal.rst + blockstorage-volume-backups.rst + blockstorage-volume-backups-export-import.rst + blockstorage-lio-iscsi-support.rst + blockstorage-volume-number-weigher.rst + blockstorage-consistency-groups.rst + blockstorage-driver-filter-weighing.rst + blockstorage-ratelimit-volume-copy-bandwidth.rst + blockstorage-over-subscription.rst + blockstorage-image-volume-cache.rst + blockstorage-volume-backed-image.rst + blockstorage-get-capabilities.rst + blockstorage-groups.rst + +.. note:: + + To enable the use of encrypted volumes, see the setup instructions in + `Create an encrypted volume type + `_. diff --git a/doc/source/admin/blockstorage-multi-backend.rst b/doc/source/admin/blockstorage-multi-backend.rst new file mode 100644 index 00000000000..a09b4d1e74e --- /dev/null +++ b/doc/source/admin/blockstorage-multi-backend.rst @@ -0,0 +1,185 @@ +.. _multi_backend: + +==================================== +Configure multiple-storage back ends +==================================== + +When you configure multiple-storage back ends, you can create several +back-end storage solutions that serve the same OpenStack Compute +configuration and one ``cinder-volume`` is launched for each back-end +storage or back-end storage pool. + +In a multiple-storage back-end configuration, each back end has a name +(``volume_backend_name``). Several back ends can have the same name. +In that case, the scheduler properly decides which back end the volume +has to be created in. + +The name of the back end is declared as an extra-specification of a +volume type (such as, ``volume_backend_name=LVM``). When a volume +is created, the scheduler chooses an appropriate back end to handle the +request, according to the volume type specified by the user. + +Enable multiple-storage back ends +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable a multiple-storage back ends, you must set the +`enabled_backends` flag in the ``cinder.conf`` file. +This flag defines the names (separated by a comma) of the configuration +groups for the different back ends: one name is associated to one +configuration group for a back end (such as, ``[lvmdriver-1]``). + +.. note:: + + The configuration group name is not related to the ``volume_backend_name``. + +.. note:: + + After setting the ``enabled_backends`` flag on an existing cinder + service, and restarting the Block Storage services, the original ``host`` + service is replaced with a new host service. The new service appears + with a name like ``host@backend``. Use: + + .. code-block:: console + + $ cinder-manage volume update_host --currenthost CURRENTHOST --newhost CURRENTHOST@BACKEND + + to convert current block devices to the new host name. + +The options for a configuration group must be defined in the group +(or default options are used). All the standard Block Storage +configuration options (``volume_group``, ``volume_driver``, and so on) +might be used in a configuration group. Configuration values in +the ``[DEFAULT]`` configuration group are not used. + +These examples show three back ends: + +.. code-block:: ini + + enabled_backends=lvmdriver-1,lvmdriver-2,lvmdriver-3 + [lvmdriver-1] + volume_group=cinder-volumes-1 + volume_driver=cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name=LVM + [lvmdriver-2] + volume_group=cinder-volumes-2 + volume_driver=cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name=LVM + [lvmdriver-3] + volume_group=cinder-volumes-3 + volume_driver=cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name=LVM_b + +In this configuration, ``lvmdriver-1`` and ``lvmdriver-2`` have the same +``volume_backend_name``. If a volume creation requests the ``LVM`` +back end name, the scheduler uses the capacity filter scheduler to choose +the most suitable driver, which is either ``lvmdriver-1`` or ``lvmdriver-2``. +The capacity filter scheduler is enabled by default. The next section +provides more information. In addition, this example presents a +``lvmdriver-3`` back end. + +.. note:: + + For Fiber Channel drivers that support multipath, the configuration group + requires the ``use_multipath_for_image_xfer=true`` option. In + the example below, you can see details for HPE 3PAR and EMC Fiber + Channel drivers. + +.. code-block:: ini + + [3par] + use_multipath_for_image_xfer = true + volume_driver = cinder.volume.drivers.hpe.hpe_3par_fc.HPE3PARFCDriver + volume_backend_name = 3parfc + + [emc] + use_multipath_for_image_xfer = true + volume_driver = cinder.volume.drivers.emc.emc_smis_fc.EMCSMISFCDriver + volume_backend_name = emcfc + +Configure Block Storage scheduler multi back end +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must enable the `filter_scheduler` option to use +multiple-storage back ends. The filter scheduler: + +#. Filters the available back ends. By default, ``AvailabilityZoneFilter``, + ``CapacityFilter`` and ``CapabilitiesFilter`` are enabled. + +#. Weights the previously filtered back ends. By default, the + `CapacityWeigher` option is enabled. When this option is + enabled, the filter scheduler assigns the highest weight to back + ends with the most available capacity. + +The scheduler uses filters and weights to pick the best back end to +handle the request. The scheduler uses volume types to explicitly create +volumes on specific back ends. For more information about filter and weighing, +see :ref:`filter_weigh_scheduler`. + + +Volume type +~~~~~~~~~~~ + +Before using it, a volume type has to be declared to Block Storage. +This can be done by the following command: + +.. code-block:: console + + $ openstack --os-username admin --os-tenant-name admin volume type create lvm + +Then, an extra-specification has to be created to link the volume +type to a back end name. Run this command: + +.. code-block:: console + + $ openstack --os-username admin --os-tenant-name admin volume type set lvm \ + --property volume_backend_name=LVM_iSCSI + +This example creates a ``lvm`` volume type with +``volume_backend_name=LVM_iSCSI`` as extra-specifications. + +Create another volume type: + +.. code-block:: console + + $ openstack --os-username admin --os-tenant-name admin volume type create lvm_gold + + $ openstack --os-username admin --os-tenant-name admin volume type set lvm_gold \ + --property volume_backend_name=LVM_iSCSI_b + +This second volume type is named ``lvm_gold`` and has ``LVM_iSCSI_b`` as +back end name. + +.. note:: + + To list the extra-specifications, use this command: + + .. code-block:: console + + $ openstack --os-username admin --os-tenant-name admin volume type list --long + +.. note:: + + If a volume type points to a ``volume_backend_name`` that does not + exist in the Block Storage configuration, the ``filter_scheduler`` + returns an error that it cannot find a valid host with the suitable + back end. + +Usage +~~~~~ + +When you create a volume, you must specify the volume type. +The extra-specifications of the volume type are used to determine which +back end has to be used. + +.. code-block:: console + + $ openstack volume create --size 1 --type lvm test_multi_backend + +Considering the ``cinder.conf`` described previously, the scheduler +creates this volume on ``lvmdriver-1`` or ``lvmdriver-2``. + +.. code-block:: console + + $ openstack volume create --size 1 --type lvm_gold test_multi_backend + +This second volume is created on ``lvmdriver-3``. diff --git a/doc/source/admin/blockstorage-nfs-backend.rst b/doc/source/admin/blockstorage-nfs-backend.rst new file mode 100644 index 00000000000..63c03e4f82d --- /dev/null +++ b/doc/source/admin/blockstorage-nfs-backend.rst @@ -0,0 +1,162 @@ +================================= +Configure an NFS storage back end +================================= + +This section explains how to configure OpenStack Block Storage to use +NFS storage. You must be able to access the NFS shares from the server +that hosts the ``cinder`` volume service. + +.. note:: + + The ``cinder`` volume service is named ``openstack-cinder-volume`` + on the following distributions: + + * CentOS + + * Fedora + + * openSUSE + + * Red Hat Enterprise Linux + + * SUSE Linux Enterprise + + In Ubuntu and Debian distributions, the ``cinder`` volume service is + named ``cinder-volume``. + +**Configure Block Storage to use an NFS storage back end** + +#. Log in as ``root`` to the system hosting the ``cinder`` volume + service. + +#. Create a text file named ``nfsshares`` in the ``/etc/cinder/`` directory. + +#. Add an entry to ``/etc/cinder/nfsshares`` for each NFS share + that the ``cinder`` volume service should use for back end storage. + Each entry should be a separate line, and should use the following + format: + + .. code-block:: bash + + HOST:SHARE + + + Where: + + * HOST is the IP address or host name of the NFS server. + + * SHARE is the absolute path to an existing and accessible NFS share. + + | + +#. Set ``/etc/cinder/nfsshares`` to be owned by the ``root`` user and + the ``cinder`` group: + + .. code-block:: console + + # chown root:cinder /etc/cinder/nfsshares + +#. Set ``/etc/cinder/nfsshares`` to be readable by members of the + cinder group: + + .. code-block:: console + + # chmod 0640 /etc/cinder/nfsshares + +#. Configure the ``cinder`` volume service to use the + ``/etc/cinder/nfsshares`` file created earlier. To do so, open + the ``/etc/cinder/cinder.conf`` configuration file and set + the ``nfs_shares_config`` configuration key + to ``/etc/cinder/nfsshares``. + + On distributions that include ``openstack-config``, you can configure + this by running the following command instead: + + .. code-block:: console + + # openstack-config --set /etc/cinder/cinder.conf \ + DEFAULT nfs_shares_config /etc/cinder/nfsshares + + The following distributions include openstack-config: + + * CentOS + + * Fedora + + * openSUSE + + * Red Hat Enterprise Linux + + * SUSE Linux Enterprise + + +#. Optionally, provide any additional NFS mount options required in + your environment in the ``nfs_mount_options`` configuration key + of ``/etc/cinder/cinder.conf``. If your NFS shares do not + require any additional mount options (or if you are unsure), + skip this step. + + On distributions that include ``openstack-config``, you can + configure this by running the following command instead: + + .. code-block:: console + + # openstack-config --set /etc/cinder/cinder.conf \ + DEFAULT nfs_mount_options OPTIONS + + Replace OPTIONS with the mount options to be used when accessing + NFS shares. See the manual page for NFS for more information on + available mount options (:command:`man nfs`). + +#. Configure the ``cinder`` volume service to use the correct volume + driver, namely ``cinder.volume.drivers.nfs.NfsDriver``. To do so, + open the ``/etc/cinder/cinder.conf`` configuration file and + set the volume_driver configuration key + to ``cinder.volume.drivers.nfs.NfsDriver``. + + On distributions that include ``openstack-config``, you can configure + this by running the following command instead: + + .. code-block:: console + + # openstack-config --set /etc/cinder/cinder.conf \ + DEFAULT volume_driver cinder.volume.drivers.nfs.NfsDriver + +#. You can now restart the service to apply the configuration. + + .. note:: + + The ``nfs_sparsed_volumes`` configuration key determines whether + volumes are created as sparse files and grown as needed or fully + allocated up front. The default and recommended value is ``true``, + which ensures volumes are initially created as sparse files. + + Setting ``nfs_sparsed_volumes`` to ``false`` will result in + volumes being fully allocated at the time of creation. This leads + to increased delays in volume creation. + + However, should you choose to set ``nfs_sparsed_volumes`` to + ``false``, you can do so directly in ``/etc/cinder/cinder.conf``. + + On distributions that include ``openstack-config``, you can + configure this by running the following command instead: + + .. code-block:: console + + # openstack-config --set /etc/cinder/cinder.conf \ + DEFAULT nfs_sparsed_volumes false + + .. warning:: + + If a client host has SELinux enabled, the ``virt_use_nfs`` + boolean should also be enabled if the host requires access to + NFS volumes on an instance. To enable this boolean, run the + following command as the ``root`` user: + + .. code-block:: console + + # setsebool -P virt_use_nfs on + + This command also makes the boolean persistent across reboots. + Run this command on all client hosts that require access to NFS + volumes on an instance. This includes all compute nodes. diff --git a/doc/source/admin/blockstorage-over-subscription.rst b/doc/source/admin/blockstorage-over-subscription.rst new file mode 100644 index 00000000000..5606e499f6b --- /dev/null +++ b/doc/source/admin/blockstorage-over-subscription.rst @@ -0,0 +1,140 @@ +.. _over_subscription: + +===================================== +Oversubscription in thin provisioning +===================================== + +OpenStack Block Storage enables you to choose a volume back end based on +virtual capacities for thin provisioning using the oversubscription ratio. + +A reference implementation is provided for the default LVM driver. The +illustration below uses the LVM driver as an example. + +Configure oversubscription settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To support oversubscription in thin provisioning, a flag +``max_over_subscription_ratio`` is introduced into ``cinder.conf``. +This is a float representation of the oversubscription ratio when thin +provisioning is involved. Default ratio is 20.0, meaning provisioned +capacity can be 20 times of the total physical capacity. A ratio of 10.5 +means provisioned capacity can be 10.5 times of the total physical capacity. +A ratio of 1.0 means provisioned capacity cannot exceed the total physical +capacity. A ratio lower than 1.0 is ignored and the default value is used +instead. + +.. note:: + + ``max_over_subscription_ratio`` can be configured for each back end when + multiple-storage back ends are enabled. It is provided as a reference + implementation and is used by the LVM driver. However, it is not a + requirement for a driver to use this option from ``cinder.conf``. + + ``max_over_subscription_ratio`` is for configuring a back end. For a + driver that supports multiple pools per back end, it can report this + ratio for each pool. The LVM driver does not support multiple pools. + +The existing ``reserved_percentage`` flag is used to prevent over provisioning. +This flag represents the percentage of the back-end capacity that is reserved. + +.. note:: + + There is a change on how ``reserved_percentage`` is used. It was measured + against the free capacity in the past. Now it is measured against the total + capacity. + +Capabilities +~~~~~~~~~~~~ + +Drivers can report the following capabilities for a back end or a pool: + +.. code-block:: ini + + thin_provisioning_support = True(or False) + thick_provisioning_support = True(or False) + provisioned_capacity_gb = PROVISIONED_CAPACITY + max_over_subscription_ratio = MAX_RATIO + +Where ``PROVISIONED_CAPACITY`` is the apparent allocated space indicating +how much capacity has been provisioned and ``MAX_RATIO`` is the maximum +oversubscription ratio. For the LVM driver, it is +``max_over_subscription_ratio`` in ``cinder.conf``. + +Two capabilities are added here to allow a back end or pool to claim support +for thin provisioning, or thick provisioning, or both. + +The LVM driver reports ``thin_provisioning_support=True`` and +``thick_provisioning_support=False`` if the ``lvm_type`` flag in +``cinder.conf`` is ``thin``. Otherwise it reports +``thin_provisioning_support=False`` and ``thick_provisioning_support=True``. + +Volume type extra specs +~~~~~~~~~~~~~~~~~~~~~~~ + +If volume type is provided as part of the volume creation request, it can +have the following extra specs defined: + +.. code-block:: python + + 'capabilities:thin_provisioning_support': ' True' or ' False' + 'capabilities:thick_provisioning_support': ' True' or ' False' + +.. note:: + + ``capabilities`` scope key before ``thin_provisioning_support`` and + ``thick_provisioning_support`` is not required. So the following works too: + +.. code-block:: python + + 'thin_provisioning_support': ' True' or ' False' + 'thick_provisioning_support': ' True' or ' False' + +The above extra specs are used by the scheduler to find a back end that +supports thin provisioning, thick provisioning, or both to match the needs +of a specific volume type. + +Volume replication extra specs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenStack Block Storage has the ability to create volume replicas. +Administrators can define a storage policy that includes +replication by adjusting the cinder volume driver. Volume replication +for OpenStack Block Storage helps safeguard OpenStack environments from +data loss during disaster recovery. + +To enable replication when creating volume types, configure the cinder +volume with ``capabilities:replication=" True"``. + +Each volume created with the replication capability set to ``True`` +generates a copy of the volume on a storage back end. + +One use case for replication involves an OpenStack cloud environment +installed across two data centers located nearby each other. The +distance between the two data centers in this use case is the length of +a city. + +At each data center, a cinder host supports the Block Storage service. +Both data centers include storage back ends. + +Depending on the storage requirements, there can be one or two cinder +hosts. The administrator accesses the +``/etc/cinder/cinder.conf`` configuration file and sets +``capabilities:replication=" True"``. + +If one data center experiences a service failure, administrators +can redeploy the VM. The VM will run using a replicated, backed up +volume on a host in the second data center. + +Capacity filter +~~~~~~~~~~~~~~~ + +In the capacity filter, ``max_over_subscription_ratio`` is used when +choosing a back end if ``thin_provisioning_support`` is True and +``max_over_subscription_ratio`` is greater than 1.0. + +Capacity weigher +~~~~~~~~~~~~~~~~ + +In the capacity weigher, virtual free capacity is used for ranking if +``thin_provisioning_support`` is True. Otherwise, real free capacity +will be used as before. diff --git a/doc/source/admin/blockstorage-ratelimit-volume-copy-bandwidth.rst b/doc/source/admin/blockstorage-ratelimit-volume-copy-bandwidth.rst new file mode 100644 index 00000000000..91416a866cd --- /dev/null +++ b/doc/source/admin/blockstorage-ratelimit-volume-copy-bandwidth.rst @@ -0,0 +1,46 @@ +.. _ratelimit_volume_copy_bandwidth: + +================================ +Rate-limit volume copy bandwidth +================================ + +When you create a new volume from an image or an existing volume, or +when you upload a volume image to the Image service, large data copy +may stress disk and network bandwidth. To mitigate slow down of data +access from the instances, OpenStack Block Storage supports rate-limiting +of volume data copy bandwidth. + +Configure volume copy bandwidth limit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure the volume copy bandwidth limit, set the +``volume_copy_bps_limit`` option in the configuration groups for each +back end in the ``cinder.conf`` file. This option takes the integer of +maximum bandwidth allowed for volume data copy in byte per second. If +this option is set to ``0``, the rate-limit is disabled. + +While multiple volume data copy operations are running in the same back +end, the specified bandwidth is divided to each copy. + +Example ``cinder.conf`` configuration file to limit volume copy bandwidth +of ``lvmdriver-1`` up to 100 MiB/s: + +.. code-block:: ini + + [lvmdriver-1] + volume_group=cinder-volumes-1 + volume_driver=cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name=LVM + volume_copy_bps_limit=104857600 + +.. note:: + + This feature requires libcgroup to set up blkio cgroup for disk I/O + bandwidth limit. The libcgroup is provided by the cgroup-bin package + in Debian and Ubuntu, or by the libcgroup-tools package in Fedora, + Red Hat Enterprise Linux, CentOS, openSUSE, and SUSE Linux Enterprise. + +.. note:: + + Some back ends which use remote file systems such as NFS are not + supported by this feature. diff --git a/doc/source/admin/blockstorage-troubleshoot.rst b/doc/source/admin/blockstorage-troubleshoot.rst new file mode 100644 index 00000000000..b16e055bb7e --- /dev/null +++ b/doc/source/admin/blockstorage-troubleshoot.rst @@ -0,0 +1,22 @@ +============================== +Troubleshoot your installation +============================== + +This section provides useful tips to help you troubleshoot your Block +Storage installation. + +.. toctree:: + :maxdepth: 1 + + ts-cinder-config.rst + ts-multipath-warn.rst + ts-eql-volume-size.rst + ts-vol-attach-miss-sg-scan.rst + ts-HTTP-bad-req-in-cinder-vol-log.rst + ts-duplicate-3par-host.rst + ts-failed-attach-vol-after-detach.rst + ts-failed-attach-vol-no-sysfsutils.rst + ts-failed-connect-vol-FC-SAN.rst + ts-no-emulator-x86-64.rst + ts-non-existent-host.rst + ts-non-existent-vlun.rst diff --git a/doc/source/admin/blockstorage-volume-backed-image.rst b/doc/source/admin/blockstorage-volume-backed-image.rst new file mode 100644 index 00000000000..0833c7dc8bf --- /dev/null +++ b/doc/source/admin/blockstorage-volume-backed-image.rst @@ -0,0 +1,90 @@ +.. _volume_backed_image: + + +=================== +Volume-backed image +=================== + +OpenStack Block Storage can quickly create a volume from an image that refers +to a volume storing image data (Image-Volume). Compared to the other stores +such as file and swift, creating a volume from a Volume-backed image performs +better when the block storage driver supports efficient volume cloning. + +If the image is set to public in the Image service, the volume data can be +shared among projects. + +Configure the Volume-backed image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Volume-backed image feature requires locations information from the cinder +store of the Image service. To enable the Image service to use the cinder +store, add ``cinder`` to the ``stores`` option in the ``glance_store`` section +of the ``glance-api.conf`` file: + +.. code-block:: ini + + stores = file, http, swift, cinder + +To expose locations information, set the following options in the ``DEFAULT`` +section of the ``glance-api.conf`` file: + +.. code-block:: ini + + show_multiple_locations = True + +To enable the Block Storage services to create a new volume by cloning Image- +Volume, set the following options in the ``DEFAULT`` section of the +``cinder.conf`` file. For example: + +.. code-block:: ini + + glance_api_version = 2 + allowed_direct_url_schemes = cinder + +To enable the :command:`openstack image create --volume ` command to +create an image that refers an ``Image-Volume``, set the following options in +each back-end section of the ``cinder.conf`` file: + +.. code-block:: ini + + image_upload_use_cinder_backend = True + +By default, the :command:`openstack image create --volume ` command +creates the Image-Volume in the current project. To store the Image-Volume into +the internal project, set the following options in each back-end section of the +``cinder.conf`` file: + +.. code-block:: ini + + image_upload_use_internal_tenant = True + +To make the Image-Volume in the internal project accessible from the Image +service, set the following options in the ``glance_store`` section of +the ``glance-api.conf`` file: + +- ``cinder_store_auth_address`` +- ``cinder_store_user_name`` +- ``cinder_store_password`` +- ``cinder_store_project_name`` + +Creating a Volume-backed image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To register an existing volume as a new Volume-backed image, use the following +commands: + +.. code-block:: console + + $ openstack image create --disk-format raw --container-format bare IMAGE_NAME + + $ glance location-add --url cinder:// + +If the ``image_upload_use_cinder_backend`` option is enabled, the following +command creates a new Image-Volume by cloning the specified volume and then +registers its location to a new image. The disk format and the container format +must be raw and bare (default). Otherwise, the image is uploaded to the default +store of the Image service. + +.. code-block:: console + + $ openstack image create --volume SOURCE_VOLUME IMAGE_NAME diff --git a/doc/source/admin/blockstorage-volume-backups-export-import.rst b/doc/source/admin/blockstorage-volume-backups-export-import.rst new file mode 100644 index 00000000000..6516fd25a51 --- /dev/null +++ b/doc/source/admin/blockstorage-volume-backups-export-import.rst @@ -0,0 +1,58 @@ +.. _volume_backups_export_import: + +================================= +Export and import backup metadata +================================= + + +A volume backup can only be restored on the same Block Storage service. This +is because restoring a volume from a backup requires metadata available on +the database used by the Block Storage service. + +.. note:: + + For information about how to back up and restore a volume, see + the section called :ref:`volume_backups`. + +You can, however, export the metadata of a volume backup. To do so, run +this command as an OpenStack ``admin`` user (presumably, after creating +a volume backup): + +.. code-block:: console + + $ cinder backup-export BACKUP_ID + +Where ``BACKUP_ID`` is the volume backup's ID. This command should return the +backup's corresponding database information as encoded string metadata. + +Exporting and storing this encoded string metadata allows you to completely +restore the backup, even in the event of a catastrophic database failure. +This will preclude the need to back up the entire Block Storage database, +particularly if you only need to keep complete backups of a small subset +of volumes. + +If you have placed encryption on your volumes, the encryption will still be +in place when you restore the volume if a UUID encryption key is specified +when creating volumes. Using backup metadata support, UUID keys set up for +a volume (or volumes) will remain valid when you restore a backed-up volume. +The restored volume will remain encrypted, and will be accessible with your +credentials. + +In addition, having a volume backup and its backup metadata also provides +volume portability. Specifically, backing up a volume and exporting its +metadata will allow you to restore the volume on a completely different Block +Storage database, or even on a different cloud service. To do so, first +import the backup metadata to the Block Storage database and then restore +the backup. + +To import backup metadata, run the following command as an OpenStack +``admin``: + +.. code-block:: console + + $ cinder backup-import METADATA + +Where ``METADATA`` is the backup metadata exported earlier. + +Once you have imported the backup metadata into a Block Storage database, +restore the volume (see the section called :ref:`volume_backups`). diff --git a/doc/source/admin/blockstorage-volume-backups.rst b/doc/source/admin/blockstorage-volume-backups.rst new file mode 100644 index 00000000000..e2a32a27ef2 --- /dev/null +++ b/doc/source/admin/blockstorage-volume-backups.rst @@ -0,0 +1,175 @@ +.. _volume_backups: + +========================================= +Back up and restore volumes and snapshots +========================================= + +The ``openstack`` command-line interface provides the tools for creating a +volume backup. You can restore a volume from a backup as long as the +backup's associated database information (or backup metadata) is intact +in the Block Storage database. + +Run this command to create a backup of a volume: + +.. code-block:: console + + $ openstack volume backup create [--incremental] [--force] VOLUME + +Where ``VOLUME`` is the name or ID of the volume, ``incremental`` is +a flag that indicates whether an incremental backup should be performed, +and ``force`` is a flag that allows or disallows backup of a volume +when the volume is attached to an instance. + +Without the ``incremental`` flag, a full backup is created by default. +With the ``incremental`` flag, an incremental backup is created. + +Without the ``force`` flag, the volume will be backed up only if its +status is ``available``. With the ``force`` flag, the volume will be +backed up whether its status is ``available`` or ``in-use``. A volume +is ``in-use`` when it is attached to an instance. The backup of an +``in-use`` volume means your data is crash consistent. The ``force`` +flag is False by default. + +.. note:: + + The ``incremental`` and ``force`` flags are only available for block + storage API v2. You have to specify ``[--os-volume-api-version 2]`` in the + ``cinder`` command-line interface to use this parameter. + +.. note:: + + The ``force`` flag is new in OpenStack Liberty. + +The incremental backup is based on a parent backup which is an existing +backup with the latest timestamp. The parent backup can be a full backup +or an incremental backup depending on the timestamp. + + +.. note:: + + The first backup of a volume has to be a full backup. Attempting to do + an incremental backup without any existing backups will fail. + There is an ``is_incremental`` flag that indicates whether a backup is + incremental when showing details on the backup. + Another flag, ``has_dependent_backups``, returned when showing backup + details, will indicate whether the backup has dependent backups. + If it is ``true``, attempting to delete this backup will fail. + +A new configure option ``backup_swift_block_size`` is introduced into +``cinder.conf`` for the default Swift backup driver. This is the size in +bytes that changes are tracked for incremental backups. The existing +``backup_swift_object_size`` option, the size in bytes of Swift backup +objects, has to be a multiple of ``backup_swift_block_size``. The default +is 32768 for ``backup_swift_block_size``, and the default is 52428800 for +``backup_swift_object_size``. + +The configuration option ``backup_swift_enable_progress_timer`` in +``cinder.conf`` is used when backing up the volume to Object Storage +back end. This option enables or disables the timer. It is enabled by default +to send the periodic progress notifications to the Telemetry service. + +This command also returns a backup ID. Use this backup ID when restoring +the volume: + +.. code-block:: console + + $ openstack volume backup restore BACKUP_ID VOLUME_ID + +When restoring from a full backup, it is a full restore. + +When restoring from an incremental backup, a list of backups is built based +on the IDs of the parent backups. A full restore is performed based on the +full backup first, then restore is done based on the incremental backup, +laying on top of it in order. + +You can view a backup list with the :command:`openstack volume backup list` +command. Optional arguments to clarify the status of your backups +include: running ``--name``, ``--status``, and +``--volume`` to filter through backups by the specified name, +status, or volume-id. Search with ``--all-projects`` for details of the +projects associated with the listed backups. + +Because volume backups are dependent on the Block Storage database, you must +also back up your Block Storage database regularly to ensure data recovery. + +.. note:: + + Alternatively, you can export and save the metadata of selected volume + backups. Doing so precludes the need to back up the entire Block Storage + database. This is useful if you need only a small subset of volumes to + survive a catastrophic database failure. + + If you specify a UUID encryption key when setting up the volume + specifications, the backup metadata ensures that the key will remain valid + when you back up and restore the volume. + + For more information about how to export and import volume backup metadata, + see the section called :ref:`volume_backups_export_import`. + +By default, the swift object store is used for the backup repository. + +If instead you want to use an NFS export as the backup repository, add the +following configuration options to the ``[DEFAULT]`` section of the +``cinder.conf`` file and restart the Block Storage services: + +.. code-block:: ini + + backup_driver = cinder.backup.drivers.nfs + backup_share = HOST:EXPORT_PATH + +For the ``backup_share`` option, replace ``HOST`` with the DNS resolvable +host name or the IP address of the storage server for the NFS share, and +``EXPORT_PATH`` with the path to that share. If your environment requires +that non-default mount options be specified for the share, set these as +follows: + +.. code-block:: ini + + backup_mount_options = MOUNT_OPTIONS + +``MOUNT_OPTIONS`` is a comma-separated string of NFS mount options as detailed +in the NFS man page. + +There are several other options whose default values may be overridden as +appropriate for your environment: + +.. code-block:: ini + + backup_compression_algorithm = zlib + backup_sha_block_size_bytes = 32768 + backup_file_size = 1999994880 + +The option ``backup_compression_algorithm`` can be set to ``bz2`` or ``None``. +The latter can be a useful setting when the server providing the share for the +backup repository itself performs deduplication or compression on the backup +data. + +The option ``backup_file_size`` must be a multiple of +``backup_sha_block_size_bytes``. It is effectively the maximum file size to be +used, given your environment, to hold backup data. Volumes larger than this +will be stored in multiple files in the backup repository. The +``backup_sha_block_size_bytes`` option determines the size of blocks from the +cinder volume being backed up on which digital signatures are calculated in +order to enable incremental backup capability. + +You also have the option of resetting the state of a backup. When creating or +restoring a backup, sometimes it may get stuck in the creating or restoring +states due to problems like the database or rabbitmq being down. In situations +like these resetting the state of the backup can restore it to a functional +status. + +Run this command to restore the state of a backup: + +.. code-block:: console + + $ cinder backup-reset-state [--state STATE] BACKUP_ID-1 BACKUP_ID-2 ... + +Run this command to create a backup of a snapshot: + +.. code-block:: console + + $ openstack volume backup create [--incremental] [--force] \ + [--snapshot SNAPSHOT_ID] VOLUME + +Where ``VOLUME`` is the name or ID of the volume, ``SNAPSHOT_ID`` is the ID of +the volume's snapshot. diff --git a/doc/source/admin/blockstorage-volume-migration.rst b/doc/source/admin/blockstorage-volume-migration.rst new file mode 100644 index 00000000000..265faed92e5 --- /dev/null +++ b/doc/source/admin/blockstorage-volume-migration.rst @@ -0,0 +1,208 @@ +.. _volume_migration.rst: + +=============== +Migrate volumes +=============== + +OpenStack has the ability to migrate volumes between back ends which support +its volume-type. Migrating a volume transparently moves its data from the +current back end for the volume to a new one. This is an administrator +function, and can be used for functions including storage evacuation (for +maintenance or decommissioning), or manual optimizations (for example, +performance, reliability, or cost). + +These workflows are possible for a migration: + +#. If the storage can migrate the volume on its own, it is given the + opportunity to do so. This allows the Block Storage driver to enable + optimizations that the storage might be able to perform. If the back end + is not able to perform the migration, the Block Storage uses one of two + generic flows, as follows. + +#. If the volume is not attached, the Block Storage service creates a volume + and copies the data from the original to the new volume. + + .. note:: + + While most back ends support this function, not all do. See the `driver + documentation `__ + in the OpenStack Configuration Reference for more details. + +#. If the volume is attached to a VM instance, the Block Storage creates a + volume, and calls Compute to copy the data from the original to the new + volume. Currently this is supported only by the Compute libvirt driver. + +As an example, this scenario shows two LVM back ends and migrates an attached +volume from one to the other. This scenario uses the third migration flow. + +First, list the available back ends: + +.. code-block:: console + + # cinder get-pools + +----------+----------------------------------------------------+ + | Property | Value | + +----------+----------------------------------------------------+ + | name | server1@lvmstorage-1#lvmstorage-1 | + +----------+----------------------------------------------------+ + +----------+----------------------------------------------------+ + | Property | Value | + +----------+----------------------------------------------------+ + | name | server2@lvmstorage-2#lvmstorage-2 | + +----------+----------------------------------------------------+ + +.. note:: + + Only Block Storage V2 API supports :command:`cinder get-pools`. + +You can also get available back ends like following: + +.. code-block:: console + + # cinder-manage host list + server1@lvmstorage-1 zone1 + server2@lvmstorage-2 zone1 + +But it needs to add pool name in the end. For example, +``server1@lvmstorage-1#zone1``. + +Next, as the admin user, you can see the current status of the volume +(replace the example ID with your own): + +.. code-block:: console + + $ openstack volume show 6088f80a-f116-4331-ad48-9afb0dfb196c + + +--------------------------------+--------------------------------------+ + | Field | Value | + +--------------------------------+--------------------------------------+ + | attachments | [] | + | availability_zone | zone1 | + | bootable | false | + | consistencygroup_id | None | + | created_at | 2013-09-01T14:53:22.000000 | + | description | test | + | encrypted | False | + | id | 6088f80a-f116-4331-ad48-9afb0dfb196c | + | migration_status | None | + | multiattach | False | + | name | test | + | os-vol-host-attr:host | server1@lvmstorage-1#lvmstorage-1 | + | os-vol-mig-status-attr:migstat | None | + | os-vol-mig-status-attr:name_id | None | + | os-vol-tenant-attr:tenant_id | d88310717a8e4ebcae84ed075f82c51e | + | properties | readonly='False' | + | replication_status | disabled | + | size | 1 | + | snapshot_id | None | + | source_volid | None | + | status | in-use | + | type | None | + | updated_at | 2016-07-31T07:22:19.000000 | + | user_id | d8e5e5727f3a4ce1886ac8ecec058e83 | + +--------------------------------+--------------------------------------+ + +Note these attributes: + +* ``os-vol-host-attr:host`` - the volume's current back end. +* ``os-vol-mig-status-attr:migstat`` - the status of this volume's migration + (None means that a migration is not currently in progress). +* ``os-vol-mig-status-attr:name_id`` - the volume ID that this volume's name + on the back end is based on. Before a volume is ever migrated, its name on + the back end storage may be based on the volume's ID (see the + ``volume_name_template`` configuration parameter). For example, if + ``volume_name_template`` is kept as the default value (``volume-%s``), your + first LVM back end has a logical volume named + ``volume-6088f80a-f116-4331-ad48-9afb0dfb196c``. During the course of a + migration, if you create a volume and copy over the data, the volume get + the new name but keeps its original ID. This is exposed by the ``name_id`` + attribute. + + .. note:: + + If you plan to decommission a block storage node, you must stop the + ``cinder`` volume service on the node after performing the migration. + + On nodes that run CentOS, Fedora, openSUSE, Red Hat Enterprise Linux, + or SUSE Linux Enterprise, run: + + .. code-block:: console + + # service openstack-cinder-volume stop + # chkconfig openstack-cinder-volume off + + On nodes that run Ubuntu or Debian, run: + + .. code-block:: console + + # service cinder-volume stop + # chkconfig cinder-volume off + + Stopping the cinder volume service will prevent volumes from being + allocated to the node. + +Migrate this volume to the second LVM back end: + +.. code-block:: console + + $ cinder migrate 6088f80a-f116-4331-ad48-9afb0dfb196c \ + server2@lvmstorage-2#lvmstorage-2 + + Request to migrate volume 6088f80a-f116-4331-ad48-9afb0dfb196c has been + accepted. + +You can use the :command:`openstack volume show` command to see the status of +the migration. While migrating, the ``migstat`` attribute shows states such as +``migrating`` or ``completing``. On error, ``migstat`` is set to None and the +host attribute shows the original ``host``. On success, in this example, the +output looks like: + +.. code-block:: console + + $ openstack volume show 6088f80a-f116-4331-ad48-9afb0dfb196c + + +--------------------------------+--------------------------------------+ + | Field | Value | + +--------------------------------+--------------------------------------+ + | attachments | [] | + | availability_zone | zone1 | + | bootable | false | + | consistencygroup_id | None | + | created_at | 2013-09-01T14:53:22.000000 | + | description | test | + | encrypted | False | + | id | 6088f80a-f116-4331-ad48-9afb0dfb196c | + | migration_status | None | + | multiattach | False | + | name | test | + | os-vol-host-attr:host | server2@lvmstorage-2#lvmstorage-2 | + | os-vol-mig-status-attr:migstat | completing | + | os-vol-mig-status-attr:name_id | None | + | os-vol-tenant-attr:tenant_id | d88310717a8e4ebcae84ed075f82c51e | + | properties | readonly='False' | + | replication_status | disabled | + | size | 1 | + | snapshot_id | None | + | source_volid | None | + | status | in-use | + | type | None | + | updated_at | 2017-02-22T02:35:03.000000 | + | user_id | d8e5e5727f3a4ce1886ac8ecec058e83 | + +--------------------------------+--------------------------------------+ + +Note that ``migstat`` is None, host is the new host, and ``name_id`` holds the +ID of the volume created by the migration. If you look at the second LVM back +end, you find the logical volume +``volume-133d1f56-9ffc-4f57-8798-d5217d851862``. + +.. note:: + + The migration is not visible to non-admin users (for example, through the + volume ``status``). However, some operations are not allowed while a + migration is taking place, such as attaching/detaching a volume and + deleting a volume. If a user performs such an action during a migration, + an error is returned. + +.. note:: + + Migrating volumes that have snapshots are currently not allowed. diff --git a/doc/source/admin/blockstorage-volume-number-weigher.rst b/doc/source/admin/blockstorage-volume-number-weigher.rst new file mode 100644 index 00000000000..e0934b45e96 --- /dev/null +++ b/doc/source/admin/blockstorage-volume-number-weigher.rst @@ -0,0 +1,88 @@ +.. _volume_number_weigher: + +======================================= +Configure and use volume number weigher +======================================= + +OpenStack Block Storage enables you to choose a volume back end according +to ``free_capacity`` and ``allocated_capacity``. The volume number weigher +feature lets the scheduler choose a volume back end based on its volume +number in the volume back end. This can provide another means to improve +the volume back ends' I/O balance and the volumes' I/O performance. + +Enable volume number weigher +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable a volume number weigher, set the +``scheduler_default_weighers`` to ``VolumeNumberWeigher`` flag in the +``cinder.conf`` file to define ``VolumeNumberWeigher`` +as the selected weigher. + +Configure multiple-storage back ends +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure ``VolumeNumberWeigher``, use ``LVMVolumeDriver`` +as the volume driver. + +This configuration defines two LVM volume groups: ``stack-volumes`` with +10 GB capacity and ``stack-volumes-1`` with 60 GB capacity. +This example configuration defines two back ends: + +.. code-block:: ini + + scheduler_default_weighers=VolumeNumberWeigher + enabled_backends=lvmdriver-1,lvmdriver-2 + [lvmdriver-1] + volume_group=stack-volumes + volume_driver=cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name=LVM + + [lvmdriver-2] + volume_group=stack-volumes-1 + volume_driver=cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name=LVM + +Volume type +~~~~~~~~~~~ + +Define a volume type in Block Storage: + +.. code-block:: console + + $ openstack volume type create lvm + +Create an extra specification that links the volume type to a back-end name: + +.. code-block:: console + + $ openstack volume type set lvm --property volume_backend_name=LVM + +This example creates a lvm volume type with +``volume_backend_name=LVM`` as extra specifications. + +Usage +~~~~~ + +To create six 1-GB volumes, run the +:command:`openstack volume create --size 1 --type lvm volume1` command +six times: + +.. code-block:: console + + $ openstack volume create --size 1 --type lvm volume1 + +This command creates three volumes in ``stack-volumes`` and +three volumes in ``stack-volumes-1``. + +List the available volumes: + +.. code-block:: console + + # lvs + LV VG Attr LSize Pool Origin Data% Move Log Copy% Convert + volume-3814f055-5294-4796-b5e6-1b7816806e5d stack-volumes -wi-a---- 1.00g + volume-72cf5e79-99d2-4d23-b84e-1c35d3a293be stack-volumes -wi-a---- 1.00g + volume-96832554-0273-4e9d-902b-ad421dfb39d1 stack-volumes -wi-a---- 1.00g + volume-169386ef-3d3e-4a90-8439-58ceb46889d9 stack-volumes-1 -wi-a---- 1.00g + volume-460b0bbb-d8a0-4bc3-9882-a129a5fe8652 stack-volumes-1 -wi-a---- 1.00g + volume-9a08413b-0dbc-47c9-afb8-41032ab05a41 stack-volumes-1 -wi-a---- 1.00g diff --git a/doc/source/admin/blockstorage.rst b/doc/source/admin/blockstorage.rst new file mode 100644 index 00000000000..ac577454c25 --- /dev/null +++ b/doc/source/admin/blockstorage.rst @@ -0,0 +1,32 @@ +.. _block_storage: + +============= +Block Storage +============= + +The OpenStack Block Storage service works through the interaction of +a series of daemon processes named ``cinder-*`` that reside +persistently on the host machine or machines. You can run all the +binaries from a single node, or spread across multiple nodes. You can +also run them on the same node as other OpenStack services. + +To administer the OpenStack Block Storage service, it is helpful to +understand a number of concepts. You must make certain choices when +you configure the Block Storage service in OpenStack. The bulk of the +options come down to two choices - single node or multi-node install. +You can read a longer discussion about `Storage Decisions`_ in the +`OpenStack Operations Guide`_. + +OpenStack Block Storage enables you to add extra block-level storage +to your OpenStack Compute instances. This service is similar to the +Amazon EC2 Elastic Block Storage (EBS) offering. + +.. toctree:: + :maxdepth: 1 + + blockstorage-api-throughput.rst + blockstorage-manage-volumes.rst + blockstorage-troubleshoot.rst + +.. _`Storage Decisions`: https://docs.openstack.org/ops-guide/arch-storage.html +.. _`OpenStack Operations Guide`: https://docs.openstack.org/ops-guide/ diff --git a/doc/source/admin/ts-HTTP-bad-req-in-cinder-vol-log.rst b/doc/source/admin/ts-HTTP-bad-req-in-cinder-vol-log.rst new file mode 100644 index 00000000000..454b74da890 --- /dev/null +++ b/doc/source/admin/ts-HTTP-bad-req-in-cinder-vol-log.rst @@ -0,0 +1,46 @@ +===================================== +HTTP bad request in cinder volume log +===================================== + +Problem +~~~~~~~ + +These errors appear in the ``cinder-volume.log`` file: + +.. code-block:: console + + 2013-05-03 15:16:33 INFO [cinder.volume.manager] Updating volume status + 2013-05-03 15:16:33 DEBUG [hp3parclient.http] + REQ: curl -i https://10.10.22.241:8080/api/v1/cpgs -X GET -H "X-Hp3Par-Wsapi-Sessionkey: 48dc-b69ed2e5 + f259c58e26df9a4c85df110c-8d1e8451" -H "Accept: application/json" -H "User-Agent: python-3parclient" + + 2013-05-03 15:16:33 DEBUG [hp3parclient.http] RESP:{'content-length': 311, 'content-type': 'text/plain', + 'status': '400'} + + 2013-05-03 15:16:33 DEBUG [hp3parclient.http] RESP BODY:Second simultaneous read on fileno 13 detected. + Unless you really know what you're doing, make sure that only one greenthread can read any particular socket. + Consider using a pools.Pool. If you do know what you're doing and want to disable this error, + call eventlet.debug.hub_multiple_reader_prevention(False) + + 2013-05-03 15:16:33 ERROR [cinder.manager] Error during VolumeManager._report_driver_status: Bad request (HTTP 400) + Traceback (most recent call last): + File "/usr/lib/python2.7/dist-packages/cinder/manager.py", line 167, in periodic_tasks task(self, context) + File "/usr/lib/python2.7/dist-packages/cinder/volume/manager.py", line 690, in _report_driver_status volume_stats = + self.driver.get_volume_stats(refresh=True) + File "/usr/lib/python2.7/dist-packages/cinder/volume/drivers/san/hp/hp_3par_fc.py", line 77, in get_volume_stats stats = + self.common.get_volume_stats(refresh, self.client) + File "/usr/lib/python2.7/dist-packages/cinder/volume/drivers/san/hp/hp_3par_common.py", line 421, in get_volume_stats cpg = + client.getCPG(self.config.hp3par_cpg) + File "/usr/lib/python2.7/dist-packages/hp3parclient/client.py", line 231, in getCPG cpgs = self.getCPGs() + File "/usr/lib/python2.7/dist-packages/hp3parclient/client.py", line 217, in getCPGs response, body = self.http.get('/cpgs') + File "/usr/lib/python2.7/dist-packages/hp3parclient/http.py", line 255, in get return self._cs_request(url, 'GET', **kwargs) + File "/usr/lib/python2.7/dist-packages/hp3parclient/http.py", line 224, in _cs_request **kwargs) + File "/usr/lib/python2.7/dist-packages/hp3parclient/http.py", line 198, in _time_request resp, body = self.request(url, method, **kwargs) + File "/usr/lib/python2.7/dist-packages/hp3parclient/http.py", line 192, in request raise exceptions.from_response(resp, body) + HTTPBadRequest: Bad request (HTTP 400) + +Solution +~~~~~~~~ + +You need to update your copy of the ``hp_3par_fc.py`` driver which +contains the synchronization code. diff --git a/doc/source/admin/ts-cinder-config.rst b/doc/source/admin/ts-cinder-config.rst new file mode 100644 index 00000000000..502e5c61e75 --- /dev/null +++ b/doc/source/admin/ts-cinder-config.rst @@ -0,0 +1,200 @@ +============================================ +Troubleshoot the Block Storage configuration +============================================ + +Most Block Storage errors are caused by incorrect volume configurations +that result in volume creation failures. To resolve these failures, +review these logs: + +- ``cinder-api`` log (``/var/log/cinder/api.log``) + +- ``cinder-volume`` log (``/var/log/cinder/volume.log``) + +The ``cinder-api`` log is useful for determining if you have endpoint or +connectivity issues. If you send a request to create a volume and it +fails, review the ``cinder-api`` log to determine whether the request made +it to the Block Storage service. If the request is logged and you see no +errors or tracebacks, check the ``cinder-volume`` log for errors or +tracebacks. + +.. note:: + + Create commands are listed in the ``cinder-api`` log. + +These entries in the ``cinder.openstack.common.log`` file can be used to +assist in troubleshooting your Block Storage configuration. + +.. code-block:: console + + # Print debugging output (set logging level to DEBUG instead + # of default WARNING level). (boolean value) + # debug=false + + # Log output to standard error (boolean value) + # use_stderr=true + + # Default file mode used when creating log files (string + # value) + # logfile_mode=0644 + + # format string to use for log messages with context (string + # value) + # logging_context_format_string=%(asctime)s.%(msecs)03d %(levelname)s + # %(name)s [%(request_id)s %(user)s %(tenant)s] %(instance)s%(message)s + + # format string to use for log mes #logging_default_format_string=%(asctime)s. + # %(msecs)03d %(process)d %(levelname)s %(name)s [-] %(instance)s%(message)s + + # data to append to log format when level is DEBUG (string + # value) + # logging_debug_format_suffix=%(funcName)s %(pathname)s:%(lineno)d + + # prefix each line of exception output with this format + # (string value) + # logging_exception_prefix=%(asctime)s.%(msecs)03d %(process)d TRACE %(name)s + # %(instance)s + + # list of logger=LEVEL pairs (list value) + # default_log_levels=amqplib=WARN,sqlalchemy=WARN,boto=WARN,suds=INFO, + # keystone=INFO,eventlet.wsgi.server=WARNsages without context + # (string value) + + # If an instance is passed with the log message, format it + # like this (string value) + # instance_format="[instance: %(uuid)s]" + + # If an instance UUID is passed with the log message, format + # it like this (string value) + #instance_uuid_format="[instance: %(uuid)s] " + + # Format string for %%(asctime)s in log records. Default: + # %(default)s (string value) + # log_date_format=%Y-%m-%d %H:%M:%S + + # (Optional) Name of log file to output to. If not set, + # logging will go to stdout. (string value) + # log_file= + + # (Optional) The directory to keep log files in (will be + # prepended to --log-file) (string value) + # log_dir= + # instance_uuid_format="[instance: %(uuid)s]" + + # If this option is specified, the logging configuration file + # specified is used and overrides any other logging options + # specified. Please see the Python logging module + # documentation for details on logging configuration files. + # (string value) + # Use syslog for logging. (boolean value) + # use_syslog=false + + # syslog facility to receive log lines (string value) + # syslog_log_facility=LOG_USER + # log_config= + +These common issues might occur during configuration, and the following +potential solutions describe how to address the issues. + +Issues with ``state_path`` and ``volumes_dir`` settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +The OpenStack Block Storage uses ``tgtd`` as the default iSCSI helper +and implements persistent targets. This means that in the case of a +``tgt`` restart, or even a node reboot, your existing volumes on that +node will be restored automatically with their original :term:`IQN `. + +By default, Block Storage uses a ``state_path`` variable, which if +installing with Yum or APT should be set to ``/var/lib/cinder/``. +The next part is the ``volumes_dir`` variable, by default this appends +a ``volumes`` directory to the ``state_path``. The result is a +file-tree: ``/var/lib/cinder/volumes/``. + +Solution +-------- + +In order to ensure nodes are restored to their original IQN, +the iSCSI target information needs to be stored in a file on creation +that can be queried in case of restart of the ``tgt daemon``. While the +installer should handle all this, it can go wrong. + +If you have trouble creating volumes and this directory does not exist +you should see an error message in the ``cinder-volume`` log indicating +that the ``volumes_dir`` does not exist, and it should provide +information about which path it was looking for. + +The persistent tgt include file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +The Block Storage service may have issues locating the persistent +``tgt include`` file. Along with the ``volumes_dir`` option, the +iSCSI target driver also needs to be configured to look in the correct +place for the persistent ``tgt include `` file. This is an entry +in the ``/etc/tgt/conf.d`` file that should have been set during the +OpenStack installation. + +Solution +-------- + +If issues occur, verify that you have a ``/etc/tgt/conf.d/cinder.conf`` +file. If the file is not present, create it with: + +.. code-block:: console + + # echo 'include /var/lib/cinder/volumes/ *' >> /etc/tgt/conf.d/cinder.conf + +No sign of attach call in the ``cinder-api`` log +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +The attach call is unavailable, or not appearing in the ``cinder-api`` log. + +Solution +-------- + +Adjust the ``nova.conf`` file, and make sure that your ``nova.conf`` +has this entry: + +.. code-block:: ini + + volume_api_class=nova.volume.cinder.API + +Failed to create iscsi target error in the ``cinder-volume.log`` file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Problem +------- + +.. code-block:: console + + 2013-03-12 01:35:43 1248 TRACE cinder.openstack.common.rpc.amqp \ + ISCSITargetCreateFailed: \ + Failed to create iscsi target for volume \ + volume-137641b2-af72-4a2f-b243-65fdccd38780. + +You might see this error in ``cinder-volume.log`` after trying to +create a volume that is 1 GB. + +Solution +-------- + +To fix this issue, change the content of the ``/etc/tgt/targets.conf`` +file from ``include /etc/tgt/conf.d/*.conf`` to +``include /etc/tgt/conf.d/cinder_tgt.conf``, as follows: + +.. code-block:: shell + + include /etc/tgt/conf.d/cinder_tgt.conf + include /etc/tgt/conf.d/cinder.conf + default-driver iscsi + +Restart ``tgt`` and ``cinder-*`` services, so they pick up the new +configuration. diff --git a/doc/source/admin/ts-duplicate-3par-host.rst b/doc/source/admin/ts-duplicate-3par-host.rst new file mode 100644 index 00000000000..8ff1af3e876 --- /dev/null +++ b/doc/source/admin/ts-duplicate-3par-host.rst @@ -0,0 +1,27 @@ +=================== +Duplicate 3PAR host +=================== + +Problem +~~~~~~~ + +This error may be caused by a volume being exported outside of OpenStack +using a host name different from the system name that OpenStack expects. +This error could be displayed with the :term:`IQN ` if the host was exported using iSCSI: + +.. code-block:: console + + Duplicate3PARHost: 3PAR Host already exists: Host wwn 50014380242B9750 \ + already used by host cld4b5ubuntuW(id = 68. The hostname must be called\ + 'cld4b5ubuntu'. + +Solution +~~~~~~~~ + +Change the 3PAR host name to match the one that OpenStack expects. The +3PAR host constructed by the driver uses just the local host name, not +the fully qualified domain name (FQDN) of the compute host. For example, +if the FQDN was *myhost.example.com*, just *myhost* would be used as the +3PAR host name. IP addresses are not allowed as host names on the 3PAR +storage server. diff --git a/doc/source/admin/ts-eql-volume-size.rst b/doc/source/admin/ts-eql-volume-size.rst new file mode 100644 index 00000000000..f0eb7987d19 --- /dev/null +++ b/doc/source/admin/ts-eql-volume-size.rst @@ -0,0 +1,223 @@ +======================================================================== +Addressing discrepancies in reported volume sizes for EqualLogic storage +======================================================================== + +Problem +~~~~~~~ + +There is a discrepancy between both the actual volume size in EqualLogic +(EQL) storage and the image size in the Image service, with what is +reported to OpenStack database. This could lead to confusion +if a user is creating volumes from an image that was uploaded from an EQL +volume (through the Image service). The image size is slightly larger +than the target volume size; this is because EQL size reporting accounts +for additional storage used by EQL for internal volume metadata. + +To reproduce the issue follow the steps in the following procedure. + +This procedure assumes that the EQL array is provisioned, and that +appropriate configuration settings have been included in +``/etc/cinder/cinder.conf`` to connect to the EQL array. + +Create a new volume. Note the ID and size of the volume. In the +following example, the ID and size are +``74cf9c04-4543-47ae-a937-a9b7c6c921e7`` and ``1``, respectively: + +.. code-block:: console + + $ openstack volume create volume1 --size 1 + + +---------------------+--------------------------------------+ + | Field | Value | + +---------------------+--------------------------------------+ + | attachments | [] | + | availability_zone | nova | + | bootable | false | + | consistencygroup_id | None | + | created_at | 2016-12-06T11:33:30.957318 | + | description | None | + | encrypted | False | + | id | 74cf9c04-4543-47ae-a937-a9b7c6c921e7 | + | migration_status | None | + | multiattach | False | + | name | volume1 | + | properties | | + | replication_status | disabled | + | size | 1 | + | snapshot_id | None | + | source_volid | None | + | status | creating | + | type | iscsi | + | updated_at | None | + | user_id | c36cec73b0e44876a4478b1e6cd749bb | + +---------------------+--------------------------------------+ + +Verify the volume size on the EQL array by using its command-line +interface. + +The actual size (``VolReserve``) is 1.01 GB. The EQL Group Manager +should also report a volume size of 1.01 GB: + +.. code-block:: console + + eql> volume select volume-74cf9c04-4543-47ae-a937-a9b7c6c921e7 + eql (volume_volume-74cf9c04-4543-47ae-a937-a9b7c6c921e7)> show + _______________________________ Volume Information ________________________________ + Name: volume-74cf9c04-4543-47ae-a937-a9b7c6c921e7 + Size: 1GB + VolReserve: 1.01GB + VolReservelnUse: 0MB + ReplReservelnUse: 0MB + iSCSI Alias: volume-74cf9c04-4543-47ae-a937-a9b7c6c921e7 + iSCSI Name: iqn.2001-05.com.equallogic:0-8a0906-19f91850c-067000000b4532cl-volume-74cf9c04-4543-47ae-a937-a9b7c6c921e7 + ActualMembers: 1 + Snap-Warn: 10% + Snap-Depletion: delete-oldest + Description: + Snap-Reserve: 100% + Snap-Reserve-Avail: 100% (1.01GB) + Permission: read-write + DesiredStatus: online + Status: online + Connections: O + Snapshots: O + Bind: + Type: not-replicated + ReplicationReserveSpace: 0MB + +Create a new image from this volume: + +.. code-block:: console + + $ openstack image create --volume volume1 \ + --disk-format raw --container-format bare image_from_volume1 + + +---------------------+--------------------------------------+ + | Field | Value | + +---------------------+--------------------------------------+ + | container_format | bare | + | disk_format | raw | + | display_description | None | + | id | 850fd393-a968-4259-9c65-6b495cba5209 | + | image_id | 3020a21d-ba37-4495-8899-07fc201161b9 | + | image_name | image_from_volume1 | + | is_public | False | + | protected | False | + | size | 1 | + | status | uploading | + | updated_at | 2016-12-05T12:43:56.000000 | + | volume_type | iscsi | + +---------------------+--------------------------------------+ + +When you uploaded the volume in the previous step, the Image service +reported the volume's size as ``1`` (GB). However, when using +:command:`openstack image show` to show the image, the displayed size is +1085276160 bytes, or roughly 1.01 GB: + ++------------------+--------------------------------------+ +| Property | Value | ++------------------+--------------------------------------+ +| checksum | cd573cfaace07e7949bc0c46028904ff | +| container_format | bare | +| created_at | 2016-12-06T11:39:06Z | +| disk_format | raw | +| id | 3020a21d-ba37-4495-8899-07fc201161b9 | +| min_disk | 0 | +| min_ram | 0 | +| name | image_from_volume1 | +| owner | 5669caad86a04256994cdf755df4d3c1 | +| protected | False | +| size | 1085276160 | +| status | active | +| tags | [] | +| updated_at | 2016-12-06T11:39:24Z | +| virtual_size | None | +| visibility | private | ++------------------+--------------------------------------+ + + + +Create a new volume using the previous image (``image_id 3020a21d-ba37-4495 +-8899-07fc201161b9`` in this example) as +the source. Set the target volume size to 1 GB; this is the size +reported by the ``cinder`` tool when you uploaded the volume to the +Image service: + +.. code-block:: console + + $ openstack volume create volume2 --size 1 --image 3020a21d-ba37-4495-8899-07fc201161b9 + ERROR: Invalid input received: Size of specified image 2 is larger + than volume size 1. (HTTP 400) (Request-ID: req-4b9369c0-dec5-4e16-a114-c0cdl6bSd210) + +The attempt to create a new volume based on the size reported by the +``cinder`` tool will then fail. + +Solution +~~~~~~~~ + +To work around this problem, increase the target size of the new image +to the next whole number. In the problem example, you created a 1 GB +volume to be used as volume-backed image, so a new volume using this +volume-backed image should use a size of 2 GB: + +.. code-block:: console + + $ openstack volume create volume2 --size 1 --image 3020a21d-ba37-4495-8899-07fc201161b9 + +---------------------+--------------------------------------+ + | Field | Value | + +---------------------+--------------------------------------+ + | attachments | [] | + | availability_zone | nova | + | bootable | false | + | consistencygroup_id | None | + | created_at | 2016-12-06T11:49:06.031768 | + | description | None | + | encrypted | False | + | id | a70d6305-f861-4382-84d8-c43128be0013 | + | migration_status | None | + | multiattach | False | + | name | volume2 | + | properties | | + | replication_status | disabled | + | size | 1 | + | snapshot_id | None | + | source_volid | None | + | status | creating | + | type | iscsi | + | updated_at | None | + | user_id | c36cec73b0e44876a4478b1e6cd749bb | + +---------------------+--------------------------------------+ + +.. note:: + + The dashboard suggests a suitable size when you create a new volume + based on a volume-backed image. + +You can then check this new volume into the EQL array: + +.. code-block:: console + + eql> volume select volume-64e8eb18-d23f-437b-bcac-b352afa6843a + eql (volume_volume-61e8eb18-d23f-437b-bcac-b352afa6843a)> show + ______________________________ Volume Information _______________________________ + Name: volume-64e8eb18-d23f-437b-bcac-b352afa6843a + Size: 2GB + VolReserve: 2.01GB + VolReserveInUse: 1.01GB + ReplReserveInUse: 0MB + iSCSI Alias: volume-64e8eb18-d23f-437b-bcac-b352afa6843a + iSCSI Name: iqn.2001-05.com.equallogic:0-8a0906-e3091850e-eae000000b7S32cl-volume-64e8eb18-d23f-437b-bcac-b3S2afa6Bl3a + ActualMembers: 1 + Snap-Warn: 10% + Snap-Depletion: delete-oldest + Description: + Snap-Reserve: 100% + Snap-Reserve-Avail: 100% (2GB) + Permission: read-write + DesiredStatus: online + Status: online + Connections: 1 + Snapshots: O + Bind: + Type: not-replicated + ReplicationReserveSpace: 0MB diff --git a/doc/source/admin/ts-failed-attach-vol-after-detach.rst b/doc/source/admin/ts-failed-attach-vol-after-detach.rst new file mode 100644 index 00000000000..6ed58960cf5 --- /dev/null +++ b/doc/source/admin/ts-failed-attach-vol-after-detach.rst @@ -0,0 +1,35 @@ +======================================= +Failed to attach volume after detaching +======================================= + +Problem +~~~~~~~ + +Failed to attach a volume after detaching the same volume. + +Solution +~~~~~~~~ + +You must change the device name on the :command:`nova-attach` command. The VM +might not clean up after a :command:`nova-detach` command runs. This example +shows how the :command:`nova-attach` command fails when you use the ``vdb``, +``vdc``, or ``vdd`` device names: + +.. code-block:: console + + # ls -al /dev/disk/by-path/ + total 0 + drwxr-xr-x 2 root root 200 2012-08-29 17:33 . + drwxr-xr-x 5 root root 100 2012-08-29 17:33 .. + lrwxrwxrwx 1 root root 9 2012-08-29 17:33 pci-0000:00:04.0-virtio-pci-virtio0 -> ../../vda + lrwxrwxrwx 1 root root 10 2012-08-29 17:33 pci-0000:00:04.0-virtio-pci-virtio0-part1 -> ../../vda1 + lrwxrwxrwx 1 root root 10 2012-08-29 17:33 pci-0000:00:04.0-virtio-pci-virtio0-part2 -> ../../vda2 + lrwxrwxrwx 1 root root 10 2012-08-29 17:33 pci-0000:00:04.0-virtio-pci-virtio0-part5 -> ../../vda5 + lrwxrwxrwx 1 root root 9 2012-08-29 17:33 pci-0000:00:06.0-virtio-pci-virtio2 -> ../../vdb + lrwxrwxrwx 1 root root 9 2012-08-29 17:33 pci-0000:00:08.0-virtio-pci-virtio3 -> ../../vdc + lrwxrwxrwx 1 root root 9 2012-08-29 17:33 pci-0000:00:09.0-virtio-pci-virtio4 -> ../../vdd + lrwxrwxrwx 1 root root 10 2012-08-29 17:33 pci-0000:00:09.0-virtio-pci-virtio4-part1 -> ../../vdd1 + +You might also have this problem after attaching and detaching the same +volume from the same VM with the same mount point multiple times. In +this case, restart the KVM host. diff --git a/doc/source/admin/ts-failed-attach-vol-no-sysfsutils.rst b/doc/source/admin/ts-failed-attach-vol-no-sysfsutils.rst new file mode 100644 index 00000000000..1f9354f0839 --- /dev/null +++ b/doc/source/admin/ts-failed-attach-vol-no-sysfsutils.rst @@ -0,0 +1,30 @@ +================================================= +Failed to attach volume, systool is not installed +================================================= + +Problem +~~~~~~~ + +This warning and error occurs if you do not have the required +``sysfsutils`` package installed on the compute node: + +.. code-block:: console + + WARNING nova.virt.libvirt.utils [req-1200f887-c82b-4e7c-a891-fac2e3735dbb\ + admin admin|req-1200f887-c82b-4e7c-a891-fac2e3735dbb admin admin] systool\ + is not installed + ERROR nova.compute.manager [req-1200f887-c82b-4e7c-a891-fac2e3735dbb admin\ + admin|req-1200f887-c82b-4e7c-a891-fac2e3735dbb admin admin] + [instance: df834b5a-8c3f-477a-be9b-47c97626555c|instance: df834b5a-8c3f-47\ + 7a-be9b-47c97626555c] + Failed to attach volume 13d5c633-903a-4764-a5a0-3336945b1db1 at /dev/vdk. + +Solution +~~~~~~~~ + +Run the following command on the compute node to install the +``sysfsutils`` packages: + +.. code-block:: console + + # apt-get install sysfsutils diff --git a/doc/source/admin/ts-failed-connect-vol-FC-SAN.rst b/doc/source/admin/ts-failed-connect-vol-FC-SAN.rst new file mode 100644 index 00000000000..2ec994262bd --- /dev/null +++ b/doc/source/admin/ts-failed-connect-vol-FC-SAN.rst @@ -0,0 +1,29 @@ +================================== +Failed to connect volume in FC SAN +================================== + +Problem +~~~~~~~ + +The compute node failed to connect to a volume in a Fibre Channel (FC) SAN +configuration. The WWN may not be zoned correctly in your FC SAN that +links the compute host to the storage array: + +.. code-block:: console + + ERROR nova.compute.manager [req-2ddd5297-e405-44ab-aed3-152cd2cfb8c2 admin\ + demo|req-2ddd5297-e405-44ab-aed3-152cd2cfb8c2 admin demo] [instance: 60ebd\ + 6c7-c1e3-4bf0-8ef0-f07aa4c3d5f3|instance: 60ebd6c7-c1e3-4bf0-8ef0-f07aa4c3\ + d5f3] + Failed to connect to volume 6f6a6a9c-dfcf-4c8d-b1a8-4445ff883200 while\ + attaching at /dev/vdjTRACE nova.compute.manager [instance: 60ebd6c7-c1e3-4\ + bf0-8ef0-f07aa4c3d5f3|instance: 60ebd6c7-c1e3-4bf0-8ef0-f07aa4c3d5f3] + Traceback (most recent call last):…f07aa4c3d5f3\] ClientException: The\ + server has either erred or is incapable of performing the requested\ + operation.(HTTP 500)(Request-ID: req-71e5132b-21aa-46ee-b3cc-19b5b4ab2f00) + +Solution +~~~~~~~~ + +The network administrator must configure the FC SAN fabric by correctly +zoning the WWN (port names) from your compute node HBAs. diff --git a/doc/source/admin/ts-multipath-warn.rst b/doc/source/admin/ts-multipath-warn.rst new file mode 100644 index 00000000000..ca8a747d46c --- /dev/null +++ b/doc/source/admin/ts-multipath-warn.rst @@ -0,0 +1,30 @@ +========================== +Multipath call failed exit +========================== + +Problem +~~~~~~~ + +Multipath call failed exit. This warning occurs in the Compute log +if you do not have the optional ``multipath-tools`` package installed +on the compute node. This is an optional package and the volume +attachment does work without the multipath tools installed. +If the ``multipath-tools`` package is installed on the compute node, +it is used to perform the volume attachment. +The IDs in your message are unique to your system. + +.. code-block:: console + + WARNING nova.storage.linuxscsi [req-cac861e3-8b29-4143-8f1b-705d0084e571 + admin admin|req-cac861e3-8b29-4143-8f1b-705d0084e571 admin admin] + Multipath call failed exit (96) + +Solution +~~~~~~~~ + +Run the following command on the compute node to install the +``multipath-tools`` packages. + +.. code-block:: console + + # apt-get install multipath-tools diff --git a/doc/source/admin/ts-no-emulator-x86-64.rst b/doc/source/admin/ts-no-emulator-x86-64.rst new file mode 100644 index 00000000000..b45ae73dccd --- /dev/null +++ b/doc/source/admin/ts-no-emulator-x86-64.rst @@ -0,0 +1,19 @@ +========================================= +Cannot find suitable emulator for x86_64 +========================================= + +Problem +~~~~~~~ + +When you attempt to create a VM, the error shows the VM is in the +``BUILD`` then ``ERROR`` state. + +Solution +~~~~~~~~ + +On the KVM host, run :command:`cat /proc/cpuinfo`. Make sure the ``vmx`` or +``svm`` flags are set. + +Follow the instructions in the `Enable KVM +`__ section in the OpenStack Configuration Reference to enable hardware +virtualization support in your BIOS. diff --git a/doc/source/admin/ts-non-existent-host.rst b/doc/source/admin/ts-non-existent-host.rst new file mode 100644 index 00000000000..f25cdbd2ad9 --- /dev/null +++ b/doc/source/admin/ts-non-existent-host.rst @@ -0,0 +1,25 @@ +================= +Non-existent host +================= + +Problem +~~~~~~~ + +This error could be caused by a volume being exported outside of +OpenStack using a host name different from the system name that +OpenStack expects. This error could be displayed with the :term:`IQN ` if the host was exported using iSCSI. + +.. code-block:: console + + 2013-04-19 04:02:02.336 2814 ERROR cinder.openstack.common.rpc.common [-] Returning exception Not found (HTTP 404) + NON_EXISTENT_HOST - HOST '10' was not found to caller. + +Solution +~~~~~~~~ + +Host names constructed by the driver use just the local host name, not +the fully qualified domain name (FQDN) of the Compute host. For example, +if the FQDN was **myhost.example.com**, just **myhost** would be used as the +3PAR host name. IP addresses are not allowed as host names on the 3PAR +storage server. diff --git a/doc/source/admin/ts-non-existent-vlun.rst b/doc/source/admin/ts-non-existent-vlun.rst new file mode 100644 index 00000000000..f2d937792d8 --- /dev/null +++ b/doc/source/admin/ts-non-existent-vlun.rst @@ -0,0 +1,22 @@ +================= +Non-existent VLUN +================= + +Problem +~~~~~~~ + +This error occurs if the 3PAR host exists with the correct host name +that the OpenStack Block Storage drivers expect but the volume was +created in a different domain. + +.. code-block:: console + + HTTPNotFound: Not found (HTTP 404) NON_EXISTENT_VLUN - VLUN 'osv-DqT7CE3mSrWi4gZJmHAP-Q' was not found. + + +Solution +~~~~~~~~ + +The ``hpe3par_domain`` configuration items either need to be updated to +use the domain the 3PAR host currently resides in, or the 3PAR host +needs to be moved to the domain that the volume was created in. diff --git a/doc/source/admin/ts-vol-attach-miss-sg-scan.rst b/doc/source/admin/ts-vol-attach-miss-sg-scan.rst new file mode 100644 index 00000000000..e1d9a516b6d --- /dev/null +++ b/doc/source/admin/ts-vol-attach-miss-sg-scan.rst @@ -0,0 +1,28 @@ +======================================== +Failed to Attach Volume, Missing sg_scan +======================================== + +Problem +~~~~~~~ + +Failed to attach volume to an instance, ``sg_scan`` file not found. This +error occurs when the sg3-utils package is not installed on the compute node. +The IDs in your message are unique to your system: + +.. code-block:: console + + ERROR nova.compute.manager [req-cf2679fd-dd9e-4909-807f-48fe9bda3642 admin admin|req-cf2679fd-dd9e-4909-807f-48fe9bda3642 admin admin] + [instance: 7d7c92e0-49fa-4a8e-87c7-73f22a9585d5|instance: 7d7c92e0-49fa-4a8e-87c7-73f22a9585d5] + Failed to attach volume 4cc104c4-ac92-4bd6-9b95-c6686746414a at /dev/vdcTRACE nova.compute.manager + [instance: 7d7c92e0-49fa-4a8e-87c7-73f22a9585d5|instance: 7d7c92e0-49fa-4a8e-87c7-73f22a9585d5] + Stdout: '/usr/local/bin/nova-rootwrap: Executable not found: /usr/bin/sg_scan' + + +Solution +~~~~~~~~ + +Run this command on the compute node to install the ``sg3-utils`` package: + +.. code-block:: console + + # apt-get install sg3-utils diff --git a/doc/source/index.rst b/doc/source/index.rst index 0dd94dd049f..e8a77ea2df5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -42,6 +42,13 @@ Installing Cinder install/index +Admin Docs +========== +.. toctree:: + :maxdepth: 2 + + admin/blockstorage + Developer Docs ==============