Update os-diff doc with package install instructions and correct usages

docs_user/modules/con_comparing-configuration-files-between-deployments.adoc

@@ -5,15 +5,68 @@
 In order to help users to handle the configuration for the {OpenStackPreviousInstaller} and {rhos_prev_long}
 services the tool: https://github.com/openstack-k8s-operators/os-diff has been
 develop to compare the configuration files between the {OpenStackPreviousInstaller} deployment and the {rhos_long} cloud.
-Make sure Golang is installed and configured on your env:
-//kgilliga: Do we want to link to "https://github.com/openstack-k8s-operators/os-diff" downstream?
+Make sure Golang is installed and configured on your environment:
+
+----
+dnf install -y golang-github-openstack-k8s-operators-os-diff
+----
+
+Then configure the `/etc/os-diff/os-diff.cfg` file and the `/etc/os-diff/ssh.config` file according to your environment. To allow os-diff to connect to your clouds and pull files from the services that you describe in the `config.yaml` file you need to properly set the option in the `os-diff.cfg` file:
+
+[source,yaml]
+[subs=+quotes]
+----
+[Default]
+
+local_config_dir=/tmp/
+service_config_file=config.yaml
+
+[Tripleo]
+
+ssh_cmd=ssh -F ssh.config
+director_host=standalone
+container_engine=podman
+connection=ssh
+remote_config_path=/tmp/tripleo
+local_config_path=/tmp/
+
+[Openshift]
+
+ocp_local_config_path=/tmp/ocp
+connection=local
+ssh_cmd=""
+----
+
+Os-diff uses `ssh_cmd` to access your {OpenStackPreviousInstaller} host via SSH,
+or the host where your cloud is accessible and the podman/docker binary is installed
+and allowed to interact with the running containers. This option could have a different form:
+
+----
+ssh_cmd=ssh -F ssh.config standalone
+director_host=
+----
+
 ----
-git clone https://github.com/openstack-k8s-operators/os-diff
-pushd os-diff
-make build
+ssh_cmd=ssh -F ssh.config
+director_host=standalone
 ----
 
-Then configure ansible.cfg and ssh-config file according to your environment:
+or without an SSH config file:
+
+----
+ssh_cmd=ssh -i /home/user/.ssh/id_rsa [email protected]
+director_host=
+----
+
+or
+----
+ssh_cmd=ssh -i /home/user/.ssh/id_rsa stack@
+director_host=my.undercloud.local
+----
+
+Note that the result of using `ssh_cmd` and `director_host` should be a "successful ssh access".
+
+Configure or generate the `ssh.config` file from inventory or hosts file, for example:
 
 [source,yaml]
 [subs=+quotes]
@@ -49,6 +102,33 @@ Host crc
     UserKnownHostsFile=/dev/null
 ----
 
+Os-diff can use an `ssh.config` file for getting access to your {rhos_prev_long} environment.
+The following command can help you generate this SSH config file from your Ansible inventory, for example, `tripleo-ansible-inventory.yaml` file:
+
+----
+os-diff configure -i tripleo-ansible-inventory.yaml -o ssh.config --yaml
+----
+
+[NOTE]
+You must set the `IdentityFile` key in the file to get full working access:
+
+----
+Host standalone
+  HostName standalone
+  User root
+  IdentityFile ~/.ssh/id_rsa
+  StrictHostKeyChecking no
+  UserKnownHostsFile /dev/null
+
+Host undercloud
+  HostName undercloud
+  User root
+  IdentityFile ~/.ssh/id_rsa
+  StrictHostKeyChecking no
+  UserKnownHostsFile /dev/null
+----
+
+
 And test your connection:
 
 ----

docs_user/modules/proc_adopting-autoscaling.adoc

@@ -53,8 +53,7 @@ EOF
 . Optional: If you have previously backed up your {OpenStackShort} services configuration file from the old environment, you can use os-diff to compare and make sure the configuration is correct. This will producre the difference between both ini configuration files:
 +
 ----
