[GitHub] [cloudstack-documentation] nvazquez commented on a diff in pull request #308: Add KVM Auto Enable-Disable Hosts docs

["nvazquez (via GitHub)" <gi...@apache.org>]

nvazquez commented on code in PR #308:
URL: https://github.com/apache/cloudstack-documentation/pull/308#discussion_r1150808717


##########
source/adminguide/hosts.rst:
##########
@@ -1003,3 +1003,51 @@ The management server iterates through hosts in each cluster on the selected sco
   - In case the post-maintenance script fails and the ‘forced’ parameter is not set, then the rolling maintenance process fails and an error is reported. If the ‘forced’ parameter is set, the host is skipped and the iteration continues with the next host in the cluster
 
 - Enable the cluster that has been disabled, after all the hosts in the cluster have been processed, or in case an error has occurred.
+
+
+KVM Auto Enable/Disable Hosts
+-----------------------------
+
+The cluster configuration 'enable.kvm.host.auto.enable.disable' (disabled by default) allows CloudStack to auto-disable and auto-enable KVM hosts resource state based on customisable host/hypervisor health checks.
+
+KVM hosts health checks
+~~~~~~~~~~~~~~~~~~~~~~~
+
+For each KVM agent on the cluster, the property 'agent.health.check.script.path' must be added to the agent.properties file, indicating the path of an executable file/script for host health check.
+
+.. note:: The health script runs every 'ping.interval' seconds on a KVM host.
+
+.. note:: The health script will need execution permissions on a KVM host.
+
+Depending on the exit code of the health script, the KVM agent will report the management server with the following results:
+
+- The health check result is true, if the script is executed successfully and the exit code is 0
+- The health check result is false, if the script is executed successfully and the exit code is 1
+- The health check result is null, if
+
+   - Script file is not specified, or
+   - Script file does not exist, or
+   - Script file is not accessible by the user of the cloudstack-agent process, or
+   - Script file is not executable, or
+   - There are errors when the script is executed (exit codes other than 0 or 1)
+
+Management Server actions based on health checks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The management server receives the health check results from the KVM agent, and takes the following actions:
+
+- If the host health check result is null, do nothing.
+- If the host health check result is true, enable the host resource state if it is Disabled.
+- If the host health check result is false, disable the host resource state if it is Enabled.
+
+On every automatic enable or disable event, the management server will send an alert to the admin and add an automatic annotation (comment) on the specific host.
+
+- If a host gets auto-disabled by a health check failure, then it can be auto-enabled when the health check succeeds. But if the host gets disabled by the admin, then it must not be auto-enabled when the health check succeeds (manual host disabling takes precedence over the auto-enabling of a host).
+- If a host gets auto-disabled by a health check failure, the admin could enable the host but unless they also disable the health check on the host then it will just get disabled again when the health check fails
+
+CloudStack controls when a host can/cannot be auto-enabled or auto-disabled by a host detail record (on the host_details table) with key ‘autoenablekvmhost’, in the following way:
+
+- If a host is auto-enabled or auto-disabled and there is no host detail with key ‘autoenablekvmhost’ for that host, then a new host detail record is created with the key ‘autoenablekvmhost’ and is set to ‘true’ (just before the host is auto-enabled/auto-disabled)
+- If the administrator manually disables a host and there is a host detail with key ‘autoenablekvmhost’ for that host, then the host detail ‘autoenablekvmhost’ is set to ‘false’ (indicating that the host cannot be auto-enabled if the health check succeeds)
+- If the administrator manually enables a host and there is a host detail with key ‘autoenablekvmhost’ for that host, then the host detail ‘autoenablekvmhost’ is set to ‘true’ (indicating that the host can be auto-disabled if the health check fails)
+- If the cluster setting 'enable.kvm.host.auto.enable.disable' is disabled, and the administrator enables/disables hosts in the cluster, then the host detail with key ‘autoenablekvmhost’ is not created for the hosts. (preserving the usual behavior). If the cluster setting is then enabled, and the administrator enables/disables the host manually then the host detail with key '‘autoenablekvmhost’ is created, and is set to false.

Review Comment:
   Great, this looks much clearer, incorporating changes



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@cloudstack.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org