CloudStack Global Settings function as the primary control plane for orchestration logic within the Apache CloudStack ecosystem. These settings dictate the behavioral parameters of the management server, defining how it handles resource allocation, networking, and virtual machine lifecycles. In the context of large scale cloud infrastructure, default configurations often fail to meet the requirements of high throughput and low latency environments. The problem typically manifests as resource fragmentation, slow VM deployment times, or stale state information within the database. The solution lies in the precise calibration of the configuration table within the CloudStack database or via the management interface. This manual provides the technical framework for identifying, modifying, and auditing these settings to ensure infrastructure stability. By fine tuning variables such as overprovisioning factors and interval timers, architects can reduce operational overhead and eliminate common bottlenecks in the orchestration layer.
Technical Specifications
| Requirement | Default Port/Range | Protocol/Standard | Impact Level (1-10) | Recommended Resources |
| :— | :— | :— | :— | :— |
| Management API | 8080 or 8443 | HTTP/S (REST) | 10 | 8GB RAM / 4 vCPU |
| Database Sync | 3306 | MySQL | 9 | High-Speed NVMe |
| Agent Communication | 8250 | TCP (KVM/Xen) | 9 | Low Latency Network |
| Console Proxy | 443 | HTTPS/WSS | 7 | 2GB RAM per Instance |
| Storage Orchestration | N/A | iSCSI/NFS/Ceph | 8 | 10Gbps Throughput |
Configuration Protocol
Environment Prerequisites:
Successful configuration of high impact Global Settings requires Apache CloudStack version 4.15 or higher. The underlying operating system must be a RHEL-based or Debian-based Linux distribution using systemd for service management. Administrators must possess root-level access to the management server and administrative credentials for the MySQL/MariaDB instance. All changes must adhere to the IEEE 802.1Q standards if modifying network-related global variables. Ensure that a full backup of the cloud database is performed before any direct manual updates to the configuration table.
Section A: Implementation Logic:
The implementation logic of CloudStack Global Settings is based on a hierarchical inheritance model. While most settings are applied globally, certain parameters can be overridden at the Zone, Pod, or Cluster level. The management server reads these configurations into an internal memory cache during the bootstrap process. For a setting to be considered idempotent, it must be applied via the CloudMonkey CLI or the UI, which triggers a validation check. Direct SQL path modifications are possible but carry the risk of bypassing the application layer logic, potentially leading to configuration drift or service instability.
Step-By-Step Execution
1. Verification of Current Global State
To begin, the administrator must query the existing values to establish a baseline. Use the cloudmonkey tool to list settings and filter by name.
cloudmonkey list configurations name=expunge.delay
System Note: This command queries the management server API, which in turn performs a select operation on the configuration table; it verifies the value currently resides in the active memory of the management service.
2. Modification of Resource Overprovisioning Factors
High density environments require the adjustment of the cpu.overprovisioning.factor and mem.overprovisioning.factor. Use the following command to increase CPU allocation logic.
cloudmonkey update configuration name=cpu.overprovisioning.factor value=2.0
System Note: This change informs the allocator service to allow more virtual CPUs than physical cores; the kernel on the hypervisor will manage the resulting context switching and throughput.
3. Adjusting Storage Cleanup Intervals
To manage disk space more aggressively, the expunge.delay and expunge.interval must be reduced. This is critical for ephemeral workloads that generate significant volume churn.
cloudmonkey update configuration name=expunge.delay value=3600
System Note: This sets the delay before a deleted volume is physically removed from the primary storage; it prevents immediate data loss while maintaining signal-attenuation of storage growth.
4. Direct Database Update for Hidden Settings
In rare cases where a setting is not exposed via the API, a direct SQL update is required. Open the MySQL terminal and target the cloud database.
mysql -u cloud -p
USE cloud;
UPDATE configuration SET value = ‘true’ WHERE name = ‘dynamic.apidoc.enabled’;
System Note: Direct manipulation of the configuration table requires a full service restart to ensure the internal cache is synchronized with the persistent state.
5. Service Synchronization and Reload
After modifying critical parameters, the management service must be cycled to ensure all background workers inherit the new configuration.
systemctl restart cloudstack-management
System Note: The systemctl command sends a SIGTERM to the Java process, allowing it to close active database connections before spawning a new process that re-reads the configuration payload.
Section B: Dependency Fault-Lines:
A common bottleneck in configuration management is the mismatch between global settings and physical hardware capabilities. For example, setting storage.overprovisioning.factor to a high value on a thin-provisioned SAN can lead to catastrophic VM freezes when the physical block device reaches capacity. Another fault-line is the stats.interval, which defines how often agents report metrics. If set too low (e.g., less than 10 seconds), the management server may experience high CPU utilization and packet-loss due to the sheer volume of incoming API traffic from hundreds of hypervisors.
THE TROUBLESHOOTING MATRIX
Section C: Logs & Debugging:
When a global setting change fails to take effect or causes a system crash, the primary log file is located at /var/log/cloudstack/management/management-server.log. Search for the string GlobalConfigDaoImpl to identify errors related to configuration loading. If a parameter is rejected, look for IllegalArgumentException in the stack trace.
For issues related to hypervisor communication after a setting change, inspect the agent logs on the host. On KVM hosts, the path is /var/log/cloudstack/agent/agent.log. Error codes such as “Host not ready” or “Failed to apply network rules” often correlate with misconfigured network.throttling.rate or guest.vlan.range settings. If the management server fails to start, verify the integrity of the configuration table by running CHECK TABLE configuration; within the MySQL shell to ensure no data corruption has occurred during manual edits.
OPTIMIZATION & HARDENING
– Performance Tuning: To increase concurrency during VM deployment, adjust vm.instantiate.wait and workers. Increasing the worker count allows the management server to process more simultaneous task payloads without increasing latency. Additionally, set api.throttling.enabled to true to prevent a single malfunctioning script from overwhelming the management server with API requests.
– Security Hardening: Ensure that ca.framework.enabled is set to true to enforce certificate-based authentication between the management server and agents. This mitigates man-in-the-middle attacks. Further, restrict the management.network.cidr to only include the subnets occupied by your management nodes and authorized administrative jump boxes.
– Scaling Logic: As the zone grows, the max.num.guest.vms per host must be audited. If the infrastructure expands across multiple geolocations, consider the pings.interval and pings.timeout settings. Increasing these values can prevent “flapping” host status in environments where inter-site latency is higher than 50ms, ensuring the orchestrator does not prematurely mark a host as down.
THE ADMIN DESK
How do I revert a global setting to its default?
Query the configuration table for the default_value column. Use cloudmonkey update configuration name=[setting] value=[original_default]. Then, restart the management service to clear the existing cache and reload the factory-defined parameter into memory.
Why is my new setting not appearing in the UI?
The UI often caches API responses for performance. Perform a hard refresh of your browser. If the value remains old, verify the change in the database. Ensure the systemctl restart cloudstack-management command was executed after manual SQL updates.
Can I apply settings to only one Cluster?
Yes. Many settings have a “Cluster” scope. When updating, specify the clusterid parameter in the API call. This allows for heterogeneous hardware configurations where one cluster may support higher overprovisioning than another within the same zone.
What setting controls the VM migration speed?
The vm.migration.speed setting dictates the maximum throughput available for live migrations. Adjusting this value is critical for managing thermal-inertia during host maintenance or avoiding packet-loss on migration networks that share bandwidth with storage traffic.
How do I troubleshoot a “Configuration value not found” error?
This error typically occurs if there is a syntax error in the SQL update or a typo in the cloudmonkey command. Verify the exact name of the variable in the name column of the configuration table. Names are case-sensitive.