Starting with the 4.21 release, Apache CloudStack introduces Instance Lease, a lifecycle control mechanism that allows cloud operators to define how long an Instance can exist and what should happen when that time is reached.

In day-to-day cloud operations, it is common for Instances to remain running long after their original purpose is gone. Temporary workloads such as training labs, proofs of concept, or test environments are created quickly, but are often not cleaned up. Over time, these unused Instances continue to consume compute, storage, IP addresses, and network capacity.

Instance Lease addresses this operational gap by making Instance lifetime an explicit part of the provisioning process. Users can deploy Instances with a defined duration and an automatic action when the lease expires. This helps keep environments clean, improves resource utilization, and simplifies governance across public clouds, private clouds, and enterprise IaaS platforms.

 

Why Instance Lease

 

The Challenge

In many cloud deployments, it’s easy for Instance to linger long past their useful lifespan:

• Training labs, proof-of-concepts or demo environments are spun up for a day or two, and then quietly forgotten.
• Sandbox and developer Instances remain powered even when the team moves on.
• Users provision Instances and move on, leaving behind “zombie” Instances consuming host, storage, IP-address and network resources.
• In shared infrastructure or managed service provider (MSP) environments, enforcing time-limited usage is a common requirement.

 

The Solution

With the Instance Lease feature, Apache CloudStack lets Administrators (and optionally Users) specify a lease duration for Instances, and an expiry action to be executed when the duration elapses.

In short:

• You deploy an Instance with a defined lifespan (for example, “10 days”).
• After the lease expires, the system either stops the Instance or destroys it automatically.
• The administrative burden of tracking and manually shutting down idle Instances is removed.
• Resource utilisation improves, governance is enforced, budgets are better protected.

Put simply: Instance Lease = “spin up an Instance for fixed time, and let the system clean it up automatically”.

 

What is Instance Lease

At its core, the Instance Lease feature allows an Administrator or User to deploy an Instance machine with a predefined “time-to-live”. When this lease expires, CloudStack will automatically perform a configured action on the Instance.

This entire mechanism is built on two new parameters:

• leaseduration: This is the lifespan of the Instance, specified in days (with a very generous maximum of 100 years).
• leaseexpiryaction: This defines what happens when the leaseduration is reached. You have two options:
  • STOP: The Instance is simply stopped.
  • DESTROY: The Instance is destroyed, and its resources are fully reclaimed.

 

For Administrators: Enabling and Configuring Instance Lease

By default, this new feature is disabled. To turn it on, an Administrator must first enable it in the Global Settings:

• instance.lease.enabled: Set this to true to activate the feature across your CloudStack management server.

Once enabled, you have a few other settings to fine-tune the background processes:

• instance.lease.scheduler.interval: This (in seconds) controls how often CloudStack checks for instances whose leases have expired. The default is 3600 (1 hour), but for more immediate cleanup, you may want to set this to a lower value.
• instance.lease.eventscheduler.interval: This (in seconds) controls how often the system generates warning events for Instances that are about to expire. The default is 86400 (1 day).
• instance.lease.expiryevent.daysbefore: This works with the setting above and defines how many days in advance to send the VM.LEASE.EXPIRING event. The default is 7 days, giving Users a week’s notice.

 

How to Use Instance Lease

Once the feature is enabled by an Administrator, Users can assign leases in a few ways.

This is the most important rule: a lease can only be added to an Instance when you deploy it. You cannot add a lease to an Instance that was deployed without one.

 

Method 1: Lease-Enabled Compute Offerings

Administrators can create Compute Offerings via API or UI that include lease specifications.

API

cmk create serviceoffering name="Dev-30Day-Offering" \ 
cpunumber=2 \ 
cpuspeed=2000 \ 
memory=4096 \ 
leaseduration=30 \ 
leaseexpiryaction=DESTROY

UI
Toggle “Enable Lease” in “Create Compute Offering” dialog and specify leaseduration and leaseexpiryaction.

When Users deploy Instances with these Offerings, the lease is automatically applied.

This is particularly useful for standardizing lifecycle policies across Instance types, e.g. all development Instances might have a 30-day lease with automatic destruction, while test Instances have a 7-day lease with automatic stop.

 

Method 2: Per-Instance Lease Configuration

Users can specify lease parameters directly during deployment, from API or UI even when using Compute Offerings that don’t define a lease.

API

cmk deploy virtualmachine name="test-instance" \
serviceofferingid=<offering-id> templateid=<template-id> \
zoneid=<zone-id> leaseduration=14 leaseexpiryaction=STOP

