About the KVMGuest agent


About the KVMGuest agent
Prev	Configuring VCS to manage virtual machines	Next

The KVMGuest agent enables Cluster Server (VCS) to monitor a KVM guest - that is, a virtual machine in the KVM environment or the Red Hat Enterprise Virtualization (RHEV) environment. The agent performs tasks such as bringing virtual machines online and taking them offline. The KVMGuest agent operates in both KVM and RHEV environments. This topic describes its behavior in the RHEV environment.

For details on the KVMGuest agent behavior in open source KVM environment or RHEV environment, see the Cluster Server Bundled Agents Reference Guide.

The KVMGuest agent uses virsh commands to manage virtual machines in the KVM environment and Representational State Transfer (REST) APIs to manage virtual machines in RHEV environment by using the REST APIs to determine the state of the virtual machine. The agent determines the resource state, on the basis of the virtual machine state. REST design architecture focuses on resources and their representations for some specific service. REST APIs help software developers and administrators integrate the functionality of the RHEV environment with custom scripts or with external applications which access the API by means of HTTP.

Prerequisites for administering virtual machines in a RHEV environment by using REST APIs:

A networked installation of Red Hat Enterprise Virtualization Manager, which includes the REST API
A client or programming library that initiates and receives HTTP requests from the REST API

The following table lists various states of a virtual machine in RHEV environment and the corresponding VCS resource state:

Table:

Virtual machine state	VCS resource state	Resource confidence level
wait_for_launch	ONLINE	10
powering_up	ONLINE	60
up	ONLINE	100
powering_down	ONLINE	40
paused	ONLINE	20
down	OFFLINE	-
saving_state	INTENTIONAL OFFLINE	-
suspended	INTENTIONAL OFFLINE	-
restoring_state	ONLINE	50
migrating	INTENTIONAL OFFLINE	-
reboot_in_progress	INTENTIONAL OFFLINE	-
image_locked	UNKNOWN	-
unknown	UNKNOWN	-

Table: KVMGuest agent functions

Function

Tasks

Online

KVM environment: Agent uses the virsh start command to start the guest virtual machine. When the resource is configured to define the guest configuration, agent uses the virsh define command to define the virtual machine while bringing it online.

RHEV environment: Agent uses the REST APIs to start the virtual machine. If the DROpts attribute is set to configure the guest network, the agent also sets the payload as a cdrom. This payload contains networking parameters to be set within the guest after a DR failover.

The agent waits for a certain time period after initiating the virtual machine start. You can specify this wait period by using the "DelayAfterGuestOnline" attribute.

The agent also checks whether the virtual machine is configured for disaster recovery by checking the DROpts attribute. If this attribute is set correctly, the agent inserts a virtual CDROM into the virtual machine's configuration. This CDROM contains a file that contains the site-specific network parameters to be applied at this site for the virtual machine. When the virtual machine boots, the vcs-net-reconfig service installed inside the guest checks for the CDROM and the disaster recovery information. If the vcs-net-reconfig service finds the disaster recovery information, the service applies the networking parameters to the virtual machine.

Offline

The Offline function initiates a graceful shutdown of the virtual machine.

KVM environment: Agent uses the virsh shutdown command to shutdown the guest virtual machine. If the SyncDir attribute is configured to synchronize the guest virtual machine configuration file, then the configuration file is copied to the location configured as a SyncDir attribute.

RHEV environment: Agent uses the REST APIs to shutdown the virtual machine.

The agents wait for a certain time period after initiating the shutdown for the virtual machine to shut down completely. You can specify this wait period by using the DelayAfterGuestOffline attribute.

Monitor

KVM environment: Agent uses the virsh domstate command to determine the status of the guest virtual machine.

RHEV environment: Agent uses the REST APIs to get the status of the virtual machine.

Clean

KVM environment: Agent uses the virsh destroy command to forcefully shutdown the guest virtual machine. If the SyncDir attribute is configured to synchronize the guest virtual machine configuration file, then the configuration file is copied to the location configured as a SyncDir attribute.

RHEV environment: Agent uses REST APIs to stop the virtual machine.

Migrate

KVM environment: The agent uses the virsh migrate command to start virtual machine migration.

RHEV environment: The agent uses REST APIs to start virtual machine migration. Additionally, it checks whether the virtual machine migration is allowed or not.

Note:

When a virtual machine is configured for disaster recovery, the virtual machine cannot be migrated across sites.

The KVMGuest agent recognizes the following resource states:

Table:

