Bug 1891749 - Add documentation for oVirt Ansible Collection
Summary: Add documentation for oVirt Ansible Collection
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Virtualization Manager
Classification: Red Hat
Component: Documentation
Version: 4.4.0
Hardware: Unspecified
OS: Unspecified
high
high
Target Milestone: ovirt-4.4.3
: ---
Assignee: Eli Marcus
QA Contact: Martin Necas
URL:
Whiteboard:
: 1894875 (view as bug list)
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2020-10-27 09:13 UTC by Martin Perina
Modified: 2021-02-02 00:06 UTC (History)
12 users (show)

Fixed In Version:
Doc Type: No Doc Update
Doc Text:
Clone Of:
Environment:
Last Closed: 2020-12-01 16:20:08 UTC
oVirt Team: Infra
Target Upstream Version:
Embargoed:


Attachments (Terms of Use)

Description Martin Perina 2020-10-27 09:13:02 UTC
As we have moved all supported Ansible roles and modules into oVirt Ansible Collection, we need to add/update documentation around below chapters:

1. Automating Configuration Tasks using Ansible
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html/administration_guide/chap-automating_rhv_configuration_using_ansible

2. Disaster Recovery Guide
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html/disaster_recovery_guide/index

3. Extend Automating Configuration Tasks using Ansible to support installation from Red Hat Automation Hub

Comment 1 Steve Goodman 2020-11-03 14:27:24 UTC
I already fixed the link in 
1. Automating Configuration Tasks using Ansible
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html/administration_guide/chap-automating_rhv_configuration_using_ansible

Comment 2 Martin Perina 2020-11-06 10:15:12 UTC
*** Bug 1894875 has been marked as a duplicate of this bug. ***

Comment 3 Martin Perina 2020-11-06 10:19:10 UTC
Adding additional request from BZ1894875:


> Description of problem:
> 
> We recently moved the code of several existing roles from other repos/packages to ovirt-ansible-collection.
> This should be properly documented.
> In particular, the location of hosted-engine before-/after-engine-setup hooks changed from:
> 
> /usr/share/ansible/roles/ovirt.hosted-engine-setup/hooks
> 
> to:
> 
> /usr/share/ansible/collections/ansible_collections/ovirt/ovirt/roles/hosted_engine_setup/hooks
> 
> Version-Release number of selected component (if applicable):
> I think 4.4.3
> 
> How reproducible:
> Always
> 
> Steps to Reproduce:
> 1. Follow existing documents you can find on the net instructing to place hooks in the old directory
> 2. Deploy
> 3.
> 
> Actual results:
> Your hooks are ignored
> 
> Expected results:
> You should notice that the hooks location changed
> 
> Additional info:

Comment 4 Martin Necas 2020-11-09 12:37:14 UTC
Here is a list of what should change in the [1] to add support to the collection.
Please let me know if you need more information about it.

[1] https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html/administration_guide/chap-automating_rhv_configuration_using_ansible


...

18.1 Ansible Collection

