Merge branch 'main' into instanceLease

Author: sudo87

.readthedocs.yaml

@@ -1,5 +1,8 @@
 version: 2
 
+sphinx:
+  configuration: source/conf.py
+
 build:
   os: "ubuntu-22.04"
   tools:

README.rst

@@ -90,7 +90,7 @@ On your computer, follow these steps to setup a local repository for working on
 .. code:: bash
 
    $ git clone https://github.com/YOUR_ACCOUNT/cloudstack-documentation.git
-   $ cd cloudstack-docs-install
+   $ cd cloudstack-documentation
    $ git remote add upstream https://github.com/apache/cloudstack-documentation.git
    $ git checkout main
    $ git fetch upstream

requirements.txt

@@ -2,4 +2,4 @@ docutils==0.20.1
 Sphinx==7.2.6
 sphinx-rtd-theme==2.0.0
 readthedocs-sphinx-ext==2.2.5
-Jinja2==3.1.3
+Jinja2==3.1.5

source/_global.rst

@@ -25,19 +25,19 @@
 
 .. Latest version systemvm template name
 
-.. |sysvm64-version|     replace:: 4.19.1
-.. |sysvm64-name-xen|    replace:: systemvm-xenserver-4.19.1
-.. |sysvm64-name-kvm|    replace:: systemvm-kvm-4.19.1
-.. |sysvm64-name-vmware| replace:: systemvm-vmware-4.19.1
-.. |sysvm64-name-hyperv| replace:: systemvm-hyperv-4.19.1
-.. |sysvm64-name-ovm|    replace:: systemvm-ovm-4.19.1
+.. |sysvm64-version|     replace:: 4.20.0
+.. |sysvm64-name-xen|    replace:: systemvm-xenserver-4.20.0-x86_64
+.. |sysvm64-name-kvm|    replace:: systemvm-kvm-4.20.0-x86_64
+.. |sysvm64-name-vmware| replace:: systemvm-vmware-4.20.0-x86_64
+.. |sysvm64-name-hyperv| replace:: systemvm-hyperv-4.20.0-x86_64
+.. |sysvm64-name-ovm|    replace:: systemvm-ovm-4.20.0-x86_64
 
 .. Latest version systemvm template URL
-.. |sysvm64-url-xen|    replace:: http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-xen.vhd.bz2
-.. |sysvm64-url-kvm|    replace:: http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-kvm.qcow2.bz2
-.. |sysvm64-url-vmware| replace:: http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-vmware.ova
-.. |sysvm64-url-hyperv| replace:: http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-hyperv.vhd.zip
-.. |sysvm64-url-ovm|    replace:: http://download.cloudstack.org/systemvm/4.19/systemvmtemplate-4.19.1-ovm.raw.bz2
+.. |sysvm64-url-xen|    replace:: http://download.cloudstack.org/systemvm/4.20/systemvmtemplate-4.20.0-x86_64-xen.vhd.bz2
+.. |sysvm64-url-kvm|    replace:: http://download.cloudstack.org/systemvm/4.20/systemvmtemplate-4.20.0-x86_64-kvm.qcow2.bz2
+.. |sysvm64-url-vmware| replace:: http://download.cloudstack.org/systemvm/4.20/systemvmtemplate-4.20.0-x86_64-vmware.ova
+.. |sysvm64-url-hyperv| replace:: http://download.cloudstack.org/systemvm/4.20/systemvmtemplate-4.20.0-x86_64-hyperv.vhd.zip
+.. |sysvm64-url-ovm|    replace:: http://download.cloudstack.org/systemvm/4.20/systemvmtemplate-4.20.0-x86_64-ovm.raw.bz2
 
 .. Images
 

source/_static/images/B&R-Backup-Respository.png

@@ -481,36 +481,74 @@ to be applied through the API call described above.
 
 
 In addition to those shown in the example script above, the following
-configuration items can be configured (the default values are for
-openldap)
+configuration items can be configured on a Global or on a per Domain level (the default values are for
+OpenLDAP) 
 
--  ``ldap.basedn``:	Sets the basedn for LDAP. Ex: **OU=APAC,DC=company,DC=com**
-
--  ``ldap.bind.principal``, ``ldap.bind.password``: DN and password for a User
-   who can list all the Users in the above basedn. Ex:
-   **CN=Administrator, OU=APAC, DC=company, DC=com**
+.. list-table:: LDAP Settings
+   :header-rows: 1
 