UI

In Advanced Mode: When deploying an Instance from the UI, you can select “Enable Lease” in the “Advanced mode” tab. This allows you to set a custom duration and expiry action for that specific Instance, and it will override any lease settings from the chosen Compute Offering.

 

Method 3: Managing an Existing Lease

What if you have an Instance with a lease that’s about to expire, but you need more time? As long as the Instance lease hasn’t already expired, you can manage it:

• Extend a lease: Edit the Instance and set a new, longer leaseduration.
• Reduce a lease: Set a new, shorter leaseduration.
• Disable a lease: Edit the Instance and set the leaseduration to -1. This removes the lease entirely, and the Instance will no longer expire.

This flexibility is available both in the UI (via the “Edit Instance” button) and through the updateVirtualMachine API call.

 

To Extend lease

An Instance with initial lease of 30 days can be modified to have 45 days lease with following API:

 cmk update virtualmachine id=<instance-id> leaseduration=45

 

Reducing Lease Duration

Similarily, leases can be shortened:

 cmk update virtualmachine id=<instance-id> leaseduration=7

 

Changing Expiry Action

Use following API to modify leaseexpiryaction from STOP to DESTROY for an Instance:

 cmk update virtualmachine id=<instance-id> leaseexpiryaction=DESTROY

 

To remove lease

If an Instance had a lease and you want to remove it, you can use following API:

 cmk update virtualmachine id=<instance-id> leaseduration=-1

Here -1 indicates removing the lease from the Instance.

Once disabled, the lease cannot be re-enabled for that Instance.

 

Instance Delete Protection and Instance Lease

The CloudStack team has built in a critical safeguard. If you set leaseexpiryaction to DESTROY, but the virtual machine also has Instance Delete Protection enabled, the destroy action will be skipped.

 

API enhancements

Multiple CloudStack APIs have been enhanced to support lease parameters:

• deployVirtualMachine: Accept leaseduration and leaseexpiryaction parameters
• updateVirtualMachine: Modify lease settings for existing Instances
• listVirtualMachines: Filter leased Instances by leased=true parameter
• createServiceOffering: Define lease defaults in Compute Offerings

 

UI Enhancements

• Resource widget shows dedicated Leased Instances quick action for Users
• New filter “Leased” is added in Instances page
• Instance Details shows lease information
• An icon beside Instance name to denote that it is under lease

 

Alerting

Instance Lease includes a proactive alerting system to notify Administrators and Users about upcoming expirations.

The alert scheduler runs at the interval specified by instance.lease.alertscheduler.interval and generates event to notify Users.

 

Alert Events

New event types have been added to CloudStack’s event framework:

• VM.LEASE.DISABLED: Triggered when the lease feature is disabled for an Instance.
• VM.LEASE.CANCELLED: Triggered when a lease is cancelled due to feature disablement
• VM.LEASE.EXECUTED: Triggered when a lease expiry action completes
• VM.LEASE.EXPIRING: Triggered for an Instance with remaining lease lesser than instance.lease.expiryevent.daysbefore days

 

Key Rules and Limitation

• No “After-the-Fact” Leases: You cannot add a lease to an existing Instance that was deployed without one.
• Expiry is Final: Once a lease expires and the STOP or DESTROY action is executed, the lease is removed. You cannot “extend” an already-expired lease.
• Global Disablement: If an Administrator sets instance.lease.enabled back to false, all active leases on all Instances are immediately cancelled. Re-enabling the feature later does not bring those old leases back.
• Lease is Tied to the Instance: The lease settings are copied to the Instance at deployment. Changing the Service Offering of the Instance later will not change its existing lease.

 

Final Thoughts

Instance Lease in Apache CloudStack 4.21 provides a practical and straightforward way to control Instance lifecycles. Instead of relying on external tooling, manual reviews, or periodic clean-up tasks, lifecycle limits are handled directly by the platform.

By defining a lease duration and an expiry action at deployment time, operators get predictable behaviour. Instances are automatically stopped or destroyed, resources are reclaimed, and unused workloads do not accumulate over time. At the same time, the feature remains flexible, allowing leases to be extended, shortened, or removed before they expire when operational requirements change.

For cloud service providers, enterprise IT teams, and platform operators, Instance Lease offers a clear and reliable mechanism to enforce time-limited usage without adding unnecessary complexity. It does not try to solve every lifecycle challenge, but it effectively addresses one of the most common operational problems in cloud environments.

In simple terms, Instance Lease turns Instance lifetime from an informal practice into an enforced platform rule.