[WIP] Filters: Add docs (#603)

* Filters: Add docs

* Add changelog

changelogs/fragments/603-add-filter-docs.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - filters - Add documentation to all filters (https://github.com/oVirt/ovirt-ansible-collection/pull/603).

plugins/filter/convert_to_bytes.yml

@@ -0,0 +1,22 @@
+DOCUMENTATION:
+  name: convert_to_bytes
+  author: Martin Necas (@mnecas)
+  # version_added: 'historical'
+  short_description: Convert units to bytes
+  description:
+    - This method convert units to bytes, which follow IEC standard
+  positional: _input
+  options:
+    _input:
+      description: Value to be converted
+      type: string
+      required: true
+
+EXAMPLES: |
+  - name: Get number of bytes
+    ansible.builtin.set_fact:
+      disk_size: "{{ '1KiB' | @NAMESPACE@.@[email protected]_to_bytes }}"
+RETURN:
+  _value:
+    description: Amount of bytes
+    type: int

plugins/filter/filtervalue.yml

@@ -0,0 +1,30 @@
+DOCUMENTATION:
+  name: filtervalue
+  author: Martin Necas (@mnecas)
+  short_description: Filter to findall occurance of some value in dict
+  description:
+    - Filter to findall occurance of some value in dict
+  positional: _input, attr, value
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+    attr:
+      description: Attribute to sotr by
+      type: list
+      required: true
+    value:
+      description: List of VMs
+      type: list
+      required: true
+
+EXAMPLES: |
+  - name: Set filtred ovirt_vms
+    ansible.builtin.set_fact:
+      ovirt_vms: "{{ vms | @NAMESPACE@.@[email protected]('name', item.name) }}"
+
+RETURN:
+  _value:
+    description: Filtred VMs
+    type: list

plugins/filter/get_network_xml_to_dict.yml

@@ -0,0 +1,22 @@
+DOCUMENTATION:
+  name: get_network_xml_to_dict
+  author: Martin Necas (@mnecas)
+  short_description: Get network bridge and uuid to dict
+  description:
+    - Get network bridge and uuid to dict
+  positional: _input
+  options:
+    _input:
+      description: xml
+      type: string
+      required: true
+
+EXAMPLES: |
+  - name: Set network_dict from default_net_xml
+    ansible.builtin.set_fact:
+      network_dict: "{{ default_net_xml['stdout'] | @NAMESPACE@.@[email protected]_network_xml_to_dict }}"
+
+RETURN:
+  _value:
+    description: Dict of network
+    type: dict

plugins/filter/get_ovf_disk_size.yml

@@ -0,0 +1,25 @@
+DOCUMENTATION:
+  name: get_ovf_disk_size
+  author: Asaf Rachmani (@arachmani)
+  # version_added: 'historical'
+  short_description: Get OVF disk size
+  description:
+    - Get OVF disk size.
+  positional: _input
+  options:
+    _input:
+      description: OVF data
+      type: string
+      required: true
+
+EXAMPLES: |
+  - name: Get ovf data
+    ansible.builtin.command: cat "{{ path }}"
+    register: ovf_data
+  - name: Get disk size from ovf data
+    ansible.builtin.set_fact:
+      disk_size: "{{ ovf_data['stdout'] | @NAMESPACE@.@[email protected]_ovf_disk_size }}"
+RETURN:
+  _value:
+    description: OVF disk size
+    type: string

plugins/filter/json_query.yml

@@ -0,0 +1,20 @@
+DOCUMENTATION:
+  name: json_query
+  short_description: Copy of community.general.json_query
+  description:
+    - Copy of community.general.json_query used internally in the collection to ease RPM packaging, so we don't need to package/release/support the whole community.general collection for RHV customers
+    - The original can be found at link https://github.com/ansible-collections/community.general/blob/main/plugins/filter/json_query.py
+  positional: _input
+  options:
+    _input:
+      description: Value to be converted
+      type: string
+      required: true
+
+EXAMPLES: |
+    Query data using jmespath query language ( http://jmespath.org ). Example:
+    - ansible.builtin.debug: msg="{{ instance | json_query(tagged_instances[*].block_device_mapping.*.volume_id') }}"
+RETURN:
+  _value:
+    description: query
+    type: string

plugins/filter/ovirtdiff.yml

@@ -0,0 +1,35 @@
+DOCUMENTATION:
+  name: ovirtdiff
+  author: Martin Necas (@mnecas)
+  short_description: Show what will be changed in next run of the VM
+  description:
+    - Show what will be changed in next run of the VM
+  positional: _input
+  options:
+    _input:
+      description: VM
+      type: dict
+      required: true
+
+EXAMPLES: |
+  - name: Get VM myvm
+    ovirt_vm_info:
+      auth: "{{ ovirt_auth }}"
+      pattern: 'name={{ myvm }}'
+      next_run: false
+    register: vm
+
+  - name: Get next_run of VM myvm
+    ovirt_vm_info:
+      auth: "{{ ovirt_auth }}"
+      pattern: 'name={{ myvm }}'
+      next_run: true
+    register: vm_next_run
+
+  - name: Print what will be changed in next run of the VM
+    debug:
+      msg: "{{ vm.ovirt_vms[0] | @NAMESPACE@.@[email protected](vm_next_run.ovirt_vms[0]) }}"
+RETURN:
+  _value:
+    description: VM
+    type: dict

plugins/filter/ovirtvmip.yml

@@ -0,0 +1,31 @@
+DOCUMENTATION:
+  name: ovirtvmip
+  author: Martin Necas (@mnecas)
+  short_description: Return first IP
+  description:
+    - Return first IP
+  positional: _input, attr, network_ip
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+    attr:
+      description: Attribute by which the
+      type: list
+    network_ip:
+      description: Filter the IPs by network address
+      type: string
+
+EXAMPLES: |
+    - name: Print VM IP
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected] }}"
+    - name: Print VM IP
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected](attr='name') }}"
+
+RETURN:
+  _value:
+    description: First IP
+    type: list

