Merge pull request #34709 from sjhala-ccs/BZ-1901643

sjhala-ccs · web-flow · commit 96eead4c3489 · 2021-08-16T14:31:58.000-04:00
BZ-1901643: Updated Monitoring VM health assembly
diff --git a/modules/virt-about-liveness-readiness-probes.adoc b/modules/virt-about-liveness-readiness-probes.adoc
diff --git a/modules/virt-about-readiness-liveness-probes.adoc b/modules/virt-about-readiness-liveness-probes.adoc
@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc
+
+[id="virt-about-readiness-liveness-probes_{context}"]
+
+= About readiness and liveness probes
+
+Use readiness and liveness probes to detect and handle unhealthy virtual machine instances (VMIs). You can include one or more probes in the specification of the VMI to ensure that traffic does not reach a VMI that is not ready for it and that a new instance is created when a VMI becomes unresponsive.
+
+A _readiness probe_ determines whether a VMI is ready to accept service requests. If the probe fails, the VMI is removed from the list of available endpoints until the VMI is ready.
+
+A _liveness probe_ determines whether a VMI is responsive. If the probe fails, the VMI is deleted and a new instance is created to restore responsiveness.
+
+You can configure readiness and liveness probes by setting the `spec.readinessProbe` and the `spec.livenessProbe` fields of the `VirtualMachineInstance` object. These fields support the following tests:
+
+HTTP GET:: The probe determines the health of the VMI by using a web hook. The test is successful if the HTTP response code is between 200 and 399. You can use an HTTP GET test with applications that return HTTP status codes when they are completely initialized.
+
+TCP socket:: The probe attempts to open a socket to the VMI. The VMI is only considered healthy if the probe can establish a connection. You can use a TCP socket test with applications that do not start listening until initialization is complete.
diff --git a/modules/virt-define-http-liveness-probe.adoc b/modules/virt-define-http-liveness-probe.adoc
@@ -4,74 +4,43 @@
 
 [id="virt-define-http-liveness-probe_{context}"]
 
-= Define an HTTP liveness probe
+= Defining an HTTP liveness probe
+
+Define an HTTP liveness probe by setting the `spec.livenessProbe.httpGet` field of the virtual machine instance (VMI) configuration. You can define both HTTP and TCP tests for liveness probes in the same way as readiness probes. This procedure configures a sample liveness probe with an HTTP GET test.
 
-This procedure provides an example configuration file for defining HTTP
-liveness probes.
 
 .Procedure
 
-. Customize a YAML configuration file to create an HTTP liveness probe, using
-the following code block as an example. In this example:
-+
---
-* You configure a probe using `spec.livenessProbe.httpGet`, which queries port `1500` of the virtual machine instance, after an initial delay of `120` seconds.
-* The virtual machine instance installs and runs a minimal HTTP server
-on port `1500` using `cloud-init`.
---
-+
-[NOTE]
-====
-The `timeoutSeconds` value must be lower than the `periodSeconds` value. The `timeoutSeconds` default value is `1`. The `periodSeconds` default value is `10`.
-====
+. Include details of the HTTP liveness probe in the VMI configuration file.
 +
+
+.Sample liveness probe with an HTTP GET test
 [source,yaml]
 ----
-apiVersion: kubevirt.io/v1alpha3
-kind: VirtualMachineInstance
-metadata:
-  labels:
-    special: vmi-fedora
-  name: vmi-fedora
+...
 spec:
-  domain:
-    devices:
-      disks:
-      - disk:
-          bus: virtio
-        name: containerdisk
-      - disk:
-          bus: virtio
-        name: cloudinitdisk
-    resources:
-      requests:
-        memory: 1024M
   livenessProbe:
-    initialDelaySeconds: 120
-    periodSeconds: 20
-    httpGet:
-      port: 1500
-    timeoutSeconds: 10
-  terminationGracePeriodSeconds: 0
-  volumes:
-  - name: containerdisk
-    registryDisk:
-      image: kubevirt/fedora-cloud-registry-disk-demo
-  - cloudInitNoCloud:
-      userData: |-
-        #cloud-config
-        password: fedora
-        chpasswd: { expire: False }
-        bootcmd:
-          - setenforce 0
-          - dnf install -y nmap-ncat
-          - systemd-run --unit=httpserver nc -klp 1500 -e '/usr/bin/echo -e HTTP/1.1 200 OK\\n\\nHello World!'
-    name: cloudinitdisk
+    initialDelaySeconds: 120 <1>
+    periodSeconds: 20 <2>
+    httpGet: <3>
+      port: 1500 <4>
+      path: /healthz <5>
+        httpHeaders:
+        - name: Custom-Header
+          value: Awesome
+    timeoutSeconds: 10 <6>
+...
 ----
