Merge remote-tracking branch 'apache/main' into andrijapanicsb-add-ne…

…w-local-pool-via-UI

source/adminguide/storage.rst

@@ -293,6 +293,98 @@ from being used for storing any further Templates, Volumes and Snapshots.
 
       cmk updateImageStore id=4440f406-b9b6-46f1-93a4-378a75cf15de readonly=true
 
+Direct resources to a specific secondary storage
+~~~~~~~~~
+
+By default, ACS allocates ISOs, volumes, snapshots, and templates to the freest secondary storage of the zone. In order to direct these resources to a specific secondary storage, the user can utilize the functionality of the dynamic secondary storage selectors using heuristic rules. This functionality utilizes JavaScript rules, defined by the user, to direct these resources to a specific secondary storage. When creating the heuristic rule, the script will have access to some preset variables with information about the secondary storage in the zone, about the resource the rule will be applied upon, and about the account that triggered the allocation. These variables are presented in the table below:
+
+   +-----------------------------------+-----------------------------------+
+   | Resource                          | Variables                         |
+   +===================================+===================================+
+   | Secondary Storage                 | ``id``                            |
+   |                                   +-----------------------------------|
+   |                                   | ``name``                          |
+   |                                   +-----------------------------------|
+   |                                   | ``usedDiskSize``                  |
+   |                                   +-----------------------------------|
+   |                                   | ``totalDiskSize``                 |
+   |                                   +-----------------------------------|
+   |                                   | ``protocol``                      |
+   +-----------------------------------+-----------------------------------+
+   | Snapshot                          | ``size``                          |
+   |                                   +-----------------------------------|
+   |                                   | ``hypervisorType``                |
+   |                                   +-----------------------------------|
+   |                                   | ``name``                          |
+   +-----------------------------------+-----------------------------------+
+   | ISO/Template                      | ``format``                        |
+   |                                   +-----------------------------------|
+   |                                   | ``hypervisorType``                |
+   |                                   +-----------------------------------|
+   |                                   | ``templateType``                  |
+   |                                   +-----------------------------------|
+   |                                   | ``name``                          |
+   +-----------------------------------+-----------------------------------+
+   | Volume                            | ``size``                          |
+   |                                   +-----------------------------------|
+   |                                   | ``format``                        |
+   +-----------------------------------+-----------------------------------+
+   | Account                           | ``id``                            |
+   |                                   +-----------------------------------|
+   |                                   | ``name``                          |
+   |                                   +-----------------------------------|
+   |                                   | ``domain.id``                     |
+   |                                   +-----------------------------------|
+   |                                   | ``domain.name``                   |
+   +-----------------------------------+-----------------------------------+
+
+To utilize this functionality, the user needs to create a selector, using the API ``createSecondaryStorageSelector``. Each selector created specifies the type of resource the heuristic rule will be verified upon allocation (e.g. ISO, snapshot, template or volume), and the zone the heuristic will be applied on. It is noteworthy that can only be one heuristic rule for the same type within a zone. Another thing to consider is that the heuristic rule should return the ID of a valid secondary storage. Below, some examples are presented for heuristic rules considering different scenarios:
+
+1. Allocate a resource type to a specific secondary storage.
+
+.. code:: javascript
+      
+   function findStorageWithSpecificId(pool) {
+      return pool.id === '7432f961-c602-4e8e-8580-2496ffbbc45d';
+   }
+
+   secondaryStorages.filter(findStorageWithSpecificId)[0].id
+
+2. Dedicate storage pools for a type of template format.
+
+.. code:: javascript
+
+   function directToDedicatedQCOW2Pool(pool) {
+      return pool.id === '7432f961-c602-4e8e-8580-2496ffbbc45d';
+   }
+
+   function directToDedicatedVHDPool(pool) {
+      return pool.id === '1ea0109a-299d-4e37-8460-3e9823f9f25c';
+   }
+
+   if (template.format === 'QCOW2') {
+      secondaryStorages.filter(directToDedicatedQCOW2Pool)[0].id
+   } else if (template.format === 'VHD') {
+      secondaryStorages.filter(directToDedicatedVHDPool)[0].id
+   }
+
+3. Direct snapshot of volumes with the KVM hypervisor to a specific secondary storage.
+
+.. code:: javascript
+
+   if (snapshot.hypervisorType === 'KVM') {
+      '7432f961-c602-4e8e-8580-2496ffbbc45d';
+   }
+
+4. Direct resources to a specific domain:
+
+.. code:: javascript
+
+   if (account.domain.id == '52d83793-26de-11ec-8dcf-5254005dcdac') {
+      '1ea0109a-299d-4e37-8460-3e9823f9f25c'
+   } else if (account.domain.id == 'c1186146-5ceb-4901-94a1-dd1d24bd849d') {
+      '7432f961-c602-4e8e-8580-2496ffbbc45d'
+   }
 
 Working With Volumes
 --------------------
@@ -1122,6 +1214,41 @@ Based on the selected Object Store, you can specify additional details like quot
 |Createbucket.png|
 
 