-pushd os-diff
-./os-diff cdiff --service aodh -c /tmp/collect_tripleo_configs/aodh/etc/aodh/aodh.conf -o aodh_patch.yaml
+os-diff diff /tmp/collect_tripleo_configs/aodh/etc/aodh/aodh.conf aodh_patch.yaml --crd
 ----
 +
 For more information, see xref:reviewing-the-openstack-control-plane-configuration_{context}[Reviewing the {rhos_prev_long} control plane configuration].

docs_user/modules/proc_adopting-image-service-with-ceph-backend.adoc

@@ -55,8 +55,7 @@ If you have previously backed up your {OpenStackShort} services configuration fi
 For more information, see xref:pulling-configuration-from-tripleo-deployment_reviewing-configuration[Pulling the configuration from a {OpenStackPreviousInstaller} deployment]. 
 
 ----
-pushd os-diff
-./os-diff cdiff --service glance -c /tmp/collect_tripleo_configs/glance/etc/glance/glance-api.conf -o glance_patch.yaml
+os-diff diff /tmp/collect_tripleo_configs/glance/etc/glance/glance-api.conf glance_patch.yaml --crd
 ----
 
 This produces the difference between both ini configuration files.

docs_user/modules/proc_adopting-telemetry-services.adoc

@@ -55,8 +55,7 @@ EOF
 . Optional: If you previously backed up your {OpenStackShort} services configuration file from the old environment, you can use os-diff to compare and make sure the configuration is correct. This will produce the difference between both ini configuration files:
 +
 ----
-pushd os-diff
-./os-diff cdiff --service ceilometer -c /tmp/collect_tripleo_configs/ceilometer/etc/ceilometer/ceilometer.conf -o ceilometer_patch.yaml
+os-diff diff /tmp/collect_tripleo_configs/ceilometer/etc/ceilometer/ceilometer.conf ceilometer_patch.yaml --crd
 ----
 +
 For more information, see xref:reviewing-the-openstack-control-plane-configuration_{context}[Reviewing the {rhos_prev_long} control plane configuration].

docs_user/modules/proc_pulling-configuration-from-a-tripleo-deployment.adoc

@@ -22,9 +22,14 @@ remote_config_path=/tmp/tripleo
 +
 Make sure the ssh command you provide in `ssh_cmd` parameter is correct and with key authentication.
 
-. Enable or disable the services you want:
-Example with default {identity_service_first_ref}:
+. Enable or disable the services that you want in the `/etc/os-diff/config.yaml` file. Make sure that you have the correct rights to edit the file, for example:
 +
+----
+chown ospng:ospng /etc/os-diff/config.yaml
+----
+
+Example with default {identity_service_first_ref}:
+
 [source,yaml]
 ----
 # service name and file location
@@ -55,19 +60,106 @@ services:
       - /etc/keystone/keystone.conf
       - /etc/keystone/logging.conf
 ----
-+
 Repeat this step for each {OpenStackShort} service that you want to disable or enable.
 
-. Pull the configuration:
+. If you are using non-containerized services, such as the `ovs-external-ids`, os-diff can pull configuration or command output:
 +
 ----
-pushd os-diff
-./os-diff pull
+services:
+  ovs_external_ids:
+    hosts:
+      - standalone
+    service_command: "ovs-vsctl list Open_vSwitch . | grep external_ids | awk -F ': ' '{ print $2; }'"
+    cat_output: true
+    path:
+      - ovs_external_ids.json
+    config_mapping:
+      ovn-bridge-mappings: edpm_ovn_bridge_mappings
+      ovn-bridge: edpm_ovn_bridge
+      ovn-encap-type: edpm_ovn_encap_type
+      ovn-match-northd-version: ovn_match_northd_version
+      ovn-monitor-all: ovn_monitor_all
+      ovn-remote-probe-interval: edpm_ovn_remote_probe_interval
+      ovn-ofctrl-wait-before-clear: edpm_ovn_ofctrl_wait_before_clear
 ----
 +
