Merge remote-tracking branch 'apache/main' into edit-feature-ext

Author: shwstppr

source/_static/images/proxmox-api-token-permission.png

@@ -92,6 +92,8 @@ CloudStack provides sample in-built orchestrator extensions for demonstration an
 
 .. include:: extensions/builtin_extensions.rst
 
+.. include:: extensions/limitations.rst
+
 .. include:: extensions/troubleshooting.rst
 
 .. include:: extensions/developer.rst

source/adminguide/extensions.rst

@@ -37,11 +37,20 @@ Get the Api Token-Secret from Proxmox
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If not already set up, create a new API Token in the Proxmox UI by navigating to `Datacenter > Permissions > API Tokens`.
-Uncheck the `Privilege Separation` checkbox in the `Add: Token` dialog or give permission to the API Token
-by navigating to `Datacenter > Permissions > Add > API Tokens Permission` and setting Role = `PVEAdmin` and Path = `/vms`.
-Note down the **user**, **token**, and **secret**.
+
+Uncheck the `Privilege Separation` checkbox in the `Add: Token` dialog
 
    |proxmox-add-token.png|
+
+Note down the **user**, **token**, and **secret**.
+
+Alternatively, check the `Privilege Separation` checkbox in the `Add: Token` dialog, and give permissions to the API Token
+by navigating to `Datacenter > Permissions > Add > API Tokens Permission` 
+
+- Set Role = `PVEAdmin` and Path = `/vms`
+- Set Role = `PVEAdmin` and Path = `/storage`
+- Set Role = `PVEAdmin` and Path = `/sdn`
+
    |proxmox-api-token-permission.png|
 
 To check whether the **token** and **secret** are working fine, you can check the following from the CloudStack Management Server:
@@ -186,6 +195,7 @@ Adding Hyper-V to CloudStack
 #. **Add Host.** Add a host to the newly created cluster with the following details:
 
    |hyperv-add-host.png|
+    **Note**: Add the detail **verify_tls_certificate** set to **false** to skip TLS certificate verification for self-signed certificates.
 
 #. **Create Template.** A Template in CloudStack can map to either a `Template` or an `ISO` in Hyper-V.
    Provide a dummy `url` and template name. Select `External` as the hypervisor and `HyperV` as the extension. Under `External Details`, specify:

source/adminguide/extensions/inbuilt_extensions.rst

@@ -0,0 +1,55 @@
+.. 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.
+   
+
+Limitations
+===========
+
+Although the external Instances behave a lot like CloudStack managed
+Instances in many ways, there are some limitations. Some of these
+limitations are due to the framework itself, while others can be addressed
+by adding custom actions in the scripts written for the built-in extensions.
+
+**Some general features/actions not supported at the framework level:**
+
+   - Console access to the external Instances.
+
+   - Data volumes.
+
+   - User Data and Metadata services.
+
+   - SSH key injection.
+
+   - Affinity Groups.
+
+   - Migrate Instance.
+
+   - Host Capacity and Utilization Stats.
+
+   - Add Nics to Instance post deployment.
+
+**Actions which can be implemented using Custom Actions in built-in extensions:**
+
+   - Reinstall Instance.
+
+   - Backup and Restore.
+
+   - Recurring Snapshots.
+
+   - Change Service Offering.
+
+   - Resize Volume.
+
+   - Attach ISO.

source/adminguide/extensions/limitations.rst

@@ -447,7 +447,7 @@ can also attach ISO images to Guest Instances. For example, this enables
 installing PV drivers into Windows. ISO images are not
 hypervisor-specific.
 
-
+.. _adding-an-iso:
 Adding an ISO
 -------------
 

source/adminguide/templates.rst

@@ -29,8 +29,7 @@ An overview of the procedure is as follow:
 
 #. Upload your Linux ISO.
 
-   For more information, see `“Adding an
-   ISO” <templates.html#adding-an-iso>`_.
+   For more information, see :ref:`adding-an-iso`.
 
 #. Create an Instance with this ISO.
 

source/adminguide/templates/_create_linux.rst

@@ -32,8 +32,7 @@ An overview of the procedure is as follows:
 
 #. Upload your Windows ISO.
 
-   For more information, see `“Adding an
-   ISO” <../templates.html#adding-an-iso>`_.
+   For more information, see :ref:`adding-an-iso`.
 
 #. Create an instance with this ISO.
 

source/adminguide/templates/_create_windows.rst

@@ -1265,6 +1265,19 @@ When the snapshotting is complete, the Instance is thawed.
 
 You can use this functionality on Instances with raw block storages (E.g. Ceph/SolidFire/Linstor).
 
+Disk-only File-based Storage Instance Snapshot on KVM
+-----------------------------------------------------
+
+Since version 4.21, CloudStack supports incremental disk-only instance snapshots for VMs on KVM that are running on file-based storages (NFS, local, shared mount point).
+Different from :ref:`Storage-based-Instance-Snapshots-on-KVM`, the VM is not frozen by default; only if the ``quiescevm`` parameter is provided. Furthermore, if ``quiescevm`` is true
+the VM is only frozen during the operation of creating the deltas on the volumes of the VM, thus the downtime is minimal.
+
+When using this snapshot strategy, you will not be able to create volume snapshots, as these two features are not compatible. If you want to use both volume snapshots and instance snapshots
+at the same time, you may inform the value ``KvmFileBasedStorageVmSnapshotStrategy`` on the ``vmSnapshot.strategies.exclude`` configuration, so that 
+this strategy is not used and the :ref:`Storage-based-Instance-Snapshots-on-KVM` feature is used instead. 
+
+More information on this feature may be found in the `specification <https://github.com/apache/cloudstack/issues/9524>`_.
+
 Limitations on Instance Snapshots
 ---------------------------------
 

source/adminguide/virtual_machines.rst

@@ -330,6 +330,23 @@ sudoers file:
    cloudstack ALL=NOPASSWD: /usr/bin/cloudstack-setup-agent
    Defaults:cloudstack !requiretty
 
+Please note that when adding the KVM host to your Cloudstack Management server,
+the setup commands will be run with sudo, even with root account.
+You should make sure that you are allowed to run binaries and sudo binaries.
+
+On security hardened machines, make sure that the following line is
+commented-out in your sudoers file if it exists:
+
+.. parsed-literal::
+
+   #Defaults noexec
+
+You may also want to make sure that sudo works by executing the following as
+the user you want to register the KVM host with:
+
+.. parsed-literal::
+
+   sudo /usr/in/cloudstack-setup-agent --help
 
 Configure CPU model for KVM guests (Optional)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^