-+
-. Create the virtual machine instance by running the following command:
+<1> The time, in seconds, after the VMI starts before the liveness probe is initiated.
+<2> The delay, in seconds, between performing probes. The default delay is 10 seconds. This value must be greater than `timeoutSeconds`.
+<3> The HTTP GET request to perform to connect to the VMI.
+<4> The port of the VMI that the probe queries. In the above example, the probe queries port 1500. The VMI installs and runs a minimal HTTP server on port 1500 via cloud-init.
+<5> The path to access on the HTTP server. In the above example, if the handler for the server's `/healthz` path returns a success code, the VMI is considered to be healthy. If the handler returns a failure code, the VMI is deleted and a new instance is created.
+<6> The number of seconds of inactivity after which the probe times out and the VMI is assumed to have failed. The default value is 1. This value must be lower than `periodSeconds`.
+
+. Create the VMI by running the following command:
 +
 [source,terminal]
 ----
-$ oc create -f <file name>.yaml
+$ oc create -f <file_name>.yaml
 ----
diff --git a/modules/virt-define-http-readiness-probe.adoc b/modules/virt-define-http-readiness-probe.adoc
@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc
+
+[id="virt-define-http-readiness-probe_{context}"]
+
+= Defining an HTTP readiness probe
+
+Define an HTTP readiness probe by setting the `spec.readinessProbe.httpGet` field of the virtual machine instance (VMI) configuration.
+
+
+.Procedure
+. Include details of the readiness probe in the VMI configuration file.
++
+
+.Sample readiness probe with an HTTP GET test
+[source,yaml]
+----
+...
+spec:
+  readinessProbe:
+    httpGet: <1>
+      port: 1500 <2>
+      path: /healthz <3>
+        httpHeaders:
+        - name: Custom-Header
+          value: Awesome
+    initialDelaySeconds: 120 <4>
+    periodSeconds: 20 <5>
+    timeoutSeconds: 10 <6>
+    failureThreshold: 3 <7>
+    successThreshold: 3 <8>
+...
+----
+<1> The HTTP GET request to perform to connect to the VMI.
+<2> The port of the VMI that the probe queries. In the above example, the probe queries port 1500.
+<3> The path to access on the HTTP server. In the above example, if the handler for the server’s /healthz path returns a success code, the VMI is considered to be healthy. If the handler returns a failure code, the VMI is removed from the list of available endpoints.
+<4> The time, in seconds, after the VMI starts before the readiness probe is initiated.
+<5> The delay, in seconds, between performing probes. The default delay is 10 seconds. This value must be greater than `timeoutSeconds`.
+<6> The number of seconds of inactivity after which the probe times out and the VMI is assumed to have failed. The default value is 1. This value must be lower than `periodSeconds`.
+<7> The number of times that the probe is allowed to fail. The default is 3. After the specified number of attempts, the pod is marked `Unready`.
+<8> The number of times that the probe must report success, after a failure, to be considered successful. The default is 1.
+
+. Create the VMI by running the following command:
++
+[source,terminal]
+----
+$ oc create -f <file_name>.yaml
+----
diff --git a/modules/virt-define-readiness-probe.adoc b/modules/virt-define-readiness-probe.adoc
diff --git a/modules/virt-define-tcp-readiness-probe.adoc b/modules/virt-define-tcp-readiness-probe.adoc
@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc
+
+[id="virt-define-tcp-readiness-probe_{context}"]
+
+= Defining a TCP readiness probe
+
+Define a TCP readiness probe by setting the `spec.readinessProbe.tcpSocket` field of the virtual machine instance (VMI) configuration.
+
+
+.Procedure
+
+. Include details of the TCP readiness probe in the VMI configuration file.
++
+
+.Sample readiness probe with a TCP socket test
+[source,yaml]
+----
+...
+spec:
+  readinessProbe:
+    initialDelaySeconds: 120 <1>
+    periodSeconds: 20 <2>
+    tcpSocket: <3>
+      port: 1500 <4>
+    timeoutSeconds: 10 <5>
+...
+----
+<1> The time, in seconds, after the VMI starts before the readiness probe is initiated.
+<2> The delay, in seconds, between performing probes. The default delay is 10 seconds. This value must be greater than `timeoutSeconds`.
+<3> The TCP action to perform.
+<4> The port of the VMI that the probe queries.
+<5> The number of seconds of inactivity after which the probe times out and the VMI is assumed to have failed. The default value is 1. This value must be lower than `periodSeconds`.
+
+. Create the VMI by running the following command:
++
+[source,terminal]
+----
+$ oc create -f <file_name>.yaml
+----
diff --git a/modules/virt-template-vmi-probe-config.adoc b/modules/virt-template-vmi-probe-config.adoc
@@ -2,29 +2,9 @@
 //
 // * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc
 
