From a06d06d0388477c42d070fc994e39c754c3bbe67 Mon Sep 17 00:00:00 2001 From: vishesh92 Date: Fri, 19 Sep 2025 13:26:34 +0530 Subject: [PATCH 1/3] Document User Data support for System VMs --- source/adminguide/systemvm.rst | 40 ++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst index 368f05d490..664a38597f 100644 --- a/source/adminguide/systemvm.rst +++ b/source/adminguide/systemvm.rst @@ -944,6 +944,46 @@ System VMs (any of the Console Proxy VM, Secondary Storage VM, Virtual Router or Since CloudStack 4.16, for VMware, migration of System VMs can also be done to a destination host in a different cluster belonging to the same pod (in case of cluster-wide primary storage pools, this will cause the Root volume of the system VM to be migrated to the appropriate datastore in the new cluster). Storage migration of stopped System VMs is also supported. +Customizing System VMs +---------------------- + +CloudStack supports User Data for System VMs at boot time. +The default root administrator can supply initialization scripts or configuration to automate tasks +such as installing additional packages, setting environment variables, or configuring telemetry. +Ensure that the User Data is valid for cloud-init. +Invalid content may prevent a System VM from functioning correctly. + +Initialization is performed by a CloudStack service, not by the systemd +cloud-init unit, to avoid conflicts with CloudStack System VM services. + +.. warning:: + User Data offers powerful customization, but inappropriate or intrusive scripts can + destabilize or break System VMs. Avoid modifying critical services or networking unless + you fully understand the impact, and always test changes in a non-production environment + before rollout. + +To enable and configure User Data for System VMs: + +#. Create a User Data entry under the default root administrator account. +#. Set the global setting ``systemvm.userdata.enabled`` to ``true``. +#. Provide the ID of the User Data per System VM type using the following global settings: + + .. cssclass:: table-striped table-bordered table-hover + ================================= ============================================================ + Global Setting Description + ================================= ============================================================ + ``consoleproxy.userdata`` ID of the User Data for Console Proxy VMs + ``secondarystorage.userdata`` ID of the User Data for Secondary Storage VMs + ``router.userdata`` ID of the User Data for Virtual Routers, + VPC VR, internal LB Instances, and elastic LB Instances + ================================= ============================================================ + +#. Destroy the System VMs and allow CloudStack to re-deploy them to apply the changes. + +.. note:: + Only the default root administrator can set the global settings for System VM User Data. + The associated User Data entries must also be created under the default root administrator account. + Troubleshoot networks from System VMs ------------------------------------- .. |run-diagnostics-icon.png| image:: /_static/images/run-diagnostics-icon.png From ee33b7b13a3b7c418131255e3016bf895a063954 Mon Sep 17 00:00:00 2001 From: vishesh92 Date: Wed, 1 Oct 2025 14:22:55 +0530 Subject: [PATCH 2/3] Add note for userdata limits for systemvm --- source/adminguide/systemvm.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst index 664a38597f..07cf69b8d6 100644 --- a/source/adminguide/systemvm.rst +++ b/source/adminguide/systemvm.rst @@ -984,6 +984,22 @@ To enable and configure User Data for System VMs: Only the default root administrator can set the global settings for System VM User Data. The associated User Data entries must also be created under the default root administrator account. +.. note:: + The size of the User Data that can be sent is dependent on the + hypervisor. This is because of the way it is provided to the system VM. + The user data is compressed and encoded in base64 format when it is + provided to the system VM along with other system VM configurations. + + - KVM: Uses QEMU Guest Agent to write configuration directly to + ``/var/cache/cloud/cmdline`` inside the VM + + - XenServer (HVM): Stores in XenStore key ``vm-data/cloudstack/init`` + + - VMware: Sets as ``machine.id`` extraConfig parameter + + The operator needs to ensure that the user data is within the limits + of the hypervisor. + Troubleshoot networks from System VMs ------------------------------------- .. |run-diagnostics-icon.png| image:: /_static/images/run-diagnostics-icon.png From c942a865acd1985551736f1215013dc4e37e08ce Mon Sep 17 00:00:00 2001 From: vishesh92 Date: Tue, 7 Oct 2025 13:27:20 +0530 Subject: [PATCH 3/3] Change global settings name --- source/adminguide/systemvm.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst index 07cf69b8d6..7a035485da 100644 --- a/source/adminguide/systemvm.rst +++ b/source/adminguide/systemvm.rst @@ -969,14 +969,14 @@ To enable and configure User Data for System VMs: #. Provide the ID of the User Data per System VM type using the following global settings: .. cssclass:: table-striped table-bordered table-hover - ================================= ============================================================ + ================================= ========================================================= Global Setting Description - ================================= ============================================================ - ``consoleproxy.userdata`` ID of the User Data for Console Proxy VMs - ``secondarystorage.userdata`` ID of the User Data for Secondary Storage VMs - ``router.userdata`` ID of the User Data for Virtual Routers, - VPC VR, internal LB Instances, and elastic LB Instances - ================================= ============================================================ + ================================= ========================================================= + ``console.proxy.vm.userdata`` ID of the User Data for Console Proxy VMs + ``secstorage.vm.userdata`` ID of the User Data for Secondary Storage VMs + ``virtual.router.userdata`` ID of the User Data for Virtual Routers, VPC VR, + internal LB Instances, and elastic LB Instances + ================================= ========================================================= #. Destroy the System VMs and allow CloudStack to re-deploy them to apply the changes.