plugins/filter/ovirtvmips.yml

@@ -0,0 +1,31 @@
+DOCUMENTATION:
+  name: ovirtvmips
+  author: Martin Necas (@mnecas)
+  short_description: VM all IPs
+  description:
+    - VM all IPs
+  positional: _input
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+    attr:
+      description: Attribute by which the
+      type: list
+    network_ip:
+      description: Filter the IPs by network address
+      type: string
+
+EXAMPLES: |
+    - name: Print VM all IPs
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected] }}"
+    - name: Print VM all IPs
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected](attr='name') }}"
+
+RETURN:
+  _value:
+    description: All IPs
+    type: list

plugins/filter/ovirtvmipsv4.yml

@@ -0,0 +1,31 @@
+DOCUMENTATION:
+  name: ovirtvmipsv4
+  author: Martin Necas (@mnecas)
+  short_description: VM IPv4
+  description:
+    - VM IPv4
+  positional: _input
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+    attr:
+      description: Attribute by which the
+      type: list
+    network_ip:
+      description: Filter the IPs by network address
+      type: string
+
+EXAMPLES: |
+    - name: Print VM all IPv4
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected] }}"
+    - name: Print VM all IPv4
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected](attr='name') }}"
+
+RETURN:
+  _value:
+    description: VM IPv4
+    type: list

plugins/filter/ovirtvmipsv6.yml

@@ -0,0 +1,31 @@
+DOCUMENTATION:
+  name: ovirtvmipsv6
+  author: Martin Necas (@mnecas)
+  short_description: VM IPv4
+  description:
+    - VM IPv4
+  positional: _input
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+    attr:
+      description: Attribute by which the
+      type: list
+    network_ip:
+      description: Filter the IPs by network address
+      type: string
+
+EXAMPLES: |
+    - name: Print VM all IPv6
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected] }}"
+    - name: Print VM all IPv6
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected](attr='name') }}"
+
+RETURN:
+  _value:
+    description: VM IPv4
+    type: list

plugins/filter/ovirtvmipv4.yml

@@ -0,0 +1,31 @@
+DOCUMENTATION:
+  name: ovirtvmipv4
+  author: Martin Necas (@mnecas)
+  short_description: VM IPv4
+  description:
+    - VM IPv4
+  positional: _input
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+    attr:
+      description: Attribute by which the
+      type: list
+    network_ip:
+      description: Filter the IPs by network address
+      type: string
+
+EXAMPLES: |
+    - name: Print VM IPv4
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected] }}"
+    - name: Print VM IPv4
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected](attr='name') }}"
+
+RETURN:
+  _value:
+    description: VM IPv4
+    type: list

plugins/filter/ovirtvmipv6.yml

@@ -0,0 +1,31 @@
+DOCUMENTATION:
+  name: ovirtvmipv6
+  author: Martin Necas (@mnecas)
+  short_description: VM IPv4
+  description:
+    - VM IPv4
+  positional: _input
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+    attr:
+      description: Attribute by which the
+      type: list
+    network_ip:
+      description: Filter the IPs by network address
+      type: string
+
+EXAMPLES: |
+    - name: Print VM IPv6
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected] }}"
+    - name: Print VM IPv6
+      debug:
+        msg: "{{ vms.ovirt_vms | @NAMESPACE@.@[email protected](attr='name') }}"
+
+RETURN:
+  _value:
+    description: VM IPv4
+    type: list

plugins/filter/removesensitivevmdata.yml

@@ -0,0 +1,22 @@
+DOCUMENTATION:
+  name: removesensitivevmdata
+  author: Martin Necas (@mnecas)
+  short_description: removesensitivevmdata internal filter
+  description:
+    - removesensitivevmdata internal filter
+  positional: _input
+  options:
+    _input:
+      description: List of VMs
+      type: list
+      required: true
+
+EXAMPLES: |
+    - name: Print VM
+      debug:
+        msg: "{{ vms | @NAMESPACE@.@[email protected] }}"
+
+RETURN:
+  _value:
+    description: List of VMs
+    type: list

roles/hosted_engine_setup/tasks/alter_libvirt_default_net_configuration.yml

@@ -6,7 +6,7 @@
 
 - name: Set network_dict from default_net_xml
   ansible.builtin.set_fact:
-    network_dict: "{{ default_net_xml['stdout'] | ovirt.ovirt.get_network_xml_to_dict }}"
+    network_dict: "{{ default_net_xml['stdout'] | @NAMESPACE@.@NAME@.get_network_xml_to_dict }}"
 
 - name: Create he-network-config.xml from network-config.j2 template
   ansible.builtin.template: