--- title: "Shelving, resizing, rebuilding and console access" slug: "instance-lifecycle-and-console" source: "https://app.cloudpe.com/help/instance-lifecycle-and-console" updated: "2026-08-30T19:03:44.151Z" --- # Shelving, resizing, rebuilding and console access ## Overview Every instance in CloudPe has a lifecycle that goes beyond start and stop. From the instance detail page you can shelve an instance to release its compute resources, resize it onto a different flavor, rebuild it onto a different image while keeping its IPs and data volumes, and open a browser console when SSH or RDP is unavailable. This article covers the shelve/unshelve actions (including scheduled shelving), resize, rebuild, and console access — including time-limited console shares you can hand to a colleague or vendor. ## Before you start - You need an existing instance in a project you can access. See [Create and manage virtual machines](/help/create-manage-virtual-machines). - Read-only views (instance detail, console, console share list) require the `vms:read` permission. - All mutating actions — power, shelve, resize, rebuild, password reset, console share creation and revocation, shelve schedules — require `vms:update`. - Resize and rebuild depend on the instance's current power state, so plan a maintenance window: an instance must be stopped to rebuild, and active or stopped to resize. - Resize is available for hourly-billed instances only. If the instance runs on a longer billing cycle, change its billing cycle first. - A resize onto a larger flavor is a chargeable change; make sure the organization wallet has enough balance before you start. - Creating a shelve schedule requires organization membership. ## Steps ### Run a lifecycle action 1. Go to **Instances** and open the instance you want to act on. 2. Use **Power** for start, stop and reboot, or **More actions** for the rest of the lifecycle (shelve, unshelve, suspend, resume, rebuild). 3. Confirm the action. Use **Refresh status** to pull the current state from the region if the badge looks stale. 4. The **Logs** tab records what was dispatched and when. ![](/kb/compute/instance-lifecycle-and-console-01-actions.png) ### Shelve and unshelve Shelving powers the instance down and releases its compute resources back to the region; the boot volume and its data are kept. Unshelving schedules it back onto a host and boots it again. 1. Open the instance and choose shelve from **More actions**. The instance must be active. 2. To bring it back, choose unshelve. A shelved instance cannot be started with the start action — use unshelve instead. Because shelving is the only lifecycle action that stops compute metering, it is the right tool for instances that are idle overnight or at weekends. ### Schedule shelving and unshelving An instance can carry one shelve schedule, defined either as a named preset or as a pair of custom cron expressions with a timezone. The schedule can email you on success, on failure, or both, and can be toggled off without deleting it. Schedules are created, updated, toggled and removed through the shelve-schedule endpoints described below. ### Resize onto a different flavor 1. Open the instance and select **Resize**. 2. In the **Change VM Flavor** dialog, pick the target flavor and confirm. 3. The instance moves through a resizing state and is confirmed automatically. If it stays in the resizing state, issue the `confirm_resize` action. ![](/kb/compute/instance-lifecycle-and-console-02-resize.png) ### Rebuild onto a different image Rebuild reinstalls the operating system while preserving the instance's fixed IP, floating IP, security groups and attached data volumes. The boot disk is replaced, so anything stored on it is lost — snapshot it first if you need it. 1. Stop the instance. 2. Choose rebuild from **More actions** and select the image. Platform images and your own custom images are both eligible — see [Custom images and uploads](/help/custom-images-and-uploads). 3. Optionally set a new administrator password, or use **Reset Password** afterwards. 4. When the rebuild finishes the instance returns to the active state and the new password is shown once. ### Open the console 1. Open the instance and select **Console**. The instance must be active. 2. A browser console session opens against the region's console proxy. 3. If the guest never reaches a login prompt, fetch the console output (boot log) instead — it is available from the API and is the fastest way to diagnose a guest that fails to boot. ### Share the console Console shares let someone without a CloudPe login reach the console of one instance for a limited time. 1. Create a share for the instance, optionally naming it and setting an expiry duration. 2. Send the returned share link to the intended recipient. 3. List active shares for the instance at any time, and revoke a share as soon as it is no longer needed. Revocation is immediate. ## API All calls use the base host https://app.cloudpe.com and a bearer token. | Method | Path | |---|---| | POST | `/api/v1/instances/{instance_id}/actions` | | GET | `/api/v1/instances/{instance_id}/console` | | GET | `/api/v1/instances/{instance_id}/console/output` | | POST | `/api/v1/instances/{instance_id}/console/share` | | GET | `/api/v1/instances/{instance_id}/console/shares` | | DELETE | `/api/v1/instances/{instance_id}/console/shares/{share_id}` | | GET | `/api/v1/instances/{instance_id}/shelve-schedule` | | POST | `/api/v1/instances/{instance_id}/shelve-schedule` | | PUT | `/api/v1/instances/{instance_id}/shelve-schedule` | | PATCH | `/api/v1/instances/{instance_id}/shelve-schedule/toggle` | | DELETE | `/api/v1/instances/{instance_id}/shelve-schedule` | | GET | `/api/v1/instances/{instance_id}/history` | | GET | `/api/v1/instances/{instance_id}` | ### Lifecycle actions `action` accepts one of: `start`, `stop`, `force_stop`, `reboot`, `hard_reboot`, `rebuild`, `suspend`, `resume`, `shelve`, `unshelve`, `resize`, `confirm_resize`. ```bash curl -X POST https://app.cloudpe.com/api/v1/instances//actions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"action": "shelve"}' ``` Resize passes the target flavor; rebuild passes the image and, optionally, a new password: ```bash curl -X POST https://app.cloudpe.com/api/v1/instances//actions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"action": "resize", "flavor": ""}' ``` ```bash curl -X POST https://app.cloudpe.com/api/v1/instances//actions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"action": "rebuild", "image": "", "password": ""}' ``` ### Console and console shares ```bash curl https://app.cloudpe.com/api/v1/instances//console \ -H "Authorization: Bearer " ``` ```bash curl -X POST https://app.cloudpe.com/api/v1/instances//console/share \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"name": "vendor-debug-session"}' ``` ```bash curl -X DELETE https://app.cloudpe.com/api/v1/instances//console/shares/ \ -H "Authorization: Bearer " ``` ### Shelve schedule `schedule_type` is `preset` or `custom_cron`. A preset schedule sets `preset_name`; a custom schedule sets `shelve_cron` and `unshelve_cron`. ```bash curl -X POST https://app.cloudpe.com/api/v1/instances//shelve-schedule \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "schedule_type": "custom_cron", "shelve_cron": "", "unshelve_cron": "", "timezone": "Asia/Kolkata", "notify_on_success": true, "notify_on_failure": true, "notification_email": "ops@example.com" }' ``` Use `PUT` on the same path to change an existing schedule, `PATCH …/toggle` to enable or disable it, and `DELETE` to remove it. ## Limits & billing - Shelving is the only lifecycle action that stops compute billing: it closes the instance's compute usage record, and unshelving opens a new one. - Stopped and suspended instances are still billed for compute, because their resources stay allocated on the host. Stop/start cycles do not pause charges — only shelve does. - Storage keeps billing while an instance is shelved: boot and data volumes are retained and continue to accrue storage charges. - Resize is available for hourly-billed instances only. An instance on a longer billing cycle must be switched to hourly billing before it can be resized; a resize onto a more expensive flavor takes effect at the new rate once confirmed and is subject to a wallet balance check. - Rebuild replaces the boot volume, so its storage line is re-created; network and data volume billing is unaffected. - Each instance can have at most one shelve schedule. ## Troubleshooting | Error | Cause and fix | |---|---| | `Instance must be active to shelve` | Only a running instance can be shelved. Start it first, then shelve. | | `Instance must be shelved to unshelve` | The instance is stopped or suspended, not shelved. Use start or resume instead. | | `Instance must be stopped to start. Use 'unshelve' for shelved instances or 'resume' for suspended instances.` | Pick the action that matches the current state shown on the instance detail page. | | `Instance must be stopped to rebuild` | Stop the instance from **Power**, wait for the stopped state, then rebuild. | | `Image is required for rebuild` | The rebuild request had no `image`. Select an image in the dialog or pass `image` in the request body. | | `Instance must be active or stopped to resize` | Wait for the instance to settle into an active or stopped state before resizing. | | `flavor is required for resize action (OpenStack flavor ID)` | Include the target flavor in the resize request. | | `Resize is available for hourly-billed instances only. This instance has an active subscription — switch its billing cycle to hourly first, or contact support.` | Change the billing cycle to hourly on the **Billing** tab, then retry the resize. | | `Instance must be in RESIZING state to confirm resize` | The resize already completed or was never dispatched. Refresh the status and check the current flavor. | | `Flavor {…} not found in this region` | The target flavor is not offered in the instance's region. Pick a flavor listed for that region. | | `Instance must be active for console access` | Start or unshelve the instance, wait for the active state, then open the console. | | `Instance must be active to change password` | Password reset only works on a running instance. | | `Console share not found` | The share was already revoked or expired. Create a new one. | | `Invalid expiry. Use: {…}` | The share expiry duration is not one of the accepted values; the message lists what is allowed. | | `A shelve schedule already exists for this instance. Use PUT to update it.` | Update the existing schedule instead of creating a second one. | | `No shelve schedule found. Use POST to create one.` | There is no schedule on this instance yet; create one first. | | `Organization membership required to create a schedule` | Ask an organization owner to add you to the organization, then retry. | | `Insufficient wallet balance. Required: ₹{…}, Available: ₹{…}` | Top up the wallet from **Billing**, then retry the action. | | `Failed to get console: {…}` | The region's console service did not respond. Retry, and if it persists raise a support ticket with the instance ID. | ## FAQ **Does stopping an instance save money?** No. Only shelving releases the compute resources and closes the compute usage record. A stopped instance keeps its allocation on the host and keeps billing. **Will I lose my data if I shelve?** No. The boot volume and any attached data volumes are retained and are still charged as storage. Unshelving brings the instance back with its disks intact. **Does rebuild change my IP address?** No. Rebuild preserves the fixed IP, any floating IP, the security groups and attached data volumes. Only the boot disk is replaced. **Can I downgrade to a smaller flavor?** Resize supports moving between flavors offered in the instance's region, but the instance must be hourly-billed. Check the current state and billing cycle on the instance detail page before you start. **Who can use a console share link?** Anyone holding the link, for as long as it is valid — the recipient does not need a CloudPe account. Revoke the share as soon as the work is done; revocation takes effect immediately. **Where can I see what actions were run on an instance?** The **Logs** tab on the instance detail page, or `GET /api/v1/instances/{instance_id}/history`. ## Related - [Create and manage virtual machines](/help/create-manage-virtual-machines) - [Custom images and uploads](/help/custom-images-and-uploads)