diff --git a/doc/source/configuration/block-storage/drivers/windows-iscsi-volume-driver.rst b/doc/source/configuration/block-storage/drivers/windows-iscsi-volume-driver.rst index 144f23b378e..32b198a7565 100644 --- a/doc/source/configuration/block-storage/drivers/windows-iscsi-volume-driver.rst +++ b/doc/source/configuration/block-storage/drivers/windows-iscsi-volume-driver.rst @@ -1,240 +1,72 @@ +.. _windows_iscsi_volume_driver: + =========================== Windows iSCSI volume driver =========================== -Windows Server 2012 and Windows Storage Server 2012 offer an integrated iSCSI -Target service that can be used with OpenStack Block Storage in your stack. +Windows Server offers an integrated iSCSI Target service that can be used with +OpenStack Block Storage in your stack. + Being entirely a software solution, consider it in particular for mid-sized networks where the costs of a SAN might be excessive. The Windows iSCSI Block Storage driver works with OpenStack Compute on any -hypervisor. It includes snapshotting support and the ``boot from volume`` -feature. +hypervisor. This driver creates volumes backed by fixed-type VHD images on Windows Server -2012 and dynamic-type VHDX on Windows Server 2012 R2, stored locally on a -user-specified path. The system uses those images as iSCSI disks and exports -them through iSCSI targets. Each volume has its own iSCSI target. +2012 and dynamic-type VHDX on Windows Server 2012 R2 and onwards, stored +locally on a user-specified path. The system uses those images as iSCSI disks +and exports them through iSCSI targets. Each volume has its own iSCSI target. -This driver has been tested with Windows Server 2012 and Windows Server R2 -using the Server and Storage Server distributions. +The ``cinder-volume`` service as well as the required Python components will +be installed directly onto the Windows node. -Install the ``cinder-volume`` service as well as the required Python components -directly onto the Windows node. +Prerequisites +~~~~~~~~~~~~~ -You may install and configure ``cinder-volume`` and its dependencies manually -using the following guide or you may use the ``Cinder Volume Installer``, -presented below. - -Installing using the OpenStack cinder volume installer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In case you want to avoid all the manual setup, you can use Cloudbase -Solutions' installer. You can find it at -https://www.cloudbase.it/downloads/CinderVolumeSetup_Beta.msi. It installs an -independent Python environment, in order to avoid conflicts with existing -applications, dynamically generates a ``cinder.conf`` file based on the -parameters provided by you. - -``cinder-volume`` will be configured to run as a Windows Service, which can -be restarted using: - -.. code-block:: console - - PS C:\> net stop cinder-volume ; net start cinder-volume - -The installer can also be used in unattended mode. More details about how to -use the installer and its features can be found at https://www.cloudbase.it. - -Windows Server configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The required service in order to run ``cinder-volume`` on Windows is -``wintarget``. This will require the iSCSI Target Server Windows feature -to be installed. You can install it by running the following command: - -.. code-block:: console - - PS C:\> Add-WindowsFeature - FS-iSCSITarget-ServerAdd-WindowsFeatureFS-iSCSITarget-Server +The Windows iSCSI volume driver depends on the ``wintarget`` Windows service. +This will require the ``iSCSI Target Server`` Windows feature to be installed. .. note:: + The Cinder MSI will automatically enable this feature, if available (some + minimal Windows versions do not provide it). - The Windows Server installation requires at least 16 GB of disk space. The - volumes hosted by this node need the extra space. + You may check the availability of this feature by running the following: -For ``cinder-volume`` to work properly, you must configure NTP as explained -in :ref:`configure-ntp-windows`. + .. code-block:: powershell -Next, install the requirements as described in :ref:`windows-requirements`. + Get-WindowsFeature FS-iSCSITarget-Server + .. end +.. end +The Windows Server installation requires at least 16 GB of disk space. The +volumes hosted by this node will need extra space. +Configuring cinder-volume +~~~~~~~~~~~~~~~~~~~~~~~~~ -Getting the code -~~~~~~~~~~~~~~~~ - -Git can be used to download the necessary source code. The installer to run Git -on Windows can be downloaded here: - -https://git-for-windows.github.io/ - -Once installed, run the following to clone the OpenStack Block Storage code: - -.. code-block:: console - - PS C:\> git.exe clone https://git.openstack.org/openstack/cinder - -Configure cinder-volume -~~~~~~~~~~~~~~~~~~~~~~~ - -The ``cinder.conf`` file may be placed in ``C:\etc\cinder``. Below is a -configuration sample for using the Windows iSCSI Driver: +Below is a configuration sample for using the Windows iSCSI Driver. Append +those options to your already existing ``cinder.conf`` file, described at +:ref:`cinder_storage_install_windows`. .. code-block:: ini [DEFAULT] - auth_strategy = keystone - volume_name_template = volume-%s + enabled_backends = winiscsi + + [winiscsi] volume_driver = cinder.volume.drivers.windows.iscsi.WindowsISCSIDriver - glance_api_servers = IP_ADDRESS:9292 - rabbit_host = IP_ADDRESS - rabbit_port = 5672 - sql_connection = mysql+pymysql://root:Passw0rd@IP_ADDRESS/cinder windows_iscsi_lun_path = C:\iSCSIVirtualDisks - rabbit_password = Passw0rd - logdir = C:\OpenStack\Log\ - image_conversion_dir = C:\ImageConversionDir - debug = True + volume_backend_name = winiscsi -The following table contains a reference to the only driver specific -option that will be used by the Block Storage Windows iSCSI driver: + # The following config options are optional + # + # use_chap_auth = true + # target_port = 3260 + # target_ip_addres = + # iscsi_secondary_ip_addresses = + # reserved_percentage = 5 +.. end -.. include:: ../../tables/cinder-windows.inc - -Run cinder-volume ------------------ - -After configuring ``cinder-volume`` using the ``cinder.conf`` file, you may -use the following commands to install and run the service (note that you -must replace the variables with the proper paths): - -.. code-block:: console - - PS C:\> python $CinderClonePath\setup.py install - PS C:\> cmd /c C:\python27\python.exe c:\python27\Scripts\cinder-volume" --config-file $CinderConfPath - -Reference material ------------------- - -.. _configure-ntp-windows: - -Configure NTP -------------- - -Network time services must be configured to ensure proper operation -of the OpenStack nodes. To set network time on your Windows host you -must run the following commands: - -.. code-block:: bat - - C:\>net stop w32time - C:\>w32tm /config /manualpeerlist:pool.ntp.org,0x8 /syncfromflags:MANUAL - C:\>net start w32time - -Keep in mind that the node will have to be time synchronized with -the other nodes of your OpenStack environment, so it is important to use -the same NTP server. Note that in case of an Active Directory environment, -you may do this only for the AD Domain Controller. - - -.. _windows-requirements: - -Requirements -~~~~~~~~~~~~ - -Python ------- - -Python 2.7 32bit must be installed as most of the libraries are not -working properly on the 64bit version. - -**Setting up Python prerequisites** - -#. Download and install Python 2.7 using the MSI installer from here: - - `python-2.7.3.msi download - `_ - - .. code-block:: console - - PS C:\> $src = "https://www.python.org/ftp/python/2.7.3/python-2.7.3.msi" - PS C:\> $dest = "$env:temp\python-2.7.3.msi" - PS C:\> Invoke-WebRequest –Uri $src –OutFile $dest - PS C:\> Unblock-File $dest - PS C:\> Start-Process $dest - -#. Make sure that the ``Python`` and ``Python\Scripts`` paths are set up - in the ``PATH`` environment variable. - - .. code-block:: console - - PS C:\> $oldPath = [System.Environment]::GetEnvironmentVariable("Path") - PS C:\> $newPath = $oldPath + ";C:\python27\;C:\python27\Scripts\" - PS C:\> [System.Environment]::SetEnvironmentVariable("Path", $newPath, [System.EnvironmentVariableTarget]::User - -Python dependencies -------------------- - -The following packages need to be downloaded and manually installed: - -setuptools - https://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11.win32-py2.7.exe - -pip - https://pip.pypa.io/en/latest/installing/ - -PyMySQL - http://codegood.com/download/10/ - -PyWin32 - https://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe - -Greenlet - http://www.lfd.uci.edu/~gohlke/pythonlibs/#greenlet - -PyCryto - http://www.voidspace.org.uk/downloads/pycrypto26/pycrypto-2.6.win32-py2.7.exe - -The following packages must be installed with pip: - -* ecdsa -* amqp -* wmi - -.. code-block:: console - - PS C:\> pip install ecdsa - PS C:\> pip install amqp - PS C:\> pip install wmi - -Other dependencies ------------------- - -``qemu-img`` is required for some of the image related operations. -You can get it from here: http://qemu.weilnetz.de/. -You must make sure that the ``qemu-img`` path is set in the -PATH environment variable. - -Some Python packages need to be compiled, so you may use MinGW or -Visual Studio. You can get MinGW from here: -http://sourceforge.net/projects/mingw/. -You must configure which compiler is to be used for this purpose by using the -``distutils.cfg`` file in ``$Python27\Lib\distutils``, which can contain: - -.. code-block:: ini - - [build] - compiler = mingw32 - -As a last step for setting up MinGW, make sure that the MinGW binaries' -directories are set up in PATH. +The ``windows_iscsi_lun_path`` config option specifies the directory in +which VHD backed volumes will be stored. diff --git a/doc/source/configuration/block-storage/drivers/windows-smb-volume-driver.rst b/doc/source/configuration/block-storage/drivers/windows-smb-volume-driver.rst new file mode 100644 index 00000000000..91c128ec292 --- /dev/null +++ b/doc/source/configuration/block-storage/drivers/windows-smb-volume-driver.rst @@ -0,0 +1,239 @@ +.. _windows_smb_volume_driver: + +========================= +Windows SMB volume driver +========================= + +Description +~~~~~~~~~~~ + +The Windows SMB volume driver leverages pre-existing SMB shares, used to store +volumes as virtual disk images. + +The main reasons to use the Windows SMB driver are: + +* ease of management and use +* great integration with other Microsoft technologies (e.g. Hyper-V Failover + Cluster) +* suitable for a various range of deployment types and sizes + +The ``cinder-volume`` service as well as the required Python components will +be installed directly onto designated Windows nodes (prefferably the ones +exposing the shares). + +Common deployment scenarios +--------------------------- + +The SMB driver is designed to support a variety of scenarios, such as: + +* Scale-Out File Servers (``SoFS``), providing highly available SMB shares. +* standalone Windows or Samba shares +* any other SMB 3.0 capable device + +By using SoFS shares, the virtual disk images are stored on Cluster Shared +Volumes (``CSV``). + +A common practice involves depoying CSVs on top of SAN backed LUNs +(exposed to all the nodes of the cluster through iSCSI or Fibre Channel). In +absence of a SAN, Storage Spaces/Storage Spaces Direct (``S2D``) may be used +for the underlying storage. + +.. note:: + + S2D is commonly used in hyper-converged deployments. +.. end + +Features +-------- + +``VHD`` and ``VHDX`` are the currently supported image formats and may be +consumed by Hyper-V and KVM compute nodes. By default, dynamic (thinly +provisioned) images will be used, unless configured otherwise. + +The driver accepts one or more shares that will be reported to the Cinder +scheduler as storage pools. This can provide means of tiering, allowing +specific shares (pools) to be requested through volume types. + +.. code-block:: console + + cinder type-key $volume_type set pool_name=$pool_name +.. end + +Frontend QoS specs may be associated with the volume types and enforced on the +consumer side (e.g. Hyper-V). + +.. code-block:: console + + cinder qos-create $rule_name consumer=front-end total_bytes_sec=20971520 + cinder qos-associate $rule_name $volume_type_id + cinder create $size --volume-type $volume_type_id +.. end + +Clustering support +------------------ +Active-Active Cinder clustering is currently experimental and should not be +used in production. This implies having multiple Cinder Volume services +handling the same share simultaneously. + +On the other hand, Active-Pasive clustering can easily be achieved, configuring +the Cinder Volume service as clustered using Microsoft Failover Cluster. + +By using SoFS, you can provide high availability of the shares used by Cinder. +This can be used in conjunction with the Nova Hyper-V cluster driver, which +allows clustering virtual machines. This ensures that when a compute node is +compromised, the virtual machines are transparently migrated to a healthy +node, preserving volume connectivity. + +.. note:: + + The Windows SMB driver is the only Cinder driver that may be used along + with the Nova Hyper-V cluster driver. The reason is that during an + unexpected failover, the volumes need to be available on the destination + compute node side. + + +.. _windows_smb_volume_driver_prerequisites: + +Prerequisites +~~~~~~~~~~~~~ + +Before setting up the SMB driver, you will need to create and configure one or +more SMB shares that will be used for storing virtual disk images. + +.. note:: + The driver does not manage share permissions. You will have to make sure + that Cinder as well as share consumers (e.g. Nova, Hyper-V) have access. + + Note that Hyper-V VMs are run using a built-in user group: + ``NT VIRTUAL MACHINE\Virtual Machines``. +.. end + +The easiest way to provide share access is by using Active Directory accounts. +You may grant share access to the users running OpenStack services, as well as +the compute nodes (and optionally storage nodes), using per computer account +access rules. One of the main advantages is that by doing so, you don't need +to pass share credentials to Cinder (and implicitly volume consumers). + +By granting access to a computer account, you're basically granting access to +the LocalSystem account of that node, and thus to the VMs running on that +host. + +.. note:: + By default, OpenStack services deployed using the MSIs are run as + LocalSystem. + +Once you've granted share access to a specific account, don't forget to also +configure file system level permissions on the directory exported by the +share. + +Configuring cinder-volume +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Below is a configuration sample for using the Windows SMB Driver. Append +those options to your already existing ``cinder.conf`` file, described at +:ref:`cinder_storage_install_windows`. + +.. code-block:: ini + + [DEFAULT] + enabled_backends = winsmb + + [winsmb] + volume_backend_name = myWindowsSMBBackend + volume_driver = cinder.volume.drivers.windows.smbfs.WindowsSmbfsDriver + smbfs_mount_point_base = C:\OpenStack\mnt\ + smbfs_shares_config = C:\Program Files\Cloudbase Solutions\OpenStack\etc\cinder\smbfs_shares_list + + # The following config options are optional + # + # image_volume_cache_enabled = true + # image_volume_cache_max_size_gb = 100 + # image_volume_cache_max_count = 10 + # + # nas_volume_prov_type = thin + # smbfs_default_volume_format = vhdx + # max_over_subscription_ratio = 1.5 + # reserved_percentage = 5 + # smbfs_pool_mappings = //addr/share:pool_name,//addr/share2:pool_name2 +.. end + +The ``smbfs_mount_point_base`` config option allows you to specify where +the shares will be *mounted*. This directory will contain symlinks pointing +to the shares used by Cinder. Each symlink name will be a hash of the actual +share path. + +Configuring the list of available shares +---------------------------------------- + +In addition to ``cinder.conf``, you will need to have another config file, +providing a list of shares that will be used by Cinder for storing disk +images. In the above sample, this file is referenced by the +``smbfs_shares_config`` option. + +The share list config file must contain one share per line, optionally +including mount options. You may also add comments, using a '#' at the +beginning of the line. + +Bellow is a sample of the share list config file: + +.. code-block:: ini + + # Cinder Volume shares + //sofs-cluster/share + //10.0.0.10/volumes -o username=user,password=mypassword +.. end + +Keep in mind that Linux hosts can also consume those volumes. For this +reason, the mount options resemble the ones used by mount.cifs (in fact, +those will actually be passed to mount.cifs by the Nova Linux nodes). + +In case of Windows nodes, only the share location, username and password +will be used when mounting the shares. The share address must use slashes +instead of backslashes (as opposed to what Windows admins may expect) because +of the above mentioned reason. + +Depending on the configured share access rules, you may skip including +share credentials in the config file, as described in the +:ref:`windows_smb_volume_driver_prerequisites` section. + +Configuring Nova credentials +---------------------------- + +The SMB volume driver relies on the ``nova assisted volume snapshots`` feature +when snapshotting in-use volumes, as do other similar drivers using shared +filesystems. + +By default, the Nova policy requires admin rights for this operation. You may +provide Cinder specific credentials to be used when requesting Nova assisted +volume snapshots, as shown bellow: + +.. code-block:: ini + + [nova] + region_name=RegionOne + auth_strategy=keystone + auth_type=password + auth_url=http://keystone_host/identity + project_name=service + username=nova + password=password + project_domain_name=Default + user_domain_name=Default +.. end + +Configuring storage pools +------------------------- + +Each share is reported to the Cinder scheduler as a storage pool. + +By default, the share name will be the name of the pool. If needed, you may +provide pool name mappings, specifying a custom pool name for each share, +as shown bellow: + +.. code-block:: ini + + smbfs_pool_mappings = //addr/share:pool0 +.. end + +In the above sample, the ``//addr/share`` share will be reported as ``pool0``. + diff --git a/doc/source/configuration/block-storage/volume-drivers.rst b/doc/source/configuration/block-storage/volume-drivers.rst index a1430e043b4..62c595bcf5c 100644 --- a/doc/source/configuration/block-storage/volume-drivers.rst +++ b/doc/source/configuration/block-storage/volume-drivers.rst @@ -69,6 +69,7 @@ Driver Configuration Reference drivers/vzstorage-driver drivers/vmware-vmdk-driver drivers/windows-iscsi-volume-driver + drivers/windows-smb-volume-driver drivers/zadara-volume-driver drivers/zfssa-iscsi-driver drivers/zfssa-nfs-driver diff --git a/doc/source/install/cinder-storage-install-windows.rst b/doc/source/install/cinder-storage-install-windows.rst new file mode 100644 index 00000000000..8fdf8edf2dd --- /dev/null +++ b/doc/source/install/cinder-storage-install-windows.rst @@ -0,0 +1,176 @@ +.. _cinder_storage_install_windows: + +Install and configure a storage node +==================================== + +Prerequisites +~~~~~~~~~~~~~ + +The following Windows versions are officially supported by Cinder: + +* ``Windows Server 2012`` +* ``Windows Server 2012 R2`` +* ``Windows Server 2016`` + +The OpenStack Cinder Volume MSI installer is the recommended deployment tool +for Cinder on Windows. You can find it at +https://cloudbase.it/openstack-windows-storage/#download. + +It installs an independent Python environment, in order to avoid conflicts +with existing applications. It can dynamically generate a ``cinder.conf`` file +based on the parameters you provide. + +The OpenStack Cinder Volume MSI installer can be deployed in a fully automated +way using Puppet, Chef, SaltStack, Ansible, Juju, DSC, Windows Group Policies +or any other automated configuration framework. + +Configure NTP +------------- + +Network time services must be configured to ensure proper operation +of the OpenStack nodes. To set network time on your Windows host you +must run the following commands: + +.. code-block:: bat + + net stop w32time + w32tm /config /manualpeerlist:pool.ntp.org,0x8 /syncfromflags:MANUAL + net start w32time + +Keep in mind that the node will have to be time synchronized with +the other nodes of your OpenStack environment, so it is important to use +the same NTP server. + +.. note:: + + In case of an Active Directory environment, you may do this only for the + AD Domain Controller. +.. end + +Install and configure components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The MSI may be run in the following modes: + +Graphical mode +-------------- +The installer will walk you through the commonly used cinder options, +automatically generating a config file based on your input. + +You may run the following in order to run the installer in graphical mode, +also specifying a log file. Please use the installer full path. + +.. code-block:: powershell + + msiexec /i CinderVolumeSetup.msi /l*v msi_log.txt +.. end + +Unattended mode +--------------- +The installer will deploy Cinder, taking care of required Windows services and +features. A minimal sample config file will be generated and need to be +updated accordingly. + +Run the following in order to install Cinder in unattended mode, enabling the +iSCSI and SMB volume drivers. + +.. code-block:: powershell + + msiexec /i CinderVolumeSetup.msi /qn /l*v msi_log.txt ` + ADDLOCAL="iscsiDriver,smbDriver" +.. end + +By default, Cinder will be installed at +``%ProgramFiles%\Cloudbase Solutions\OpenStack``. You may choose a different +install directory by using the ``INSTALLDIR`` argument, as following: + + +.. code-block:: powershell + + msiexec /i CinderVolumeSetup.msi /qn /l*v msi_log.txt ` + ADDLOCAL="iscsiDriver,smbDriver" ` + INSTALLDIR="C:\cinder" +.. end + + +The installer will generate a Windows service, called ``cinder-volume``. + +.. note:: + Previous MSI releases may use a separate service per volume backend (e.g. + cinder-volume-smb). You may double check the cinder services along with + their executable paths by running the following: + + .. code-block:: powershell + + get-service cinder-volume* + sc.exe qc cinder-volume-smb + .. end + + Note that ``sc`` is also an alias for ``Set-Content``. To use the service + control utility, you have to explicitly call ``sc.exe``. +.. end + + +Configuring Cinder +------------------ +If you've run the installer in graphical mode, you may skip this part as the +MSI already took care of generating the configuration files. + +The Cinder Volume Windows service configured by the MSI expects the cinder +config file to reside at:: + + %INSTALLDIR%\etc\cinder.conf + +You may use the following config sample, updating fields appropriately. + +.. code-block:: ini + + [DEFAULT] + my_ip = MANAGEMENT_INTERFACE_IP_ADDRESS + auth_strategy = keystone + transport_url = rabbit://RABBIT_USER:RABBIT_PASS@controller:5672 + glance_api_servers = http://controller/image + sql_connection = mysql+pymysql://cinder:CINDER_DBPASS@controller/cinder + image_conversion_dir = C:\OpenStack\ImageConversionDir\ + lock_path = C:\OpenStack\Lock\ + log_dir = C:\OpenStack\Log\ + log_file = cinder-volume.log + + [coordination] + backend_url = file:///C:/OpenStack/Lock/ + + [key_manager] + api_class = cinder.keymgr.conf_key_mgr.ConfKeyManager +.. end + +.. note:: + The above sample doesn't configure any Cinder Volume driver. To do + so, follow the configuration guide for the driver of choice, appending + driver specific config options. +.. end + +Currently supported drivers on Windows: + +* :ref:`windows_smb_volume_driver` +* :ref:`windows_iscsi_volume_driver` + + +Finalize installation +~~~~~~~~~~~~~~~~~~~~~ + +#. Restart the Cinder Volume service: + + .. code-block:: powershell + + Restart-Service cinder-volume + + .. end + +#. Ensure that the Cinder Volume service is running: + + .. code-block:: powershell + + Get-Service cinder-volume + + .. end + diff --git a/doc/source/install/index-windows.rst b/doc/source/install/index-windows.rst new file mode 100644 index 00000000000..28e3091ee31 --- /dev/null +++ b/doc/source/install/index-windows.rst @@ -0,0 +1,15 @@ +===================================== +Cinder Installation Guide for Windows +===================================== + +This section describes how to install and configure storage nodes +for the Block Storage service. + +For the moment, Cinder Volume is the only Cinder service supported on +Windows. + +.. toctree:: + :maxdepth: 2 + + cinder-storage-install-windows.rst + cinder-verify.rst diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 032e75f8bfd..db07ffd0545 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -40,4 +40,5 @@ The following links describe how to install the Cinder Block Storage Service: index-obs index-rdo index-ubuntu + index-windows