Merge release branch 4.20 to main

* 4.20:
  system vm destroy behaviour (#468)
  Added command to set libvirtd to traditional mode (#462)
  Add section about Domain VPCs (#410)
  note: AMQP configuration change (#463)
  Updating security group documentation (#469)
  vxlan prefix must be given to prevent interpretation as vlan (#465)
  Updated note in compute/service offering for enable/disable VM High Availability manager setting (#464)
  Disable API Key Access for users, accounts and domains (#446)

Author: DaanHoogland

source/_static/images/edit-user-api-key-access.png

@@ -884,3 +884,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/filter-user-api-key-access.png

@@ -73,6 +73,13 @@ in the AMQP server.
 Additionally, both an in-memory implementation and an Apache Kafka
 implementation are also available.
 
+
+.. note::
+   On upgrading from 4.19.x or lower, existing AMQP or Kafka intergration
+   configurations should be moved from folder
+   ``/etc/cloudstack/management/META-INF/cloudstack/core`` to
+   ``/etc/cloudstack/management/META-INF/cloudstack/event``
+
 Use Cases
 ~~~~~~~~~
 
@@ -101,7 +108,7 @@ As a CloudStack administrator, perform the following one-time
 configuration to enable event notification framework. At run time no
 changes can control the behaviour.
 
-#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/core``
+#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/event``
 
 #. Inside that folder, open ``spring-event-bus-context.xml``.
 
@@ -246,7 +253,7 @@ changes can control the behaviour.
 
    
 
-#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/core``
+#. Create the folder ``/etc/cloudstack/management/META-INF/cloudstack/event``
 
 #. Inside that folder, open ``spring-event-bus-context.xml``.
 

source/adminguide/accounts.rst

@@ -95,6 +95,8 @@ Adding Multiple Subnets to a Shared Network
       defaulted to the vlan of the network or if vlan of the network is
       null - to Untagged
 
+.. note:: If the VNI is of a VXLAN, the protocol prefix `vxlan://` must be used, like in `vxlan://<vni>`
+
 #. Click OK.
 
 

source/adminguide/events.rst

@@ -27,7 +27,8 @@ rules filter network traffic according to the IP address that is
 attempting to communicate with the instance. Security groups are particularly
 useful in zones that use basic networking, because there is a single
 guest network for all Guest Instances. In advanced zones, security groups are
-supported only on the KVM hypervisor.
+supported only on the KVM hypervisor and XenServer/XCP-ng with the network backend
+configured as "bridge". 
 
 .. note:: 
    In a zone that uses advanced networking, you can instead define 
@@ -41,8 +42,7 @@ desired set of rules.
 Any CloudStack user can set up any number of additional security groups.
 When a new instance is launched, it is assigned to the default security group
 unless another user-defined security group is specified. An instance can be a
-member of any number of security groups. Once an instance is assigned to a
-security group, it remains in that group for its entire lifetime; you
+member of any number of security groups. You can change the security groups of an instance only in a stopped state; you
 can not move a running instance from one security group to another.
 
 You can modify a security group by deleting or adding any number of

source/adminguide/networking/multiple_subnets_in_shared_network.rst

@@ -1448,6 +1448,26 @@ Editing, Restarting, and Removing a Virtual Private Cloud
    |restart-vpc.png|
 
 
+Working with Domain VPCs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The functionality of domain VPCs allows operators to aggregate multiple
+Network Tiers from distinct users on the same VPC, reducing the number of virtual
+routers necessary in the environment, and consequently, decreasing the
+amount of public IP addresses consumed. All Network Tiers added to the VPC share
+the same VR, but each one has their own broadcast domain and features
+implemented by the VPC, such as DHCP, NAT, and so on.
+
+In order to utilize this functionality, a new Network Tier must be included to an
+existing VPC by inputing the respective data for the account and the VPC
+on the **'createNetwork'** API. It is important to note that, in order
+for a Network Tier of a different account to be created on the VPC, the account
+that creates the Network Tier must have access to both the account that owns the
+VPC and the account that owns the Network Tier. The owner of the VPC must also
+have access to the account that owns the Network Tier, however, the opposite
+is not required.
+
+
 .. |add-vpc.png| image:: /_static/images/add-vpc.png
    :alt: adding a vpc.
 .. |add-tier.png| image:: /_static/images/add-tier.png

source/adminguide/networking/security_groups.rst

@@ -212,7 +212,7 @@ To create a new compute offering:
       it enables the admin to set some boundaries.
 
    -  **# of CPU cores**: The number of cores which should be allocated
-      to a system VM with this offering. If 'Custom constrained' is checked, the admin will
+      to the VM with this offering. If 'Custom constrained' is checked, the admin will
       be asked to enter the minimum and maximum number of CPUs that a user
       can request. If 'Custom unconstrained' is checked, this field does not appear
       as the user will be prompted to enter a value when creating their guest Instance.
@@ -226,7 +226,7 @@ To create a new compute offering:
       will be prompted to enter a value when creating their guest Instance.
 
    -  **Memory (in MB)**: The amount of memory in megabytes that the
-      system VM should be allocated. For example, “2048” would provide
+      VM should be allocated. For example, “2048” would provide
       a 2 GB RAM allocation. If 'Custom constrained' is selected, the admin will
       be asked to enter the minimum and maximum amount of RAM that a user
       can request. If 'Custom unconstrained' is selected, this field does
@@ -238,7 +238,11 @@ To create a new compute offering:
    -  **Network Rate**: Allowed data transfer rate in MB per second.
 
    -  **Offer HA**: If yes, the administrator can choose to have the
-      system VM be monitored and as highly available as possible.
+      VM be monitored and as highly available as possible.
+
+      .. note::
+         The HA is offered when the VM High Availability manager is enabled in the zone using the setting 'vm.ha.enabled', by default this setting is enabled.
+         When disabled, alerts are sent during HA attempts when 'vm.ha.alerts.enabled' setting is enabled.
 
    -  **Dynamic Scaling Enabled**: If yes, Instance can be dynamically scalable of cpu or memory
 
@@ -336,7 +340,7 @@ To create a new compute offering:
 
          -  **Storage type**: The type of disk that should be allocated. Local
             allocates from storage attached directly to the host where the
-            system VM is running. Shared allocates from storage accessible via
+            VM is running. Shared allocates from storage accessible via
             NFS.
 
          -  **Provisioning type**: The type of disk that should be allocated.
@@ -389,7 +393,7 @@ To create a new compute offering:
             disk that represents the root disk. This does not apply for KVM.
 
          -  **Storage Tags**: The tags that should be associated with the
-            primary storage used by the system VM.
+            primary storage used by the VM.
 
       When the flag is disabled
 
@@ -599,6 +603,10 @@ To create a system service offering:
    -  **Offer HA**: If yes, the administrator can choose to have the system
       VM be monitored and as highly available as possible.
 
+      .. note::
+         The HA is offered when the VM High Availability manager is enabled in the zone using the setting 'vm.ha.enabled', by default this setting is enabled.
+         When disabled, alerts are sent during HA attempts when 'vm.ha.alerts.enabled' setting is enabled.
+
    -  **Storage Tags**: The tags that should be associated with the primary
       storage used by the system VM.
 

source/adminguide/networking/virtual_private_cloud_config.rst

@@ -17,7 +17,7 @@
 CloudStack uses several types of system Instances to perform
 tasks in the cloud. In general CloudStack manages these system VMs and
 creates, starts, and stops them as needed based on scale and immediate
-needs. However, the administrator should be aware of them and their
+needs. Unlike user VMs, system VMs are expunged on destroying them. However, the administrator should be aware of them and their
 roles to assist in debugging issues.
 
 

source/adminguide/service_offerings.rst

@@ -637,6 +637,8 @@ Core Zone
 
    -  **VLAN / VNI ID.** The VLAN / VNI ID's that will be used for guest traffic.
 
+.. note:: If the VNI is of a VXLAN, the protocol prefix `vxlan://` must be used, like in `vxlan://<vni>`
+
 #. In a new pod, CloudStack adds the first cluster for you. You can
    always add more clusters later. For an overview of what a cluster is,
    see :ref:`about-clusters`