Skip to content
Cloudbricks.dev logo

Apache CloudStack — Virtual Machine Lifecycle

Part 5 of the Apache CloudStack series: allocation strategies, deployment, management, and instance snapshots.

Kishore 5 min read

An instance in CloudStack moves through a defined set of states, and every operation — start, stop, migrate, snapshot, destroy — is a transition between them. Knowing the states makes the failure messages much easier to read.

This part covers the objects you need before a VM can exist, the deployment path, and the day-two operations that matter in a lab.

Before the first VM

Four things must exist:

  1. A template — the image the instance boots from.
  2. A service offering — the CPU, RAM, and disk profile.
  3. A network — where the instance attaches.
  4. A key pair or password — how you log in.

A service offering is the CloudStack equivalent of a flavor:

cmk create serviceoffering \
  name=small-2c4g \
  displaytext="2 vCPU / 4 GB" \
  cpunumber=2 \
  cpuspeed=2000 \
  memory=4096

Add offerha=true for high availability (the instance is restarted on another host if its host fails), and storagetype=shared if it should use shared storage.

A key pair is injected into the instance at boot:

cmk create sshkeypair name=lab-key

Save the private key returned by the API. CloudStack does not store it for you. On Linux, chmod 600 the file.

A security group is a stateful firewall applied to the instance’s network interfaces:

cmk create securitygroup name=web securitygroupaccount=<account>
cmk authorize securitygroupingress \
  securitygroupid=<sg-id> \
  protocol=TCP \
  startport=22 \
  endport=22 \
  cidrlist=192.168.0.0/16

In an advanced zone, security groups apply to isolated networks. In a basic zone, they are the primary isolation mechanism.

Deploying an instance

The UI wizard is the easiest path: Compute → Instances → Add Instance, then choose the template, offering, network, and key pair. The API equivalent is:

cmk deploy virtualmachine \
  serviceofferingid=<offering-id> \
  templateid=<template-id> \
  zoneid=<zone-id> \
  networkids=<network-id> \
  name=web-01 \
  displayname=web-01 \
  keypair=lab-key

The response includes a job ID. CloudStack operations are asynchronous; poll the job or watch the instance state:

cmk list virtualmachines name=web-01
cmk query asyncjobresult jobid=<job-id>

The instance moves through Starting to Running. If it lands in Error, the job result usually contains the reason.

Allocation strategies

When more than one host can run an instance, CloudStack chooses one using the cluster’s allocation strategy:

StrategyBehaviour
First fitPicks the first host with capacity
User dispersionSpreads a user’s VMs across hosts
Host dispersionSpreads all VMs across hosts
RandomRandom host with capacity

Set it on the cluster. For a lab, first fit is fine. For production, dispersion strategies reduce the blast radius of a host failure.

Affinity groups are the other scheduling control: host anti-affinity keeps instances on different hosts, and host affinity keeps them together. They require hardware support for the anti-affinity case and are enforced at deploy time, not continuously.

Day-two operations

OperationCommandNotes
Startcmk start virtualmachine id=<vm-id>Fails if the host has no capacity
Stopcmk stop virtualmachine id=<vm-id>Graceful by default
Rebootcmk reboot virtualmachine id=<vm-id>Guest-level reboot
Destroycmk destroy virtualmachine id=<vm-id>Instance stops; disk is retained
Recovercmk recover virtualmachine id=<vm-id>Undo a destroy before expunge
Expungecmk expunge virtualmachine id=<vm-id>Permanent deletion

Destroy is not delete. A destroyed instance remains recoverable until it is expunged. This is deliberate: it protects against accidental deletion and lets you keep the disk for forensics or a rebuild. Expunge is the irreversible step.

Snapshots and templates

There are two snapshot types:

  • Volume snapshot — a point-in-time copy of a disk. Restore it to the same volume or create a new volume from it.
  • Instance snapshot — a snapshot of the instance’s root volume, used to create a template. It is tied to the instance’s configuration.
cmk create snapshot volumeid=<volume-id>
cmk create template volumeid=<volume-id> ...

For a repeatable golden image, the pattern is: build a VM, configure it, stop it, create a template from its root volume, then deploy new instances from that template. Keep the template’s OS type and disk offering consistent with the original.

Migration and maintenance

Live migration moves a running instance to another host. It requires shared storage and hosts in the same cluster:

cmk migrate virtualmachine virtualmachineid=<vm-id> hostid=<host-id>

For host maintenance, put the host into maintenance mode. CloudStack migrates the instances it can and reports the ones it cannot. Local-storage instances must be stopped or cold-migrated first.

Console and recovery

If SSH is not working, the console is the way in:

cmk getVMPassword id=<vm-id>
cmk console proxy virtualmachineid=<vm-id>

The console proxy system VM serves the browser console. If the console URL is blank, check that the console proxy VM is running and reachable.

Troubleshooting

  • “No suitable host” — the cluster lacks CPU/RAM, the template is not available on the host, or an affinity group cannot be satisfied.
  • Instance stuck in Starting — check the host agent, libvirt logs, and the storage mount.
  • Password reset fails — the template must have cloud-init or the password-change script installed.
  • Cannot destroy — the instance may be in a transitional state; wait for the job to finish, then retry.
  • Snapshot fails — secondary storage is full or the volume is attached and the backend does not support live snapshots.