-[id="virt-define-tcp-liveness-probe_{context}"]
+[id="virt-template-vmi-probe-config_{context}"]
+= Template: Virtual machine instance configuration file for defining health checks
 
-= Define a TCP liveness probe
-
-This procedure provides an example configuration file for defining
-TCP liveness probes.
-
-.Procedure
-
-. Customize a YAML configuration file to create an TCP liveness probe, using
-this code block as an example. In this example:
-+
---
-* You configure a probe using `spec.livenessProbe.tcpSocket`, which queries port `1500` of the virtual machine instance, after an initial delay of `120` seconds.
-* The virtual machine instance installs and runs a minimal HTTP server
-on port `1500` using `cloud-init`.
---
-+
-[NOTE]
-====
-The `timeoutSeconds` value must be lower than the `periodSeconds` value. The `timeoutSeconds` default value is `1`. The `periodSeconds` default value is `10`.
-====
-+
 [source,yaml]
 ----
 apiVersion: kubevirt.io/v1alpha3
@@ -46,16 +26,18 @@ spec:
     resources:
       requests:
         memory: 1024M
-  livenessProbe:
+  readinessProbe:
+    httpGet:
+      port: 1500
     initialDelaySeconds: 120
     periodSeconds: 20
-    tcpSocket:
-      port: 1500
     timeoutSeconds: 10
+    failureThreshold: 3
+    successThreshold: 3
   terminationGracePeriodSeconds: 0
   volumes:
   - name: containerdisk
-    registryDisk:
+    containerDisk:
       image: kubevirt/fedora-cloud-registry-disk-demo
   - cloudInitNoCloud:
       userData: |-
@@ -68,10 +50,3 @@ spec:
           - systemd-run --unit=httpserver nc -klp 1500 -e '/usr/bin/echo -e HTTP/1.1 200 OK\\n\\nHello World!'
     name: cloudinitdisk
 ----
-+
-. Create the virtual machine instance by running the following command:
-+
-[source,terminal]
-----
-$ oc create -f <file name>.yaml
-----
diff --git a/virt/logging_events_monitoring/virt-monitoring-vm-health.adoc b/virt/logging_events_monitoring/virt-monitoring-vm-health.adoc
@@ -5,10 +5,15 @@ include::modules/virt-document-attributes.adoc[]
 
 toc::[]
 
-Use this procedure to create liveness and readiness probes
-to monitor virtual machine health.
+A virtual machine instance (VMI) can become unhealthy due to transient issues such as connectivity loss, deadlocks, or problems with external dependencies. A health check periodically performs diagnostics on a VMI by using any combination of the readiness and liveness probes.
 
-include::modules/virt-about-liveness-readiness-probes.adoc[leveloffset=+1]
+include::modules/virt-about-readiness-liveness-probes.adoc[leveloffset=+1]
+include::modules/virt-define-http-readiness-probe.adoc[leveloffset=+1]
+include::modules/virt-define-tcp-readiness-probe.adoc[leveloffset=+1]
 include::modules/virt-define-http-liveness-probe.adoc[leveloffset=+1]
-include::modules/virt-define-tcp-liveness-probe.adoc[leveloffset=+1]
-include::modules/virt-define-readiness-probe.adoc[leveloffset=+1]
+include::modules/virt-template-vmi-probe-config.adoc[leveloffset=+1]
+
+[id="additional-resources_monitoring-vm-health"]
+== Additional resources
+
+* xref:../../applications/application-health.adoc#application-health[Monitoring application health by using health checks]