+Browsing objects in a bucket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Once a bucket has been created, you can browse the files in the bucket by clicking the bucket name.
+|bucket-details-browser-tab.png|
+
+2. Open the `Browser` tab to list files in the bucket.
+|object-store-browser-tab.png|
+
+Under `Browser` tab, clicking a directory on the browser tab will list the objects in that directory.
+For a file, clicking it list the properties of that file with links to access the file.
+|object-store-file-properties.png|
+
+.. note:: 
+   To access the bucket, UI uses the URL, access key and secret key from the bucket's details.
+
+
+Uploading an object to a bucket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. On the `Browser` tab, click the |upload-button.png| button to upload a file to the bucket. This will open up a dialog box to select the file to upload.
+|object-store-file-upload.png|
+
+2. Select the file you want to upload and specify the upload path & metadata for the object as per requirements.
+
+3. Click on `Upload` button to upload the file(s) to the bucket.
+
+
+Deleting objects from a bucket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Select the files you want to remove from the bucket.
+
+2. Click on the |delete-button.png| button to delete the selected files from the bucket.
+
 .. |AttachDiskButton.png| image:: /_static/images/attach-disk-icon.png
    :alt: Attach Disk Button.
 .. |resize-volume-icon.png| image:: /_static/images/resize-volume-icon.png
@@ -1142,6 +1269,18 @@ Based on the selected Object Store, you can specify additional details like quot
    :alt: Offering is needed when creating a volume from the ROOT Volume Snapshot.
 .. |Createbucket.png| image:: /_static/images/add-bucket.png
    :alt: Create Bucket
+.. |bucket-details-browser-tab.png| image:: /_static/images/bucket-details-browser-tab.png
+   :alt: Bucket details browser tab
+.. |object-store-browser-tab.png| image:: /_static/images/object-store-browser-tab.png
+   :alt: Object store browser tab
+.. |object-store-file-properties.png| image:: /_static/images/object-store-file-properties.png
+   :alt: Object store file properties
+.. |object-store-file-upload.png| image:: /_static/images/object-store-file-upload.png
+   :alt: Object store file upload
+.. |delete-button.png| image:: /_static/images/delete-button.png
+   :alt: Delete button
+.. |upload-button.png| image:: /_static/images/upload-button.png
+   :alt: Upload button
 .. |adding-local-pool-via-ui.png| image:: /_static/images/adding-local-pool-via-ui.png
    :align: center
    :alt: Adding Local Storage Pool via UI

source/adminguide/virtual_machines.rst

@@ -1445,11 +1445,24 @@ Instance statistics are collected on a regular interval (defined by global
 setting vm.stats.interval with a default of 60000 milliseconds).
 Instance statistics include compute, storage and Network statistics.
 
-Instance statistics are stored in the database as historical data for a desired time period. These historical statistics then can be retrieved using listVirtualMachinesUsageHistory API. For system VMs, the same historical statistics can be retrieved using listSystemVmsUsageHistory API
+Instance statistics are stored in the database as historical data for a desired time period. These historical statistics then can be retrieved using ``listVirtualMachinesUsageHistory`` API. For system VMs, the same historical statistics can be retrieved using ``listSystemVmsUsageHistory`` API
 
-Instance statistics retention time in the database is controlled by the global configuration - `vm.stats.max.retention.time`. Default value is 720 minutes, i.e., 12 hours. Another global configuration that affects Instance statistics is:
+Instance statistics retention time in the database is controlled by the global configuration ``vm.stats.max.retention.time``, with a default value of 720 minutes, i.e., 12 hours. The interval in which the metrics are retrieved are defined by the global configuration ``vm.stats.interval``, which has a default value of 60,000 milliseconds, i.e., 1 minute. The default values are only meant for guideline, as they can have a major impact in DB performance. The equation below presents the overall storage size required considering the values of these configurations.
 
-- `vm.stats.user.vm.only` - When set to 'false' stats for system VMs will be collected otherwise stats collection will be done only for user Instances.
+.. math::
+
+   StatsSize = (\frac{retention * 60000}{interval}) * nodes * VMs * registrySize
+
+- **StatsSize**: the size, in `bytes`, required for storing the VM stats;
+- **retention**: the value of the configuration ``vm.stats.max.retention.time``;
+- **interval**: the value of the configuration ``vm.stats.interval``;
+- **nodes**: the number of nodes running the management server in the environment;
+- **VMs**: the number of running VMs in the environment;
+- **registrySize**: the estimated size, in `bytes`, of the registry in the DB;
+
+Considering the default values of the configurations ``vm.stats.max.retention.time`` and ``vm.stats.interval``, three nodes running the management server, 10,000 running VMs and an estimated registry size of 400 bytes, it would need, approximately, 8 GB of storage to store VM stats. Therefore, the values for these configurations should be changed considering the CloudStack environment, evaluating the required storage and its impact in DB performance.
+
+Another global configuration that affects Instance statistics is ``vm.stats.user.vm.only``. When set to 'false' stats for system VMs will be collected, otherwise stats collection will be done only for user Instances.
 
 In the UI, historical Instance statistics are shown in the Metrics tab in an individual Instance view, as shown in the image below.