-The configuration will be pulled and stored by default:
+This service is not an {rhos_prev_long} service executed in a container, so the description and the behavior is different. It is important to correctly configure an SSH config file or equivalent for non-standard services such as OVS. The `ovs_external_ids` does not run in a container, and the ovs data is stored
+on each host of our cloud: controller_1/controller_2/...
++
+With the `hosts` key, os-diff loops on each host and runs the command in the `service_command` key:
++
+----
+    ovs_external_ids:
+        path:
+            - ovs_external_ids.json
+        hosts:
+            - standalone
+----
++
+The `service_command`  provides the required information. It could be a simple cat from a config file. If you want os-diff to get the output of the command and store the output in a file specified by the key path, set `cat_output` to true. Then you can provide a mapping between in this case the EDPM CRD, and the ovs-vsctl output with config_mapping:
++
+----
+        service_command: 'ovs-vsctl list Open_vSwitch . | grep external_ids | awk -F '': '' ''{ print $2; }'''
+        cat_output: true
+        config_mapping:
+            ovn-bridge: edpm_ovn_bridge
+            ovn-bridge-mappings: edpm_ovn_bridge_mappings
+            ovn-encap-type: edpm_ovn_encap_type
+            ovn-match-northd-version: ovn_match_northd_version
+            ovn-monitor-all: ovn_monitor_all
+            ovn-ofctrl-wait-before-clear: edpm_ovn_ofctrl_wait_before_clear
+            ovn-remote-probe-interval: edpm_ovn_remote_probe_interval
+----
++
+Then you can use the following command to compare the values:
++
+----
+os-diff diff ovs_external_ids.json edpm.crd --crd --service ovs_external_ids
+----
++
+For example, to check the `/etc/yum.conf` on every host, you must put the following statement in the `config.yaml` file. The following example uses a file called `yum_config`:
 +
 ----
+services:
+  yum_config:
+    hosts:
+      - undercloud
+      - controller_1
+      - compute_1
+      - compute_2
+    service_command: "cat /etc/yum.conf"
+    cat_output: true
+    path:
+      - yum.conf
+----
+
+. Pull the configuration:
++
+
+This command will pull all the configuration files that are described in the `/etc/os-diff/config.yaml` file.
+Os-diff can update this file automatically according to your running environment with the command `--update` or `--update-only`.
+This option sets the podman information into the `config.yaml` for all running containers.
+It can be useful later, when all the {rhos_prev_long} services are turned off.
+
+Note that when the `config.yaml` file is populated automatically you must provide the configuration paths manually for each service.
+
+----
+# will only update the /etc/os-diff/config.yaml
+os-diff pull --update-only
+----
+
+----
+# will update the /etc/os-diff/config.yaml and pull configuration
+os-diff pull --update
+----
+
+----
+# will update the /etc/os-diff/config.yaml and pull configuration
+os-diff pull
+----
+
+The configuration will be pulled and stored by default:
+----
 /tmp/tripleo/
 ----
 

docs_user/modules/proc_verifying-the-image-service-adoption.adoc

@@ -9,7 +9,7 @@ Verify that you successfully adopted your {image_service_first_ref} to the {rhos
 . Test the {image_service_first_ref} from the {rhos_prev_long} CLI. You can compare and make sure the configuration has been correctly applied to the {image_service} pods:
 +
 ----
-./os-diff cdiff --service glance -c /etc/glance/glance.conf.d/02-config.conf  -o glance_patch.yaml --frompod -p glance-api
+os-diff diff /etc/glance/glance.conf.d/02-config.conf glance_patch.yaml --frompod -p glance-api
 ----
 +
 If no line appears, then the configuration is correctly done.