This document is currently being updated as part of the Object Name Convention initiative.
Content and examples may change.

Overview

We are standardizing how Object Types are referenced in Apache CloudStack code, logs, API documentation, and developer communication.

This page defines the Title Case Convention for CloudStack Object Types, provides context on where and when to use Title Case, and lists all official Object Types recognized in the platform.

The goal is to make references to key CloudStack objects consistent, readable, and clear, especially in user-facing text, logs, and documentation.

Why this change

Historically, Object Type names (e.g. "instance", "network", "account") have been written inconsistently across code, logs, and API responses. For example, developers may refer to a "virtual machine", "VM", or "instance" interchangeably.

To improve clarity and consistency:

The term Instance is now the official name for a CloudStack-managed virtual machine.
The legacy term Virtual Machine may still appear in some API names and parameters for backward compatibility, but must not be used in new code, logs, or documentation.

The Title Case Convention ensures that when a word refers to a CloudStack Object Type, it is written as a proper noun (e.g. Instance, Network, User). When used in a generic or non-object sense, it remains lowercase.

Canonical Object Types (Work in Progress)

The following are the canonical CloudStack Object Types that should always appear in Title Case when referring to CloudStack model entities.

Object Type	Description
Instance	Represents a virtual machine provisioned and managed by CloudStack. Formerly referred to as “Virtual Machine” or “VM.” Instances are created from Templates and run on hypervisors.
Network	Logical networking entity that defines connectivity between Instances, Routers, and other components. Includes isolated, shared, and system networks.
User	Represents an individual identity within an Account. Each User has unique credentials and access rights.
Account	Represents a CloudStack account that owns Users, Instances, Networks, and other resources.
Template	A base image used to deploy Instances.
Snapshot	A point-in-time copy of a Volume.

Note: API calls (e.g. listVirtualMachines, deployVirtualMachine) retain the older naming for compatibility.

Implementation Guidelines

1. Code and Logs

When writing or updating log messages, always use the correct Object Type name and capitalization.

// Incorrect
LOGGER.info("Failed to start virtual machine for account: " + accountId);

// Correct
LOGGER.info("Failed to start Instance for Account: " + accountId);

2. API Description

Ensure all API parameter and response field descriptions use the proper Object Type name and Title Case.

/////////////////////////////////////////////////////
//////////////// API parameters /////////////////////
/////////////////////////////////////////////////////

// Incorrect
@Parameter(name = ApiConstants.SNAPSHOT_POLICY_ID, type = CommandType.LONG, description = "lists recurring snapshots by snapshot policy ID")
private Long snapshotPolicyId;

// Correct
@Parameter(name = ApiConstants.SNAPSHOT_POLICY_ID, type = CommandType.LONG, description = "Lists recurring snapshots by Snapshot policy ID")
private Long snapshotPolicyId;

Before	After
“the account that owns this network”	“The Account that owns this Network.”
“Deploys a new virtual machine.”	“Deploys a new Instance.”

3. Documentation and UI

All references to CloudStack-managed objects in user-facing content; including CWIKI documentation, Admin UI strings, and API reference docs, should use the canonical Title Case name.

4. Code Comments

Use Title Case when describing Object relationships or model entities.

/**
 * Associates the Network with an Account and allocates IP addresses for Instances.
 */

Notes for Contributors

Always verify whether the term refers to a CloudStack Object Type before applying Title Case.
Do not change API names or parameters that are public-facing or backward-compatible (e.g., deployVirtualMachine); only update descriptions, logs, and documentation.
Use Instance instead of Virtual Machine or VM in all new code, messages, and documentation.
Community feedback is welcome via mailing list or JIRA.