--  ``ldap.user.object``: object type of Users within LDAP. Defaults value is
-   **user** for AD and **interorgperson** for openldap.
+   * - Setting
+     - OpenLDAP
+     - Active Directory
+     - Description
+   * - ``ldap.basedn``
+     - `Ex: OU=APAC, DC=company, DC=com`
+     - `Ex: DC=company, DC=com`
+     - Sets the basedn for LDAP.
+   * - ``ldap.search.group.principle``
+     - `Ex: CN=ACSGroup, DC=company, DC=com`
+     - `Ex: CN=ACSGroup, CN=Users, DC=company, DC=com`
+     - (optional) if set only Users from this group are listed.
+   * - ``ldap.bind.principal``
+     - `Ex: CN=ACSServiceAccount, OU=APAC, DC=company, DC=com`
+     - `Ex: CN=ACSServiceAccount, CN=Users, DC=company, DC=com`
+     - Service account that can list all the Users in the above basedn. Avoid using privileged account such as Administrator.
+   * - ``ldap.bind.password``
+     - `******************`
+     - `******************`
+     - Password for a DN User. Is entered in plain text but gets stored encrypted.
+   * - ``ldap.user.object``
+     - `interorgperson`
+     - `user`
+     - Object type of Users within LDAP.
+   * - ``ldap.email.attribute``
+     - `mail`
+     - `mail`
+     - Email attribute within ldap for a User.
+   * - ``ldap.firstname.attribute``
+     - `givenname`
+     - `givenname`
+     - firstname attribute within ldap for a User.
+   * - ``ldap.lastname.attribute``
+     - `sn`
+     - `sn`
+     - lastname attribute within ldap for a User.
+   * - ``ldap.group.object``
+     - `groupOfUniqueNames`
+     - `groupOfUniqueNames`
+     - Object type of groups within LDAP.
+   * - ``ldap.group.user.uniquemember``
+     - `uniquemember`
+     - `uniquemember`
+     - Attribute for uniquemembers within a group.
+
+
+Once configured, on Add Account page, you will see an "Add LDAP Account" button which opens a dialog and the selected Users can be imported.
 
--  ``ldap.email.attribute``: email attribute within ldap for a User. Default
-   value for AD and openldap is **mail**.
+.. figure:: /_static/images/CloudStack-ldap-screen1.png
+   :align:   center
 
--  ``ldap.firstname.attribute``: firstname attribute within ldap for a User.
-   Default value for AD and openldap is **givenname**.
 
--  ``ldap.lastname.attribute``: lastname attribute within ldap for a User.
-   Default value for AD and openldap is **sn**.
+You could also use api commands:
+``listLdapUsers``, to list Users in LDAP that could or would be imported in CloudStack
+``ldapCreateAccount``, to manually create a User in a specific Account
+``importLdapUsers``, to batch import Users from LDAP
 
--  ``ldap.username.attribute``: username attribute for a User within LDAP.
-   Default value is **SAMAccountName** for AD and **uid** for openldap.
+Once LDAP is enabled, the Users will not be allowed to changed password
+directly in CloudStack.
 
 
-Restricting LDAP Users to a group:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  ``ldap.search.group.principle``: this is optional and if set only Users from
-   this group are listed.
 
 
 LDAP SSL:
@@ -524,30 +562,6 @@ You will need to know the path to the keystore and the password.
 -  ``ldap.truststore.password`` : truststore password
 
 
-LDAP groups:
-~~~~~~~~~~~~
-
--  ``ldap.group.object``: object type of groups within LDAP. Default value is
-   group for AD and **groupOfUniqueNames** for openldap.
-
--  ``ldap.group.user.uniquemember``: attribute for uniquemembers within a group.
-   Default value is **member** for AD and **uniquemember** for openldap.
-
-Once configured, on Add Account page, you will see an "Add LDAP Account" button
-which opens a dialog and the selected Users can be imported.
-
-.. figure:: /_static/images/CloudStack-ldap-screen1.png
-   :align:   center
-
-
-You could also use api commands:
-``listLdapUsers``, to list Users in LDAP that could or would be imported in CloudStack
-``ldapCreateAccount``, to manually create a User in a specific Account
-``importLdapUsers``, to batch import Users from LDAP
-
-Once LDAP is enabled, the Users will not be allowed to changed password
-directly in CloudStack.
-
 .. |button to dedicate a zone, pod,cluster, or host| image:: /_static/images/dedicate-resource-button.png
 
 Using a SAML 2.0 Identity Provider for User Authentication
