XML Hook

Overview

An XML Hook is a script that can flexibly insert or modify parameters in XML files of VM instances. By attaching an XML Hook to a VM instance, you can customize VM configurations and enable specialized functionalities.

Figure 1. XML Hook

Advantages

The XML Hook feature provided by ZStack Cloud has the following advantages:

Flexibility
- ZStack Cloud manages XML Hooks as separate script files, helping separate temporary or customized configurations from the core logic code. By attaching/detaching XML Hooks to/from VM instances, you can dynamically adjust VM configurations without manually modifying core codes.
- On ZStack Cloud, XML Hooks can be stored long-term and reused. An XML Hook can be attached to multiple VM instances simultaneously, effectively improving O&M efficiency in large-scale scenarios.
Scalability
By defining and using XML Hooks, you can flexibly modify VM XML files, thus achieving configurations that cannot be directly completed through UI operations. This effectively extends the capabilities of VM instances and helps meet customized requirements, such as modifying QEMU custom parameters and disabling TSO for vNICs.

Considerations

To use XML Hooks, you must be familiar with VM instance configurations and XML Hook writing rules. If the XML Hook contains syntax errors or leads to configuration errors, the VM instances attached with this XML Hook fail to reboot or start.
If you need to upgrade the QEMU/Libvirt or a VM instance which has an XML Hook attached, confirm in advance whether the expected QEMU/Libvirt version is compatible with the XML Hook to prevent the VM reboot/start failure because of XML Hook incompatibility after the upgrade.

Inventory

Properties

Name	Description	Starting Version
uuid	The XML Hook UUID.	5.2.0
description	The detailed information of the XML Hook.	5.2.0
name	The XML Hook name.	5.2.0
hookScript	The XML Hook content.	5.2.0
libvirtVersion	The Libvirt version.	5.2.0
type	The XML Hook type.	5.2.0
createDate	The creation date. See Resource Property	5.2.0
lastOpDate	The last operation data. See Resource Property	5.2.0
tagUuid	The tag UUID list.	5.2.0
userTags	The user tags. For more information, see CreateUserTag.	5.2.0
systemTags	The system tags. For more information, see CreateSystemTag.	5.2.0
groupBy		5.2.0

Sample

{
    "inventories": [
        {
            "createDate": "Aug 29, 2024 2:08:10 PM",
            "hookScript": "ZGVm",
            "lastOpDate": "Aug 29, 2024 2:08:10 PM",
            "name": "test",
            "type": "Customization",
            "uuid": "38cb92040eb747e7835b7c50a803a9ed"
        }
    ],
    "success": true
}

Operations

CreateVmUserDefinedXmlHookScript

Create a custom XML Hook. For example,

CreateVmUserDefinedXmlHookScript name=hook hookScript=base64

Parameters

Name	Description	Optional	Starting Version
name	The XML Hook name.		5.2.0
description	The detailed information of XML Hook.	Yes	5.2.0
hookScript	The XML Hook content.		5.2.0
resourceUuid	The resource UUID.	Yes	5.2.0
tagUuids	The tag UUID list.	Yes	5.2.0
userTags	The user tags. For more information, see CreateUserTag.	Yes	5.2.0
systemTags	The system tags. For more information, see CreateSystemTag.	Yes	5.2.0
timeout		Yes

ExpungeVmUserDefinedXmlHookScript

Expunges a custom XML Hook. For example,

ExpungeVmUserDefinedXmlHookScript uuid=99df64f50f5b34c6be5a7339d676aeb6

Parameters

Name	Description	Optional	Starting Version
uuid	The XML Hook UUID.		5.2.0
userTags	The user tags. For more information, see CreateUserTag.	Yes	5.2.0
systemTags	The system tags. For more information, see CreateSystemTag.	Yes	5.2.0
timeout		Yes

QueryVmUserDefinedXmlHookScript

Queries a custom XML Hook. For example,

QueryVmUserDefinedXmlHookScript uuid=99df64f50f5b34c6be5a7339d676aeb6

Primitive Fields of Query

See XML Hook Inventory

UpdateVmUserDefinedXmlHookScript

Updates a custom XML Hook. For example,

UpdateVmUserDefinedXmlHookScript uuid=99df64f50f5b34c6be5a7339d676aeb6 name=example

Parameters

Name	Description	Optional	Valid Values	Starting Version
uuid	The XML Hook UUID.			5.2.0
name	The XML Hook name.	Yes		5.2.0
description	The detailed information of the XML Hook.	Yes		5.2.0
hookScript	The XML Hook content.	Yes		5.2.0
userTags	The user tags. For more information, see CreateUserTag.	Yes		5.2.0
systemTags	The system tags. For more information, see CreateSystemTag.	Yes		5.2.0
startupStrategy	Whether reboot associated VM instances immediately.		Reboot None	5.2.0
timeout		Yes

AttachUserDefinedXmlHookScriptToVm

Attaches an XML Hook to a VM instance. For example,

AttachUserDefinedXmlHookScriptToVm vmInstanceUuid=6baaffd8cb123dcc954b6242835267b9 xmlHookUuid=73300c2b203e3e43bc4b0dec7c3b0f21 startupStrategy=None

Parameters

Name	Description	Optional	Valid Values	Starting Version
vmInstanceUuid	The VM instance UUID.			5.2.0
xmlHookUuid	The XML Hook UUID.			5.2.0
startupStrategy	Whether reboot the VM instance immediately.	Yes	Reboot None	5.2.0
userTags	The user tags. For more information, see CreateUserTag.	是		5.2.0
systemTags	The system tags. For more information, see CreateSystemTag.	是		5.2.0
timeout		是

DetachUserDefinedXmlHookScriptFromVm

Detaches an XML Hook from a VM instance. For example,

DetachUserDefinedXmlHookScriptFromVm vmInstanceUuid=6baaffd8cb123dcc954b6242835267b9 startupStrategy=None deleteMode=Permissive

Parameters

Name	Description	Optional	Valid Values	Starting Version
vmInstanceUuid	The VM instance UUID.			5.2.0
startupStrategy	Whether rebbot the VM instance immediately	Yes	Reboot None	5.2.0
deleteMode	The deletion mode.	Yes	Permissive Enforcing，Permissive	5.2.0
userTags	The user tags. For more information, see CreateUserTag.	Yes		5.2.0
systemTags	The system tags. For more information, see CreateSystemTag.	Yes		5.2.0
timeout		Yes

PreviousScript Library NextJob Scheduling