Ansible collection provides all modules, roles, and plugins to manage various parts of the Red Hat Virtualization infrastructure.
The modules are used for communication between Ansible and the Red Hat Virtualization Manager.
Ansible roles provide a method of modularizing Ansible code by breaking up large playbooks into smaller, reusable files that can be shared with other users.
For more information about the Ansible collection see the [Automation Hub](https://cloud.redhat.com/ansible/automation-hub/redhat/rhv/docs) documentation.

18.1.1. Installing Ansible Collection

You can install Ansible collection for Red Hat Virtualization from the Red Hat Virtualization Manager repository. Use the following command to install the Ansible collection on the Manager machine:

```shell
# dnf install ovirt-ansible-collection
```

By default the collection is installed to  **/usr/share/ansible/collections/ansible_collections/redhat/rhv**. The structure of the `ovirt-ansible-collection` package is as follows:

- /usr/share/ansible/collections/ansible_collections/redhat/rhv
- /usr/share/doc/ovirt-ansible-collection/

18.1.2. Using Ansible Collection to Configure Red Hat Virtualization

The following procedure guides you through creating and running a playbook that uses Ansible collection to configure Red Hat Virtualization. This example uses Ansible to connect to the Manager on the local machine and create a new data center.

Prerequisites
- Ensure that you have the Python SDK installed on the machine running the playbook.

Configuring Red Hat Virtualization using Ansible Collection
- ...
- 4. Create your playbook.
```
---
- name: RHV infrastructure
  hosts: localhost
  connection: local
  gather_facts: false

  vars_files:
    # Contains variables to connect to the Manager
    - engine_vars.yml
    # Contains encrypted engine_password variable using ansible-vault
    - passwords.yml

  pre_tasks:
    # The use of redhat.rhv before ovirt_auth is to check if the collection is correctly loaded
    - name: Login to RHV
      redhat.rhv.ovirt_auth:
        url: "{{ engine_url }}"
        username: "{{ engine_user }}"
        password: "{{ engine_password }}"
        ca_file: "{{ engine_cafile | default(omit) }}"
        insecure: "{{ engine_insecure | default(true) }}"
      tags:
        - always

  vars:
    data_center_name: mydatacenter
    data_center_description: mydatacenter
    data_center_local: false
    compatibility_version: 4.4

  roles:
    - infra
  collections:
    - redhat.rhv
  post_tasks:
    - name: Logout from RHV
      ovirt_auth:
        state: absent
        ovirt_auth: "{{ ovirt_auth }}"
      tags:
        - always
```
- ...

You have successfully used the `infra` Ansible role from collection to create a data center named `mydatacenter`.

Comment 5 Martin Perina 2020-11-09 16:32:35 UTC
(In reply to Martin Necas from comment #4)
> Here is a list of what should change in the [1] to add support to the
> collection.
> Please let me know if you need more information about it.
> 
> [1]
> https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/
> html/administration_guide/chap-automating_rhv_configuration_using_ansible
> 
> 
> ...
> 
> 18.1 Ansible Collection

Let's use "oVirt Ansible Collection" everywhere , this is the official name for both oVirt and RHV

> 
> Ansible collection provides all modules, roles, and plugins to manage
> various parts of the Red Hat Virtualization infrastructure.
> The modules are used for communication between Ansible and the Red Hat
> Virtualization Manager.
> Ansible roles provide a method of modularizing Ansible code by breaking up
> large playbooks into smaller, reusable files that can be shared with other
> users.
> For more information about the Ansible collection see the [Automation
> Hub](https://cloud.redhat.com/ansible/automation-hub/redhat/rhv/docs)
> documentation.
> 
> 18.1.1. Installing Ansible Collection
> 
> You can install Ansible collection for Red Hat Virtualization from the Red
> Hat Virtualization Manager repository. Use the following command to install
> the Ansible collection on the Manager machine:
> 
> ```shell
> # dnf install ovirt-ansible-collection
> ```

It's also worth mentioning that oVirt Ansible Collection (along with all SDKs) is available not only in RHV Manager and Host channels, but also RHV Tools channel, which is available with all RHEL subscriptions (no need to have RHV subscription)

> 
> By default the collection is installed to 
> **/usr/share/ansible/collections/ansible_collections/redhat/rhv**. The
> structure of the `ovirt-ansible-collection` package is as follows:
> 
> - /usr/share/ansible/collections/ansible_collections/redhat/rhv
> - /usr/share/doc/ovirt-ansible-collection/
> 
> 18.1.2. Using Ansible Collection to Configure Red Hat Virtualization
> 
> The following procedure guides you through creating and running a playbook
> that uses Ansible collection to configure Red Hat Virtualization. This
> example uses Ansible to connect to the Manager on the local machine and
> create a new data center.
> 
> Prerequisites
> - Ensure that you have the Python SDK installed on the machine running the
> playbook.
> 
> Configuring Red Hat Virtualization using Ansible Collection
> - ...
> - 4. Create your playbook.
> ```
> ---
> - name: RHV infrastructure
>   hosts: localhost
>   connection: local
>   gather_facts: false
> 
>   vars_files:
>     # Contains variables to connect to the Manager
>     - engine_vars.yml
>     # Contains encrypted engine_password variable using ansible-vault
>     - passwords.yml
> 
>   pre_tasks:
>     # The use of redhat.rhv before ovirt_auth is to check if the collection
> is correctly loaded
>     - name: Login to RHV
>       redhat.rhv.ovirt_auth:
>         url: "{{ engine_url }}"

Please use hostname option instead of url:

          hostname: "{{ engine_fqdn }}"

>         username: "{{ engine_user }}"
>         password: "{{ engine_password }}"
>         ca_file: "{{ engine_cafile | default(omit) }}"
>         insecure: "{{ engine_insecure | default(true) }}"
>       tags:
>         - always
> 
>   vars:
>     data_center_name: mydatacenter
>     data_center_description: mydatacenter
>     data_center_local: false
>     compatibility_version: 4.4
> 
>   roles:
>     - infra
>   collections:
>     - redhat.rhv
>   post_tasks:
>     - name: Logout from RHV
>       ovirt_auth:
>         state: absent
>         ovirt_auth: "{{ ovirt_auth }}"
>       tags:
>         - always
> ```
> - ...
> 
> You have successfully used the `infra` Ansible role from collection to
> create a data center named `mydatacenter`.

Looks good to update the existing part of Ansible integration, but we need also to describe Automation Hub installation process

Comment 6 Martin Necas 2020-11-16 12:21:32 UTC
18.1.1. Installing Ansible Collection RPM

...

18.1.2. Installing Ansible Collection from Automation Hub

Automation Hub is a new place from which users can install the collections. For configuring the environment please follow the [Automation Hub setup](https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/1.0/html/getting_started_with_red_hat_ansible_automation_hub/index).

Install the collection
```
$ ansible-galaxy collection install redhat.rhv
```

The Automation Hub currently does not install RPM dependencies, please make sure that you have packages on the host where you execute the playbook:
- python3-ovirt-engine-sdk4
- python3-netaddr
- python3-jmespath
- python3-passlib

18.1.3. Using Ansible Collection to Configure Red Hat Virtualization

...


Note You need to log in before you can comment on or make changes to this bug.