Documentation for Shared FileSystems

source/adminguide/storage.rst

@@ -1485,6 +1485,105 @@ Deleting objects from a bucket
 
 2. Click on the |delete-button.png| button to delete the selected files from the bucket.
 
+Shared FileSystems
+---------------
+
+CloudStack offers fully managed NFS Shared FileSystems to all users.
+This section gives technical details on how to create/manage a Shared FileSystem
+using basic lifecycle operations and also some implementation details.
+
+.. note:: 
+   This feature is available only on advanced zones without security groups.
+
+Creating a New Shared FileSystem 
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Log in to the CloudStack UI as a user or administrator.
+
+#. In the left navigation bar, click Storage.
+
+#. In the Select View, choose Shared FileSystems.
+
+Click on Create Shared FileSystem, provide the following details and then click OK.
+
+#. Name
+#. Description
+#. Zone
+#. Format: Filesystem format (XFS, EXT4) which will be installed on the Shared FileSystem.
+#. Network: Guest network to which the Shared FileSystem will be attached.
+#. Compute offering: Offering using which the Shared FileSystem VM will be deployed.
+#. Disk offering: Offering used by the underlying data volume.
+#. Size, MinIops and MaxIos: Displayed only when the disk offering takes custom size and custom iops.
+
+|create-sharedfs.png|
+
+Admins will see extra fields in the create form where they can specify the
+account, domain and the project which will be owning the Shared FileSystem.
+|create-sharedfs-admin.png|
+
+Access
+~~~~~~
+The Shared FileSystem can be mounted by using the information given on the Access Tab.
+|sharedfs-access-tab.png|
+
+Lifecycle Operations 
+~~~~~~~~~~~~~~~~~~~~
+
+Supported lifecycle operations are :
+
+#. Update name and description of the Shared FileSystem
+
+#. Stop/Start Shared FileSystem - This will Stop and Start the Shared FileSystem VM 
+
+#. Restart Shared FileSystem - Reboots the Shared FileSystem VM. If Cleanup option is provided then the
+   VM state is cleaned up and restored to the original template. Configurations related to setting up the
+   NFS export will be done again. This will not affect the data on the VM.
+   Shared FileSystem.
+   |restart-sharedfs.png|
+
+#. Change Disk Offering - The disk offering of the underlying volume can be changed. Whether live resize
+   is supported or not depends on the hyervisor.
+   Please note that the size of the Shared FileSystem can only be increased.
+
+#. Change Service Offering - The service offering of the Shared FileSystem VM can be changed as required.
+   This can only be done when the Shared FileSystem is in Stopped state.
+
+#. Add/Remove Network - Guest networks can be added to or removed from the Shared FileSystem.
+   NFS share is exported to all networks. So VMs on different networks can mount the
+   same share using the respective IP addresses as given on the Access tab.
+   APIs serving these operations are addNicToVirtualMachine and removeNicToVirtualMachine
+   called with the Shared FileSystem VM ID.
+   Please note that the added networks must not be on overlapping CIDR ranges.
+   |add-remove-sharedfs-network.png|
+
+#. Destroy Shared FileSystem - The Shared FileSystem will be destroyed. It can be recovered before it automatically gets expunged.
+   Expunge timeout is given by the global setting 'sharedfs.cleanup.delay'.
+
+
+Shared FileSystem VM
+~~~~~~~~~~~~~~
+The Shared FileSystem VM is stateless and HA enabled. A new VM is deployed and will start
+serving the NFS share if the host or VM goes down.
+The VM is installed with the SystemVM template which is also used by the CPVM and SSVM.
+
+The Shared FileSystem VM can be seen in the Instance Tab as well. It's name is prefixed by the
+Shared FileSystem name. Actions that might interfere with Shared FileSystem operations are blocked or not shown.
+Basic operaions like Start, Stop and Reboot are allowed for troubleshooting.
+Users can access the VM using the 'View Console' button for troubleshooting although it is not
+required during normal operations.
+
+Service Offering
+~~~~~~~~~~~~~~~~
+There are two global settings that control what should be the minimum RAM size and minimum
+CPU count for the Shared FileSystem VM : 'sharedfsvm.min.cpu.count' and 'sharedfsvm.min.ram.size`.
+Only those offerings which meet these settings and have HA enabled are shown in the create form.
+
+Shared FileSystem Data Volume
+~~~~~~~~~~~~~~~~~~~~~~
+The data volume is also visible to the users. It is recommended to use the Shared FileSystem UI/API to
+manage the data but users or admin can perform actions directly on the data volume or the root volume
+as well if they wish. Attaching and detaching a disk is not allowed on a Shared FileSystem VM.
+
 .. |AttachDiskButton.png| image:: /_static/images/attach-disk-icon.png
    :alt: Attach Disk Button.
 .. |resize-volume-icon.png| image:: /_static/images/resize-volume-icon.png
@@ -1529,6 +1628,16 @@ Deleting objects from a bucket
    :alt: Import Volume
 .. |unmanage-volume.png| image:: /_static/images/unmanage-volume.png
    :alt: Unmanage Volume
+.. |create-sharedfs.png| image:: /_static/images/create-sharedfs.png
+   :alt: Create Shared FileSystem
+.. |create-sharedfs-admin.png| image:: /_static/images/create-sharedfs-admin.png
+   :alt: Create Shared FileSystem Admin Options
+.. |restart-sharedfs.png| image:: /_static/images/restart-sharedfs.png
+   :alt: Restart Shared FileSystem
+.. |sharedfs-access-tab.png| image:: /_static/images/sharedfs-access-tab.png
+   :alt: Shared FileSystem Access Tab
+.. |add-remove-sharedfs-network.png| image:: /_static/images/add-remove-sharedfs-network.png
+   :alt: Shared FileSystem Networks
 .. |nfs-mount-options-create-zone-wizard.png| image:: /_static/images/nfs-mount-options-create-zone-wizard.png
    :alt: NFS mount options in create Zone wizard
 .. |nfs-mount-options-add-primary-storage.png| image:: /_static/images/nfs-mount-options-add-primary-storage.png

source/conceptsandterminology/concepts.rst

@@ -535,6 +535,16 @@ Users can create buckets within the object storage pool.
 The basic storage units of Object Store are objects. Any type of data, regardless of content type, is stored as an object.
 Buckets are logical containers for storing objects.
 
+About Shared FileSystems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+CloudStack users can setup CloudStack managed Shared FileSystems which can be mounted via NFS.
+Users can choose the service offering, disk offering, filesystem format and network.
+The Shared FileSystem is deployed on a VM with the specified service offering.
+A data volume is created using the given disk offering and attached to the VM.
+User can specify which filesystem to use (XFS, EXT4).
+The filesystem is created on the data volume and exported via NFS.
+All VMs in the guest network can mount and read/write to the Shared FileSystem.
+
 About Physical Networks
 ~~~~~~~~~~~~~~~~~~~~~~~