Resource state	Description
ONLINE	Indicates that the guest virtual machine is running.
OFFLINE	Indicates that the guest virtual machine has stopped.
FAULTED	Indicates that the guest virtual machine has failed to start or has unexpectedly stopped.
UNKNOWN	Indicates that a problem exists with the configuration or with the ability to monitor the resource.
INTENTIONAL OFFLINE	Indicates that the virtual machine has either migrated to another physical host or the administrator intentionally suspended it.

The Cluster Server agent for managing virtual machines in a KVM or RHEV environment, is represented by the KVMGuest resource type definition:

type KVMGuest (
        static int IntentionalOffline = 1
        static boolean AEPTimeout = 1
        static int MigrateTimeout = 300
        static int MigrateWaitLimit = 2
        static keylist SupportedActions = { "guestmigrated", "vmconfigsync", "DevScan" }
        static keylist SupportedOperations = { "migrate"}
        static keylist RegList = { "GuestName", "DelayAfterGuestOnline", "DelayAfterGuestOffline", "RHEVMInfo", "DROpts" }
        static str ArgList[] = { GuestName, DelayAfterGuestOnline, DelayAfterGuestOffline, SyncDir, GuestConfigFilePath, CEInfo, RHEVMInfo, ResyncVMCfg, DROpts }
        str CEInfo{} = { Enabled=0, CESystem=NONE, FaultOnHBLoss=1 }
        str RHEVMInfo{} = { Enabled=0, URL=NONE, User=NONE, Password=NONE, Cluster=NONE, UseManualRHEVMFencing=0 }
        str GuestName
        int DelayAfterGuestOnline = 5
        int DelayAfterGuestOffline = 30
        str SyncDir
        str GuestConfigFilePath
        boolean ResyncVMCfg = 0
        str DROpts{} = { ConfigureNetwork=0, IPAddress=NONE, Netmask=NONE, Gateway=NONE, DNSServers=NONE, DNSSearchPath=NONE, Device=NONE }
)

The RHEVMInfo attribute enables the KVMGuest attribute configuration to support the Red Hat Enterprise Virtualization environment. RHEVMInfo specifies the following information about the RHEV environment:

Attribute value	Description
Enabled	Specifies whether the virtualization environment is a KVM environment or a Red Hat Enterprise Virtualization (RHEV) environment. 0 indicates the KVM environment. 1 indicates the RHEV environment. The default value is 0.
URL	Specifies the RHEV-M URL, that the KVMGuest agent can use for REST API communication. The API can only communicate with the secure port (SSL). For example: https://rhevm-server.example.com:443
User	Specifies the RHEV-M user name that the agent must use for REST API communication. For example: admin@internal rhevadmin@example.com
Password	Specifies the encrypted password associated with the RHEVM user profile. The password should be encrypted using "vcsencrypt" command. To generate the encrypted password, run the following command: # `/opt/VRTSvcs/bin/vcsencrypt -agent plain_text_password`
Cluster	Specifies the name of the RHEV-M cluster of which the VCS host is a member.
UseManualRHEVMFencing	Specifies if the use of manual RHEV-M fencing is enabled in the event that the physical host on which virtual machine is running crashes. 0 indicates that manual RHEV-M fencing is disabled. 1 indicates that manual RHEV-M fencing is enabled. The default value is 0.

The DROpts attribute enables the virtual machine for disaster recovery. The attribute contains site-specific network parameters for the virtual machine. The value of this attribute consists of the following keys that define the disaster recovery options for the virtual machine:

Attribute keys	Description
DNSSearchPath	The domain search path used by the virtual machine in this site. The value of this key must contain a list of DNS domain names that are used for the DNS lookup of a hostname in case the domain name of the hostname is not specified. Use spaces to separate the domain names.
DNSServers	The list of DNS servers used by the virtual machine in this site. The value of this key must contain a list of IP addresses of DNS servers that are used for the DNS lookup of a hostname. Use spaces to separate the IP addresses.
Gateway	The default gateway used by the virtual machine in this site.
Device	The Network Interface Card (NIC) that is dedicated to the exclusive IP address of the virtual machine in this site. If this key is not specified, the agent automatically selects the first dedicated NIC for the assignment of the IP address, if specified. Example: eth0.
IPAddress	The IP address to be assigned to the virtual machine in this site after a cross-site failover.
Netmask	The netmask to be used by the virtual machine in this site after a cross-site failover.
ConfigureNetwork	The DROpts attribute value is applied to the virtual machine only if this key is set to 1. Type and dimension: string-association.

Note:

For information on other attributes associated with the KVMGuest agent, see the Cluster Server Bundled Agents Reference Guide.

Prev	Up	Next
How Cluster Server (VCS) manages virtual machines	Home	Validating the virtualization environment