Skip to content
Cloudbricks.dev logo

Apache CloudStack - Accounts, Projects & Service Offerings

Part 6 of the Apache CloudStack series: domains, accounts, users, projects, service offerings, and resource limits.

Kishore 6 min read

A CloudStack cloud has two audiences. The people who run it need a hierarchy that maps onto an organisation. The people who use it need a menu of offerings they can pick from without understanding the infrastructure underneath. This part covers both: the account model, and the offerings that turn capacity into a product.

The account hierarchy

CloudStack models tenancy as a tree:

ROOT domain
└── Domain: engineering
    ├── Account: platform-team
    │   ├── User: alice (User)
    │   └── User: bob (User)
    └── Account: data-team
        └── User: carol (User)
LevelWhat it isWho manages it
DomainAn organisational boundary. Domains can contain sub-domains.ROOT admin; domain admins manage their own subtree
AccountThe resource-owning tenant. Every VM, volume, network and IP belongs to an account.Domain admin or ROOT admin
UserA login inside an account. Users inherit the account’s resources.Account admin, domain admin, or ROOT admin
RoleA named set of API permissions.ROOT admin

The important mental model: resources belong to accounts, not users. If two users are in the same account, they see the same VMs. If you need separation, create two accounts, not two users.

Account types

  • User — a normal tenant. Sees only its own account’s resources.
  • Domain Admin — manages accounts and users inside its domain, and can see resources in that domain.
  • ROOT Admin — the built-in admin account. Sees and controls everything.

The built-in accounts (admin, system) should not be used to run workloads. Create a named admin account for daily operations and keep the ROOT credentials for break-glass work.

Creating a domain and account

The UI path is Global Settings → Domains and Accounts. With the API:

# Create a sub-domain under ROOT
cmk create domain name=engineering

# Create an account inside it
cmk create account \
  accounttype=0 \
  email=platform@example.com \
  firstname=Platform \
  lastname=Team \
  username=platform-admin \
  password='<strong-password>' \
  domainid=<domain-id>

accounttype=0 is a normal user account. Use 1 for a domain admin and 2 for a ROOT admin. The roleid parameter, where available, assigns an RBAC role instead of relying on the legacy account type.

Then create additional users inside the account:

cmk create user \
  account=platform-team \
  domainid=<domain-id> \
  email=alice@example.com \
  firstname=Alice \
  lastname=Example \
  username=alice \
  password='<strong-password>'

Projects

A project is a shared workspace that sits across accounts. It exists for the case where a group of people from different accounts needs to collaborate on the same resources without merging their accounts.

  • A project has an owner account and members.
  • Resources created inside a project are owned by the project, not by an individual account.
  • Members can use project resources according to their project role.
  • Projects are scoped to a domain.
cmk create project name=web-platform displaytext="Web platform" domainid=<domain-id>
cmk add projectaccount projectid=<project-id> account=platform-team

Projects are useful for cross-team labs and shared development environments. They are not a substitute for proper account isolation: if two teams should not see each other’s resources, use separate accounts.

Service offerings

A service offering (compute offering) is the VM profile: CPU count, CPU speed, memory, and optional features. It is the CloudStack equivalent of an OpenStack flavor.

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

Key parameters:

ParameterMeaning
cpunumber / cpuspeedvCPU count and MHz per vCPU. cpuspeed is a scheduling hint, not a hard cap.
memoryRAM in MB.
offerhaRestart the VM on another host if its host fails.
storagetypeshared or local. Must match the storage pool.
hosttagsRestrict placement to hosts carrying a matching tag.
provisioningtypethin, thick, or sparse. Depends on the storage backend.
diskofferingidOptional root-disk profile.

There are also:

  • Disk offerings — size and storage tag for data volumes (covered in Part 4).
  • Network offerings — which services a network provides (covered in Part 3).
  • VPC offerings — the template for VPCs.

Custom vs fixed offerings

A fixed offering has a set size. A custom offering lets the user choose CPU, RAM, or disk within limits. Custom offerings are convenient but make capacity planning harder, because users can request shapes you did not size the cluster for. In a shared cloud, prefer fixed offerings with a small catalogue over a free-for-all.

Resource limits and quotas

Every account has limits. Limits are separate from the physical capacity of the cluster: they cap what a tenant is allowed to consume, not what the cluster can provide.

Common limit types:

ResourceAPI limit type
Instancesuser_vm
Volumesvolume
Snapshotssnapshot
Templatestemplate
Public IPspublic_ip
Networksnetwork
CPU corescpu
Memory (MB)memory
Primary storage (GB)primary_storage
Secondary storage (GB)secondary_storage

Read the current limits:

cmk list resource limits account=platform-team domainid=<domain-id>

Update them:

cmk update resource limit \
  account=platform-team \
  domainid=<domain-id> \
  resourcetype=0 \
  max=20

resourcetype is numeric; check the API reference or cmk list resource limits output for the mapping in your version. A value of -1 means unlimited.

Limits are the first place to look when a user reports “the deploy button is greyed out”. CloudStack will refuse a deployment that would exceed a limit even when the cluster has free capacity.

LDAP and single sign-on

CloudStack can authenticate users against an LDAP or Active Directory server instead of its local user table. Configure it under Global Settings → LDAP (or the ldap.* configuration keys), then create accounts with user.source=LDAP.

The usual pattern is:

  1. Point CloudStack at the directory.
  2. Map directory groups to CloudStack accounts or roles.
  3. Keep one local ROOT account as a break-glass login.

Test the bind DN and search base carefully. A wrong search base produces an authentication failure that looks like a bad password.

A workable tenancy design

For a small private cloud:

  • One domain per business unit.
  • One account per team or environment.
  • A fixed catalogue of three or four service offerings.
  • Per-account limits that match the team’s allocation.
  • A named admin account, with ROOT reserved for emergencies.

For a service provider:

  • One domain per customer.
  • One account per customer environment.
  • Strong limits, and a billing integration if you charge for usage.
  • Projects for shared internal work, not for customer isolation.

Troubleshooting

  • Account cannot deploy. Check resource limits first, then the service offering’s storage type and host tags.
  • User cannot log in. Confirm the account is enabled, the user is in the right domain, and LDAP is reachable if it is configured.
  • Offering not visible. Offerings can be restricted to a domain or zone. Check the offering’s scope and the account’s domain.
  • Limit update has no effect. The limit applies at the account level; a domain-level limit can still cap the account. Check both.
  • Deleted account still owns resources. CloudStack will not delete an account with active resources. Destroy and expunge the resources first, or migrate ownership where the API supports it.