This is an automated email from the ASF dual-hosted git repository.
rohit pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new a6bd527 Documentation related to Instance lease feature (#492)
a6bd527 is described below
commit a6bd5274075446db250b754c535a7920d39ffa9f
Author: Manoj Kumar <[email protected]>
AuthorDate: Fri May 23 11:37:12 2025 +0530
Documentation related to Instance lease feature (#492)
* Documentation related to Instance lease feature
* add note for disabling feature and cancellation of lease
* Add behaviour and considerations for instance lease
* Add lease events in the doc
* incoporate suggestions
* update config key names and handle review comments
* minor change
* Add note for editing lease for compute offering and lowest possible value
for scheduler interval
* max allowed lease is for 100 years
* fix typos
---
.../images/compute_offering_dailog_with_lease.png | Bin 0 -> 60253 bytes
.../images/deploy_instance_advanced_lease.png | Bin 0 -> 34518 bytes
.../images/deploy_instance_lease_offering.png | Bin 0 -> 60568 bytes
source/_static/images/edit_instance_lease.png | Bin 0 -> 48288 bytes
source/adminguide/service_offerings.rst | 28 ++++
source/adminguide/virtual_machines.rst | 147 +++++++++++++++++++++
6 files changed, 175 insertions(+)
diff --git a/source/_static/images/compute_offering_dailog_with_lease.png
b/source/_static/images/compute_offering_dailog_with_lease.png
new file mode 100644
index 0000000..bf5417c
Binary files /dev/null and
b/source/_static/images/compute_offering_dailog_with_lease.png differ
diff --git a/source/_static/images/deploy_instance_advanced_lease.png
b/source/_static/images/deploy_instance_advanced_lease.png
new file mode 100644
index 0000000..8949961
Binary files /dev/null and
b/source/_static/images/deploy_instance_advanced_lease.png differ
diff --git a/source/_static/images/deploy_instance_lease_offering.png
b/source/_static/images/deploy_instance_lease_offering.png
new file mode 100644
index 0000000..ac56d08
Binary files /dev/null and
b/source/_static/images/deploy_instance_lease_offering.png differ
diff --git a/source/_static/images/edit_instance_lease.png
b/source/_static/images/edit_instance_lease.png
new file mode 100644
index 0000000..d406cb9
Binary files /dev/null and b/source/_static/images/edit_instance_lease.png
differ
diff --git a/source/adminguide/service_offerings.rst
b/source/adminguide/service_offerings.rst
index 0a2662e..550daf2 100644
--- a/source/adminguide/service_offerings.rst
+++ b/source/adminguide/service_offerings.rst
@@ -405,6 +405,34 @@ To create a new compute offering:
- **Disk Offering Strictness**: This flag defines the strictness of
the disk offering association
with the compute offering. When set to true, overriding of disk
offering is not allowed on deploy instance
and change disk offering is not allowed for the ROOT disk
+
+ - **Enable Lease**: When this flag is enabled, Compute Offering is created
with 'Instance Lease' enabled.
+ In CloudStack, a lease for an instance sets a specific time duration (in
days) after which a chosen lease action, such as stopping or destroying the
instance, will take place.
+ These lease settings are defined in the Compute Offering and are
automatically applied to any Instance created using it.
+
+ .. note:: The global configuration ``instance.lease.enabled`` should be
configured as true to create compute offering with lease.
+
+ .. note:: Lease duration or expiryaction can't be updated for compute
offering.
+
+ ``instance.lease.enabled``: Indicates whether Instance Lease feature is
enabled or not. Default is **false**
+ For more information, see `“Setting Global Configuration Parameters”
+
<../installguide/configuration.html#setting-global-configuration-parameters>`_.
+
+ When the flag is enabled
+
+ - **Lease Duration (in days)**: Sets the lease duration. An instance
created using this compute offering will inherit the lease duration by default.
Supported values are in range 1 <= N <= 36500.
+
+ - **Lease expiry action**: Lease expiry action: Denotes lease expiry
action, which gets executed upon lease expiry for instances created using this
compute offering.
+ Supported values for lease expiry action are as follows:
+
+ - STOP
+ - DESTROY
+
+ .. image:: /_static/images/compute_offering_dailog_with_lease.png
+ :width: 400px
+ :align: center
+ :alt: Compute offering dialog box
+
#. Click Add.
diff --git a/source/adminguide/virtual_machines.rst
b/source/adminguide/virtual_machines.rst
index 86043e5..558d23b 100644
--- a/source/adminguide/virtual_machines.rst
+++ b/source/adminguide/virtual_machines.rst
@@ -973,6 +973,153 @@ restoreVirtualMachine call. In this case, the Instance's
root disk is
destroyed and recreated, but from the same Template or ISO that was
already in use by the Instance.
+Instance Lease
+--------------
+
+CloudStack offers the option to create Instances with a Lease. A Lease defines
a set time period after which a selected action,
+such as stopping or destroying the instance, will be automatically performed.
This helps optimize cloud resource usage by automatically
+freeing up resources that are no longer in use.
+
+If a user needs an instance only for a limited time, this option can be very
helpful.
+When deploying an instance, users can either choose a Compute Offering that
includes Instance Lease support or enable it specifically for that instance,
+setting the number of days after which the instance should be stopped or
destroyed once their task is complete.
+
+
+**Configuring Instance Lease feature**
+
+The cloud administrator can use global configuration variables to control the
behavior of Instance Lease.
+To set these variables, API or CloudStack UI can be used:
+
+======================================= ========================
+Configuration Description
+======================================= ========================
+instance.lease.enabled Indicates whether to enable the
Instance Lease feature, will be applicable only on instances created after
lease is enabled. **Default: false**
+instance.lease.scheduler.interval Background task interval in seconds
that executes Lease expiry action on eligible expired instances. Default: 3600.
+instance.lease.eventscheduler.interval Background task interval in seconds
that executes Lease event executor for instances about to be expired in next N
days. Default: 86400
+instance.lease.expiryevent.daysbefore Denotes number of days (N) in advance
expiry events are generated for instance about to expire. Default: 7 days
+======================================= ========================
+
+.. note:: it is recommended to configure the lowest possible value (in secs)
for **instance.lease.scheduler.interval**, so that lease expiry action is taken
as soon as lease is expired.
+
+
+**Lease Parameters**
+
+
+**leaseduration**: Lease duration is specified in days. This can take Natural
numbers (>=1) and -1 to disable the lease. Max supported value is 36500 (100
years).
+
+User can disable Lease for instance in two ways:
+
+- Disable the Instance Lease during instance deployment by unchecking the
'Enable Lease' option when using a Compute Offering that supports it.
+- For existing instances with a lease already enabled, it can be removed by
editing the instance and unchecking the 'Enable Lease' option.
+
+**leaseexpiryaction**: There are two expiry action supported:
+
+- STOP: The instance is stopped, and it will be out of lease. The user can
restart the instance manually.
+- DESTROY: The instance is destroyed when the lease expires.
+
+.. note:: Expiry action is executed at most once on the instance, e.g. STOP
action will bring instance in Stopped state on expiry and instance will be out
of lease. User may choose to start it again.
+
+
+**Using Instance Lease**
+
+Lease information is associated to an Instance and following parameters are
used to enable lease for it:
+
+#. leaseduration
+#. leaseexpiryaction
+
+Instance remains active for specified leaseduration (in days). Upon lease
expiry, configured expiryaction is executed on the instance and
+lease is removed from the instance for any further action.
+
+**Notes:**
+
+#. Lease Assignment: A lease can only be assigned to an instance during
deployment.
+#. Lease Acquisition: Instances without a lease cannot acquire one by
switching to a different Compute Offering or by editing the instance.
+#. Lease Inheritance: Instances inherit the lease from a Compute Offering with
'Instance Lease' feature enabled. This lease can be overridden or disabled in
the “Advanced Settings”.
+#. Lease Persistence: A lease is always tied to the instance. Modifications to
the Compute Offering do not affect the instance's lease.
+#. Non-Lease Compute Offering: Instances can have a lease by enabling it in
the "Advanced Settings" for non-lease based Compute Offering too.
+#. Lease Duration Management: The lease duration can be extended or reduced
for instances before expiry. However, once the lease is disabled, it cannot be
re-enabled for that instance.
+#. Lease Expiry: Once the lease expires and the associated action is
completed, the lease is annulled and cannot be reattached or extended.
+#. Feature Disablement: If the lease feature is disabled, the lease associated
with instances is canceled. Re-enabling the feature will not automatically
reapply the lease to previously grandfathered instances.
+#. Delete Protection: The DESTROY lease expiry action is skipped for instances
with delete protection enabled.
+
+**Deployment of Instance with lease**
+
+There are 2 ways to deploy instance with lease from UI:
+
+1. Use Compute Offering which has 'Instance Lease' feature enabled.
+
+.. image:: /_static/images/deploy_instance_lease_offering.png
+ :width: 400px
+ :align: center
+ :alt: Deploy Instance with lease compute offering dialog box
+
+2. Enable lease under Advance settings during instance Deployment
+
+.. image:: /_static/images/deploy_instance_advanced_lease.png
+ :width: 400px
+ :align: center
+ :alt: Deploy Instance with lease using advance settings
+
+
+**Using API**
+
+Pass lease parameters in the command to enable lease during instance
deployment:
+
+.. code:: bash
+
+ cmk deploy virtualmachine name=..... leaseduration=... leaseexpiryaction=...
+
+- Use Compute Offering with lease
+
+.. code:: bash
+
+ cmk deploy virtualmachine name=.....
serviceofferingid=lease-compute-offering
+
+
+**Editing Instance Lease**
+
+The lease duration for an instance can be extended, reduced, or disabled for
instances that already have an active lease.
+However, it is not possible to enable the lease on an instance after it has
already been deployed.
+
+From UI:
+
+.. image:: /_static/images/edit_instance_lease.png
+ :width: 400px
+ :align: center
+ :alt: Edit Instance Lease dialog
+
+
+Using API:
+
+.. code:: bash
+
+ cmk update virtualmachine id=fa970d19-8340-455c-a9fb-569205954fdc
leaseduration=20 leaseexpiryaction=DESTROY
+
+To disable lease using API:
+
+.. code:: bash
+
+ cmk update virtualmachine id=fa970d19-8340-455c-a9fb-569205954fdc
leaseduration=-1
+
+.. note:: DESTROY action will ignore instance if deleteprotection is enabled
for it.
+
+.. note:: When the feature is disabled, the lease associated with instances is
cancelled. Re-enabling the feature will not automatically reapply the lease to
previously grandfathered instances.
+
+.. note:: Lease duration is considered as total lease for instance.
+
+**Instance Lease Events**
+
+Lease feature generates various events to help in auditing and monitoring:
+
+=================== ========================
+Event Type Description
+=================== ========================
+VM.LEASE.EXPIRED Event is generated at lease expiry
+VM.LEASE.DISABLED Denotes if lease is disabled by user/admin
+VM.LEASE.CANCELLED When lease is cancelled (feature gets disabled)
+VM.LEASE.EXPIRING Expiry intimation event for instance
+=================== ========================
+
Advanced Instance Settings
--------------------------
