feat(vm_healthcheck): add VM health validation role

CODE_OF_CONDUCT.md

@@ -1,4 +1,3 @@
 # Community Code of Conduct
 
-Please see the official
-[Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).
+Please see the official [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).

CONTRIBUTING.md

@@ -1,13 +1,27 @@
-# Welcome to the Ansible for OpenShift Virtualization Migration collection!
+# WELCOME TO ANSIBLE GITHUB
 
-Please check our [Contributor's Guide](https://github.com/redhat-cop/openshift-virtualization-migration-documentation/blob/main/CONTRIBUTING.md).
+Hi! Nice to see you here!
 
-The [documentation repository](https://github.com/redhat-cop/openshift-virtualization-migration-documentation) contains information on how to get started, links to other resources, deployment guides and more.
+## QUESTIONS ?
 
-## Using Red Hat Developer Sandbox
+Please see the [Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) for information on how to ask questions on the [mailing lists](https://docs.ansible.com/ansible/latest/community/communication.html#mailing-list-information) and IRC.
 
-NOTE: As this repository is currently not public you will need to create a personal access token and add that to your Developer Sandbox profile. Please perform the steps in the contribution guide [Using Red Hat Developer Sandbox](https://github.com/redhat-cop/openshift-virtualization-migration-documentation/blob/main/CONTRIBUTING.md#contribute-using-red-hat-developer-sandbox) section.
+The GitHub issue tracker is not the best place for questions for various reasons, but both IRC and the mailing list are very helpful places for those things, as the community page explains best.
 
-Click the link below to launch your IDE hosted in the Developer Sandbox:
+## CONTRIBUTING ?
 
-[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://workspaces.openshift.com/f?url=https://github.com/redhat-cop/openshift_virtualization_migration/openshift_virtualization_migration.git)
+By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution.
+
+You can read more about the [DCO and Contributor License Agreements](https://docs.ansible.com/ansible/latest/community/collection_contributors/collection_requirements.html#contributor-license-agreements) on the Ansible docsite.
+
+Please review the [Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) for more information on contributing to Ansible.
+
+## BUG TO REPORT ?
+
+First and foremost, also check the [Community Guide](https://docs.ansible.com/ansible/latest/community/index.html).
+
+You can report bugs or make enhancement requests at the [Ansible GitHub issue page](http://github.com/ansible/ansible/issues/new/choose) by filling out the issue template that will be presented.
+
+Also please make sure you are testing on the latest released version of Ansible or the development branch; see the [Installation Guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) for details.
+
+Thanks!

SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+Ansible applies security fixes according to the 3-versions-back support
+policy. Please find more information in [our docs](
+https://docs.ansible.com/ansible/devel/reference_appendices/release_and_maintenance.html#release-status
+).
+
+## Reporting a Vulnerability
+
+We encourage responsible disclosure practices for security
+vulnerabilities. Please read our [policies for reporting bugs](
+https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#reporting-a-bug
+) if you want to report a security issue that might affect Ansible.

playbooks/vm_healthcheck.yml

@@ -0,0 +1,15 @@
+---
+- name: Run VM Healthchecks
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  tasks:
+    - name: Invoke VM Healthcheck Role
+      ansible.builtin.include_role:
+        name: infra.openshift_virtualization_ops.vm_healthcheck
+        tasks_from: _healthcheck.yml
+      vars:
+        openshift_host: "{{ lookup('ansible.builtin.env', 'K8S_AUTH_HOST', default=Undefined) | default('', True) }}"
+        openshift_api_key: "{{ lookup('ansible.builtin.env', 'K8S_AUTH_API_KEY', default=Undefined) | default('', True) }}" # noqa: yaml[line-length]
+        openshift_verify_ssl: "{{ lookup('ansible.builtin.env', 'K8S_AUTH_VERIFY_SSL', default='') | default(false) | bool }}" # noqa: yaml[line-length]
+...

roles/vm_healthcheck/README.md

@@ -0,0 +1,92 @@
+<!-- STATIC CONTENT START
+Use this section for adding additional content to the README
+This will not be overwritten by Docsible -->
+# Role overview
+
+This role performs health validation checks on Virtual Machines running in OpenShift Virtualization.
+It verifies VM status, networking, storage, and resource configuration, and generates an HTML report
+summarizing the results.
+
+## Checks performed
+
+- **Status**: VM phase (Running), Ready condition, guest agent presence, node assignment
+- **Networking**: Interface IP assignment, interface name consistency, masquerade pod network, bridge/multus attachment
+- **Storage**: PVC bound status, DataVolume succeeded status, volume attachment verification
+- **Resources**: CPU/memory requests vs limits, node capacity, overcommit detection
+
+## Usage
+
+```yaml
+---
+- name: Run VM healthchecks
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  roles:
+    - role: infra.openshift_virtualization_ops.vm_healthcheck
+      vars:
+        vm_healthcheck_namespace: my-vms
+        vm_healthcheck_vm_names:
+          - my-vm-01
+          - my-vm-02
+        vm_healthcheck_report_path: /tmp/vm_healthcheck_report.html
+```
+
+Individual check categories can be disabled:
+
+```yaml
+vm_healthcheck_check_networking: false
+vm_healthcheck_check_storage: false
+vm_healthcheck_check_resources: false
+vm_healthcheck_generate_report: false
+```
+
+<!-- STATIC CONTENT END -->
+<!-- Everything below will be overwritten by Docsible -->
+<!-- DOCSIBLE START -->
+## vm_healthcheck
+
+```
+Role belongs to infra/openshift_virtualization_ops
+Namespace - infra
+Collection - openshift_virtualization_ops
+Version - 1.0.2
+Repository - https://github.com/redhat-cop/openshift_virtualization_ops
+```
+
+Description: Health validation and status reporting for Virtual Machines.
+
+### Defaults
+
+**These are static variables with lower priority**
+
+#### File: defaults/main.yml
+
+| Var          | Type         | Value       |Required    | Title       |
+|--------------|--------------|-------------|-------------|-------------|
+| [`vm_healthcheck_namespace`](defaults/main.yml#L4)   | str   | `""` |   True  |  Target namespace |
+| [`vm_healthcheck_vm_names`](defaults/main.yml#L9)   | list   | `[]` |   False  |  List of VM names |
+| [`vm_healthcheck_check_networking`](defaults/main.yml#L14)   | bool   | `true` |   False  |  Check networking |
+| [`vm_healthcheck_check_storage`](defaults/main.yml#L19)   | bool   | `true` |   False  |  Check storage |
+| [`vm_healthcheck_check_resources`](defaults/main.yml#L24)   | bool   | `true` |   False  |  Check resources |
+| [`vm_healthcheck_generate_report`](defaults/main.yml#L29)   | bool   | `true` |   False  |  Generate report |
+| [`vm_healthcheck_report_path`](defaults/main.yml#L34)   | str   | `/tmp/vm_healthcheck_report.html` |   False  |  Report output path |
+| [`vm_healthcheck_kubevirt_api_version`](defaults/main.yml#L39)   | str   | `kubevirt.io/v1` |   True  |  KubeVirt API Version |
+| [`vm_healthcheck_cdi_api_version`](defaults/main.yml#L44)   | str   | `cdi.kubevirt.io/v1beta1` |   True  |  CDI API Version |
+| [`vm_healthcheck_openshift_host`](defaults/main.yml#L49)   | str   | `{{ openshift_host }}` |   True  |  OpenShift host |
+| [`vm_healthcheck_openshift_api_key`](defaults/main.yml#L53)   | str   | `{{ openshift_api_key }}` |   True  |  OpenShift API Key |
+| [`vm_healthcheck_openshift_verify_ssl`](defaults/main.yml#L57)   | str   | `{{ openshift_verify_ssl }}` |   True  |  Enable SSL Verification |
+
+## Author Information
+
+OpenShift Virtualization Migration Contributors
+
+## License
+
+GPL-3.0-only
+
+## Minimum Ansible Version
+
+2.15.0
+
+<!-- DOCSIBLE END -->

roles/vm_healthcheck/defaults/main.yml

@@ -0,0 +1,62 @@
+---
+# defaults file for vm_healthcheck
+# title: Target namespace
+# required: True
+# description: Namespace containing VMs to healthcheck
+vm_healthcheck_namespace: ""
+
+# title: List of VM names
+# required: False
+# description: List of VM names to check. If empty, all VMs in namespace are checked
+vm_healthcheck_vm_names: []
+
+# title: Check networking
+# required: False
+# description: Whether to run networking health checks
+vm_healthcheck_check_networking: true
+
+# title: Check storage
+# required: False
+# description: Whether to run storage health checks
+vm_healthcheck_check_storage: true
+
+# title: Check resources
+# required: False
+# description: Whether to run resource utilization checks
+vm_healthcheck_check_resources: true
+
+# title: Generate report
+# required: False
+# description: Whether to generate an HTML healthcheck report
+vm_healthcheck_generate_report: true
+
+# title: Report output path
+# required: False
+# description: File path for the generated HTML healthcheck report
+vm_healthcheck_report_path: "/tmp/vm_healthcheck_report.html"
+
+# title: KubeVirt API Version
+# required: True
+# description: KubeVirt API Version
+vm_healthcheck_kubevirt_api_version: kubevirt.io/v1
+
+# title: CDI API Version
+# required: True
+# description: CDI API Version for DataVolume lookups
+vm_healthcheck_cdi_api_version: cdi.kubevirt.io/v1beta1
+
+# title: OpenShift host
+# required: True
+# description: OpenShift host
+vm_healthcheck_openshift_host: "{{ openshift_host }}"
+
+# title: OpenShift API Key
+# required: True
+# description: OpenShift API Key
+vm_healthcheck_openshift_api_key: "{{ openshift_api_key }}"
+
+# title: Enable SSL Verification
+# required: True
+# description: Variable to enable SSL verification
+vm_healthcheck_openshift_verify_ssl: "{{ openshift_verify_ssl }}"
+...

roles/vm_healthcheck/meta/main.yml

@@ -0,0 +1,10 @@
+---
+galaxy_info:
+  author: ""
+  description: Health validation and status reporting for Virtual Machines.
+  company: ""
+  license: GPL-3.0-only
+  min_ansible_version: 2.15.0
+  galaxy_tags: []
+dependencies: []
+...

roles/vm_healthcheck/tasks/_healthcheck.yml

@@ -0,0 +1,100 @@
+---
+
+- name: _healthcheck | Verify Required Parameters
+  ansible.builtin.assert:
+    that:
+      - vm_healthcheck_namespace | default("", true) | length > 0
+      - vm_healthcheck_openshift_host | default("", true) | length > 0
+      - vm_healthcheck_openshift_api_key | default("", true) | length > 0
+    quiet: true
+    fail_msg: "Required parameters not provided: namespace, openshift_host, and openshift_api_key are required"
+
+- name: _healthcheck | Initialize Healthcheck Results
+  ansible.builtin.set_fact:
+    vm_healthcheck_results: []
+
+- name: _healthcheck | Discover VMs in Namespace
+  kubernetes.core.k8s_info:
+    api_key: "{{ vm_healthcheck_openshift_api_key }}"
+    host: "{{ vm_healthcheck_openshift_host }}"
+    api_version: "{{ vm_healthcheck_kubevirt_api_version }}"
+    kind: VirtualMachine
+    namespace: "{{ vm_healthcheck_namespace }}"
+    validate_certs: "{{ vm_healthcheck_openshift_verify_ssl }}"
+  register: _vm_healthcheck_all_vms
+  when: vm_healthcheck_vm_names | length == 0
+
+- name: _healthcheck | Discover Named VMs
+  kubernetes.core.k8s_info:
+    api_key: "{{ vm_healthcheck_openshift_api_key }}"
+    host: "{{ vm_healthcheck_openshift_host }}"
+    api_version: "{{ vm_healthcheck_kubevirt_api_version }}"
+    kind: VirtualMachine
+    namespace: "{{ vm_healthcheck_namespace }}"
+    name: "{{ __vm_healthcheck_vm_name }}"
+    validate_certs: "{{ vm_healthcheck_openshift_verify_ssl }}"
+  register: _vm_healthcheck_named_vms
+  loop: "{{ vm_healthcheck_vm_names }}"
+  loop_control:
+    loop_var: __vm_healthcheck_vm_name
+
+- name: _healthcheck | Build VM List
+  ansible.builtin.set_fact:
+    _vm_healthcheck_vms: >-
+      {{
+        _vm_healthcheck_all_vms.resources | default([])
+        if vm_healthcheck_vm_names | length == 0
+        else _vm_healthcheck_named_vms.results | default([]) | map(attribute='resources') | flatten
+      }}
+
+- name: _healthcheck | Verify VMs Found
+  ansible.builtin.assert:
+    that:
+      - _vm_healthcheck_vms | length > 0
+    quiet: true
+    fail_msg: "No VMs found in namespace {{ vm_healthcheck_namespace }}"
+
+- name: _healthcheck | Run VM Status Checks
+  ansible.builtin.include_tasks:
+    file: vm_status.yml
+  loop: "{{ _vm_healthcheck_vms }}"
+  loop_control:
+    loop_var: __vm_healthcheck_vm
+    label: "{{ __vm_healthcheck_vm.metadata.name }}"
+
+- name: _healthcheck | Run Networking Checks
+  ansible.builtin.include_tasks:
+    file: vm_networking.yml
+  loop: "{{ _vm_healthcheck_vms }}"
+  loop_control:
+    loop_var: __vm_healthcheck_vm
+    label: "{{ __vm_healthcheck_vm.metadata.name }}"
+  when: vm_healthcheck_check_networking | bool
+
+- name: _healthcheck | Run Storage Checks
+  ansible.builtin.include_tasks:
+    file: vm_storage.yml
+  loop: "{{ _vm_healthcheck_vms }}"
+  loop_control:
+    loop_var: __vm_healthcheck_vm
+    label: "{{ __vm_healthcheck_vm.metadata.name }}"
+  when: vm_healthcheck_check_storage | bool
+
+- name: _healthcheck | Run Resource Checks
+  ansible.builtin.include_tasks:
+    file: vm_resources.yml
+  loop: "{{ _vm_healthcheck_vms }}"
+  loop_control:
+    loop_var: __vm_healthcheck_vm
+    label: "{{ __vm_healthcheck_vm.metadata.name }}"
+  when: vm_healthcheck_check_resources | bool
+
+- name: _healthcheck | Generate Healthcheck Report
+  ansible.builtin.include_tasks:
+    file: report.yml
+  when: vm_healthcheck_generate_report | bool
+
+- name: _healthcheck | Display Healthcheck Summary
+  ansible.builtin.debug:
+    msg: "Healthcheck complete: {{ vm_healthcheck_results | selectattr('status', 'equalto', 'pass') | list | length }} passed, {{ vm_healthcheck_results | selectattr('status', 'equalto', 'fail') | list | length }} failed" # noqa: yaml[line-length]
+...

roles/vm_healthcheck/tasks/main.yml

@@ -0,0 +1,3 @@
+---
+# tasks file for vm_healthcheck
+...

roles/vm_healthcheck/tasks/report.yml

@@ -0,0 +1,24 @@
+---
+
+- name: report | Build Summary Statistics
+  ansible.builtin.set_fact:
+    _vm_healthcheck_summary:
+      total_checks: "{{ vm_healthcheck_results | length }}"
+      passed: "{{ vm_healthcheck_results | selectattr('status', 'equalto', 'pass') | list | length }}"
+      failed: "{{ vm_healthcheck_results | selectattr('status', 'equalto', 'fail') | list | length }}"
+      vms_checked: "{{ vm_healthcheck_results | map(attribute='vm') | unique | list }}"
+      status_results: "{{ vm_healthcheck_results | selectattr('category', 'equalto', 'status') | list }}"
+      networking_results: "{{ vm_healthcheck_results | selectattr('category', 'equalto', 'networking') | list }}"
+      storage_results: "{{ vm_healthcheck_results | selectattr('category', 'equalto', 'storage') | list }}"
+      resources_results: "{{ vm_healthcheck_results | selectattr('category', 'equalto', 'resources') | list }}"
+
+- name: report | Render HTML Report
+  ansible.builtin.template:
+    src: healthcheck_report.html.j2
+    dest: "{{ vm_healthcheck_report_path }}"
+    mode: "0644"
+
+- name: report | Report Location
+  ansible.builtin.debug:
+    msg: "Healthcheck report written to {{ vm_healthcheck_report_path }}"
+...