CloudStack account levels represent the fundamental logical partitioning of a cloud software-defined data center. In high-density compute environments, the distinction between a Root Admin and a User Domain Admin is more than a simple permissions checkbox; it defines the boundary between physical infrastructure sovereignty and virtualized resource management. The Root Admin operates at the global tier, overseeing the physical hosts, primary storage arrays, and network service providers that constitute the cloud fabric. In contrast, the User Domain Admin functions within a specific sub-tree of the organizational hierarchy, possessing management authority over users and virtual resources within that domain while remaining strictly isolated from the underlying hardware layer. This hierarchical structure addresses the critical problem of multi-tenant security and resource contention. By delegating administrative tasks to Domain Admins, an organization reduces the management overhead on global operators while ensuring that no single tenant can influence the stability or throughput of the broader infrastructure. This manual details the technical specifications, implementation protocols, and auditing procedures required to manage these account levels effectively.
Technical Specifications
| Requirement | Default Port/Range | Protocol/Standard | Impact Level (1-10) | Recommended Resources |
| :— | :— | :— | :— | :— |
| API Gateway Access | 8080/8443 | RESTful/HTTPS | 10 | 4 vCPU, 8GB RAM |
| Database Connectivity | 3306 | MySQL/MariaDB | 9 | SSD RAID-10 Storage |
| Authentication | 389/636 | LDAP/LDAPS | 8 | Low Latency Network |
| Hypervisor Agent | 22/16509 | SSH/Libvirt | 10 | High Concurrency CPU |
| Physical Audit | N/A | IEEE 802.1Q (VLAN) | 7 | 10GbE SFP+ Fabric |
The Configuration Protocol
Environment Prerequisites:
Successful deployment of tiered administrative accounts requires Apache CloudStack version 4.15 or higher to leverage advanced Access Control List (ACL) features. The underlying operating system must be a hardened Linux distribution such as RHEL 8 or Ubuntu 20.04 LTS. All management nodes must have synchronized clocks via NTP to prevent credential expiration due to clock drift. The database tier requires at least 100 concurrent connections configured in my.cnf to handle the surge in API requests during domain-wide polling. Root Admin access requires a unique API key and Secret key generated through the UI or the cmk command-line tool.
Section A: Implementation Logic:
The logic of CloudStack account levels is built upon the principle of administrative encapsulation. When a Root Admin creates a domain, the system initializes a unique domain_id in the cloud.domain table. Every account subsequently created within that domain is tagged with this ID. The CloudStack API dispatcher utilizes a recursive permission check: for every incoming payload, the dispatcher verifies if the requested action (e.g., deployVirtualMachine) falls within the scope of the account’s account_type and domain_id. Root Admins (Type 1) bypass most of these checks, whereas Domain Admins (Type 2) are limited by the domain tree. This ensures that a Domain Admin cannot see the physical capacity of a Pod or Cluster, as that information resides outside their encapsulated view.
Step-By-Step Execution
Step 1: Initialize Domain Partitioning
Access the management server terminal and use the CloudMonkey CLI to create a new administrative domain. Execute the command: cmk create domain name=Engineering_Dept.
System Note: This command triggers an insert into the cloud.domain table and calculates the initial resource count for the new branch. The database must maintain ACID compliance during this transaction to prevent orphaned domain entries if the network experiences high latency.
Step 2: Provision the Domain Admin Account
Run the command: cmk create account username=dept_manager accounttype=2 domainid=[UUID] email=admin@eng.local.
System Note: Setting accounttype=2 specifically designates this user as a Domain Admin. The management server’s internal logic engine maps this user to the specific ACL group that grants visibility into the cloud.vm_instance records associated only with that domain_id.
Step 3: Define Resource Limits and Quotas
Execute the command: cmk update resourceLimit account=dept_manager domainid=[UUID] resourcetype=0 max=50.
System Note: This specific call sets the maximum number of virtual machines (resource type 0) the Domain Admin can manage. By hard-coding these limits, the Root Admin prevents any single domain from consuming excessive compute cycles, thereby protecting the thermal-inertia of the physical host racks and ensuring consistent throughput for other tenants.
Step 4: Configure Global Visibility Settings
As a Root Admin, navigate to the Global Settings and search for allow.user.view.all.domain.accounts. Set this value to false.
System Note: This modification changes the behavior of the API’s list functions. It ensures that when a Domain Admin calls listAccounts, the kernel-level filtering logic restricts the returned payload to only those accounts residing within the specific sub-domain, effectively hiding the cloud’s wider organizational structure.
Step 5: Validate Physical Interface Isolation
On the hypervisor level (KVM/Xen), verify the bridge configuration using brctl show or ip link.
System Note: The Root Admin must ensure that the traffic for the Engineering domain is encapsulated within the correct VLAN tag. This physical audit prevents packet-loss between the virtual switches and the physical routers, ensuring that the Domain Admin’s infrastructure remains logically separate from the Root Admin’s management network.
Section B: Dependency Fault-Lines:
The most common failure in tiered administration arises from database synchronization delays. If the cloud_usage service fails to update the account_vsm_limits table, a Domain Admin might be blocked from deploying resources even if their quota is not met. Another frequent bottleneck is the LDAP synchronization interval. If a user is promoted to Domain Admin in the active directory, but the CloudStack management server has not yet performed its periodic sync, the user will experience “Access Denied” errors when attempting to access the administrative console. Finally, check for signal-attenuation in the management network; if the API gateway cannot reach the database within the defined timeout (usually 5 seconds), the authentication handshake will fail.
THE TROUBLESHOOTING MATRIX
Section C: Logs & Debugging:
When diagnosing administrative permission failures, the primary log file is /var/log/cloudstack/management/management-server.log. Look for strings such as PermissionDenied or UnauthorizedAccessException. If a Domain Admin reports they cannot see their assigned volumes, query the database directly using mysql -u cloud -p -e “SELECT * FROM cloud.volumes WHERE domain_id = ‘[UUID]’;”. This confirms whether the resource is correctly mapped in the schema. For networking issues, check /var/log/cloudstack/agent/agent.log on the physical host to see if the hypervisor is receiving the correct metadata for the domain’s virtual routers. If you see EBTABLES errors, it indicates that the automated firewall rules for that domain are failing to apply, potentially exposing the tenant’s internal traffic.
OPTIMIZATION & HARDENING
– Performance Tuning: To decrease API latency for Domain Admins in large environments, enable the api.stats.interval setting to monitor the throughput of administrative calls. Use a high-performance key-value store like Redis to cache the result of the listDomains query, which reduces the query overhead on the primary MySQL database.
– Security Hardening: Implement mandatory multi-factor authentication (MFA) for the Root Admin level. For Domain Admins, enforce strict CIDR restrictions on the API access. Use the updateAccount API to set networkdomain parameters, ensuring that every VM launched by a Domain Admin is automatically assigned to a secure, isolated network segment with its own firewall rules.
– Scaling Logic: As the number of sub-domains grows, the Root Admin should transition to a delegated management model using Regions. By splitting the cloud into multiple regions, each with its own set of management servers, the organization can scale horizontally without increasing the concurrency contention for the global database lock.
THE ADMIN DESK
How can a Domain Admin reset a user password?
The Domain Admin must navigate to the Accounts tab, select the user, and use the Update User tool. This call is idempotent; the system will overwrite the existing hash in the database without affecting other user metadata.
Why is the Root Admin the only one seeing physical hosts?
This is by design to maintain infrastructure security. Displaying physical hostnames or IP addresses to a Domain Admin could allow for targeted side-channel attacks or insights into the physical network topology, increasing the risk of data breaches.
Can a Domain Admin create another Domain Admin?
Normally, no. The ability to create administrative accounts is restricted to the level above. However, if the Domain Admin is given “Sub-Domain Admin” permissions, they can manage users within their specific sub-tree but cannot exceed the total resource quota.
What causes a “Resource Limit Exceeded” error for a Domain Admin?
This occurs when the sum of resources (VMs, IPs, Volumes) in a domain reaches the value set by the Root Admin. To fix this, the Root Admin must execute updateResourceLimit to increase the allowable capacity for that UUID.