@@ -676,7 +690,7 @@ For GitHub, please follow the instructions mentioned here `"Setting up OAuth 2.0
 In any OAuth 2.0 configuration admin has to use the redirect URI "http://<management server IP>:<port>/#/verifyOauth"
 
 .. Note:: [Google OAuth 2.0 redirect URI] :
-          Google OAuth 2.0 configuration wont accept '#' in the URI, please use "http://<management server Domain>:<port>/?verifyOauth"
+          Google OAuth 2.0 configuration won't accept '#' in the URI, please use "http://<management server Domain>:<port>/?verifyOauth"
           Google does not accept direct IP address in the redirect URI, it must be a domain. As a workaround one can add the management
           server IP to host table in the local system and assign a domain, something like "management.cloud". In that redirect URI looks like
           "http://management.cloud:8080/?verifyOauth"
@@ -884,3 +898,76 @@ password for a user:
 
    .. figure:: /_static/images/reset-password.png
       :align:   center
+
+Using API Key and Secret Key based Authentication
+-------------------------------------------------
+Users can generate API key and Secret key to directly access CloudStack APIs.
+This authenctication method is used for programatically calling CloudStack APIs and thus helps in automation.
+The API key uniquely identifies the Account, while the Secret key is used to generate a secure singnature.
+When making an API call, the API key and signature are included along with the command and other parameters,
+and sent to the CloudStack API endpoint. For detailed information, refer to the CloudStack's Programmer Guide.
+
+Disabling Api Key and Secret Key based Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Root Administrators may choose to Disable Api key based access for certain Users, Accounts or Domains.
+Or the Administrator may choose to Disable Api Key based access globally and allow only for certain users.
+This could be particularly useful in cases where external authorization mechanisms like LDAP, SAML or OAuth2 are used,
+as then Api key based authorization is the only means for automation.
+This gives control to the Admin over who is allowed to run automation.
+
+Api key based access is enabled by default but it can be disabled (or enabled) at different granularities:
+
+1. Users
+
+Setting for a User can be changed through the Api Key Access field in the Edit User form, visible only to the Root Administrator.
+Three values are possible: Disable, Enable and Inherit. Inherit means that the User will inherit whatever value is set for the Account.
+
+    .. figure:: /_static/images/edit-user-api-key-access.png
+       :align:  center
+
+Admins can also search for Users having the required Api key access value using the User list view search filter.
+
+    .. figure:: /_static/images/filter-user-api-key-access.png
+       :align:  center
+
+2. Accounts
+
+Similar to Users, Api Key Access field is present in the Edit Account Form and the Account list view search filter, only for the Root Administrator. 
+If the value is set to Inherit, it means that Account will inherit whatever value is set for the Domain.
+
+3. Domains
+
+Api Key Access at Domain level is controlled by the Domain level setting "api.key.access". If the Domain level
+configuration is not set, then similar to other configurations it will consult the global value.
+
+4. Global
+
+The global value of the configuration setting "api.key.access" is set to 'True' by default. So Api Key Access at
+all levels is enabled by default. If the global value is changed to 'False' without setting any of the lower levels,
+then Api Key Access will be disabled for all Users.
+
+Order of Precedence
+^^^^^^^^^^^^^^^^^^^
+The local value always takes precedence over the global value. So if Api key access is disabled for a User but
+enabled for an Account, the User authorisation will still fail. Only if the User's Api key access is set to
+'Inherit', the Account's Api Key Access value is considered.
+Similarly if Account's Api Key Access is set to 'Inherit', only then the Domain level setting is considered,
+And only if the Domain level configuration is not set, the Global configuration is considered.
+
+Examples
+^^^^^^^^
+
+#. Disallow Api key access for all Accounts and Users in a Domain.
+
+    #. Leave all User and Account level Api Key Access values to the default 'Inherit'.
+    #. Set the Domain level setting "api.key.access" to False only for the required domain.
+
+#. Disallow Api key access for some Users, but allowed globally.
+
+    #. Set the User level permission to ‘Disabled’ only for the required Users.
+    #. All upper level permissions should either be Inherit or Enabled.
+
+#. Allow Api key access to some Users, but disallowed globally.
+
+    #. Set User level permission to ‘Enabled’ only for the required Users.
+    #. All upper level permissions should either be Inherit or Disabled.

source/_static/images/B&R-BackupScheduleEntry.png

@@ -64,12 +64,16 @@ the user data:
 #. Run the following command to find the virtual router.
 
    .. code:: bash
+
       # cat /var/lib/dhclient/dhclient-eth0.leases | grep dhcp-server-identifier | tail -1
+
 #. Access user data by running the following command using the result of
    the above command
 
    .. code:: bash
+
       # curl http://10.1.1.1/latest/user-data
+
 Meta Data can be accessed similarly, using a URL of the form
 http://10.1.1.1/latest/meta-data/{metadata type}. (For backwards
 compatibility, the previous URL http://10.1.1.1/latest/{metadata type}

source/_static/images/add-bucket.png

@@ -0,0 +1,30 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information#
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+   http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+
+Hosts/Cluster Arch Types Allocation
+===================================
+
+Since CloudStack 4.20.0, it is possible to add AMD 64 bits and ARM 64 bits clusters (and hosts). A single zone can contain clusters (and hosts) of different arch types (multi-arch zones). 
+
+When a multi-arch zone is selected for VM deployment, CloudStack allows the users to filter the templates/ISOs by their arch type.
+
+|deploy-vm-arch-types.png|
+
+Once a template/ISO is selected, only the clusters (and hosts) matching the arch type will be considered for the VM allocation
+
+.. |deploy-vm-arch-types.png| image:: /_static/images/deploy-vm-arch-types.png
+   :alt: Filtering templates and ISOs by arch types
+

source/_static/images/cks-acquire-publicip.png

@@ -31,7 +31,7 @@ The following providers are currently supported:
 - KVM with NAS B&R Plugin (4.20 onwards)
 
 See the Veeam Backup and Recovery plugin documentation for plugin specific information.
-:ref:`Veeam Backup and Recovery Plugin`
+:ref:`Veeam Backup and Replication Plugin`
 
 See the DELL EMC Networker Backup and Recovery plugin documentation for plugin specific information.
 :ref:`DELL EMC Networker Backup and Recovery Plugin`
@@ -92,7 +92,7 @@ Backup Offerings
 ------------------
 
 Admins can import an external provider's backup offerings using UI or API for a
-particular zone, as well as manage a backup offering's lifecyle. Admins can also
+particular zone, as well as manage a backup offering's lifecycle. Admins can also
 specify if a backup offering allows user-defined backup schedules and ad-hoc
 backups. Users can list and consume the imported backup offerings, only root admins can import or
 delete offerings.
@@ -144,12 +144,12 @@ icon.
 
 |B&R-createBackup.png|
 
-To setup a recurring backup schedule, navigate to the Instance and click on the 'Backup Schedule'
+To setup a recurring backup schedule, navigate to the Instance and click on the 'Configure Backup Schedule'
 icon.
 
 |B&R-BackupSchedule.png|
 
-Then set the time and frequency of the backups, click 'Configure' and then 'Close'
+Then set the Interval type, timezone, time of taking the backup and maximum numbers of backups to retain.
 
 |B&R-BackupScheduleEntry.png|
 
@@ -178,6 +178,21 @@ Supported APIs:
 - **restoreVolumeFromBackupAndAttachToVM**: restore and attach a backed-up volume (of an Instance backup) to a specified Instance.
 
 
+Configuring resource limits on Backups
+--------------------------------------
+Administrators can enforce limits on the maximum number of backups that can be taken and
+the total backup storage size that can be used at an account, domain and project level.
+Administrators can do this by going to the configure limits tab in accounts, domains and projects
+similar to when enforcing resource limits on volumes, primary storage usage etc.
+
+Unlike other resources like volumes, backup limits take into account the physical used size
+and not the allocated size of the backup. This is because the backup once taken can never
+grow into the allocated size. At the time of backup creation, Cloudstack doesn't know the
+size of the backup that will be taken, so it uses the physical size of the volumes to be
+backed up from Volume Stats to calculate the backup size for checking resource limits.
+If Volume Stats are not present, then the virtual size of the volumes is used to calculate
+the backup size, although the actual backup size may be less than the size use to do resource limit check.
+
 .. |B&R-assignOffering.png| image:: /_static/images/B&R-assignOffering.png
    :alt: Assigning an SLA/Policy to an Instance.
    :width: 400 px