Merge pull request #126 from redhatci/default_job_path

Define default deprecated_api_logs for standalone usage of deprecated_api role

roles/deprecated_api/README.md

@@ -1,11 +1,5 @@
 # redhatci.ocp.deprecated_api – Detect To-Be-Removed Kubernetes (K8s) APIs
 
-- [Synopsis](https://galaxy.ansible.com/ui/repo/published/redhatci/ocp/content/role/deprecated_api/README.md#synopsis)
-- [Requirements](https://galaxy.ansible.com/ui/repo/published/redhatci/ocp/content/role/deprecated_api/README.md#requirements)
-- [Parameters](https://galaxy.ansible.com/ui/repo/published/redhatci/ocp/content/role/deprecated_api/README.md#parameters)
-- [Examples](https://galaxy.ansible.com/ui/repo/published/redhatci/ocp/content/role/deprecated_api/README.md#examples)
-- [Output](https://galaxy.ansible.com/ui/repo/published/redhatci/ocp/content/role/deprecated_api/README.md#output)
-
 # Synopsis
 
 - Connect to a running K8s cluster with an application workload already deployed.
@@ -16,7 +10,6 @@
 - Output a map from OpenShift versions to a list of workload APIs to be removed in each version.
 - Generate a JUnit file containing the testsuite 'Workload Compatibility with OCP Versions'.
 
-
 # Requirements
 
 The role requires the following:
@@ -25,26 +18,33 @@ The role requires the following:
 - Ensure the availability of the K8s [APIRequestCount](https://github.com/openshift/cluster-kube-apiserver-operator/blob/master/bindata/assets/kube-apiserver/apiserver.openshift.io_apirequestcount.yaml) object. For OpenShift, APIRequestCount is included in the standard distribution from OCP 4.9 onwards. For other distributions, deploy the required CRD and CR before using the role.
 - Python version 3.6 or higher is needed to parse the APIs.
 
-
 # Parameters
 
 | Parameter               | Choices/Defaults      | Comments                                             |
 |-------------------------|-----------------------|------------------------------------------------------|
 | `kubeconfig`            | `~/.kube/config.json` | Path to an existing Kubernetes config file to be used by k8s_info dependency. If not provided, the OpenShift client will attempt to load the default configuration file from `~/.kube/config.json`. Can also be specified via `K8S_AUTH_KUBECONFIG` environment variable.                                                                                                |
-| `deprecated_namespaces` | `undefined`           | List of namespaces the role will check for deprecated APIs. Typically, it should include the namespaces where you deploy the workload. If left undefined, the role will check all namespaces, excluding those starting with the `openshift` and `kube-` prefixes.                                                |
+| `deprecated_namespaces` | `undefined`           | Optional. List of namespaces the role will check for deprecated APIs. Typically, it should include the namespaces where you deploy the workload. If left undefined, the role will check all namespaces, excluding those starting with the `openshift` and `kube-` prefixes.                                                |
 | `ocp_version`           | `"4.9"/"4.10"/etc`    | OpenShift version currently running on your cluster. |
-| `job_logs`              | `undefined`           | Directory to store the output JUnit file containing the 'Workload Compatibility with OCP Versions' testsuite.                                                              |
+| `deprecated_api_logs.path` | `/tmp`             | Optional. Directory to store the output JUnit file containing the 'Workload Compatibility with OCP Versions' testsuite.                                                              |
 
 # Examples
 
 ```
-- name: Detect to-be-Removed APIs in all namespaces excluding ones starting with openshift and kube-
+- name: Detect to-be-removed APIs in all namespaces excluding ones starting with openshift and kube
+  include_role:
+    name: redhatci.ocp.deprecated_api
+  vars:
+    ocp_version: "4.9"
+```
+
+```
+- name: Detect to-be-removed APIs and define a directory to store the output
   include_role:
     name: redhatci.ocp.deprecated_api
   vars:
     ocp_version: "4.9"
-    job_logs:
-      path: "{{ playbook_dir }}"
+    deprecated_api_logs:
+      path: "/path/to/my/log/folder"
 ```
 
 # Output
@@ -55,7 +55,7 @@ The role sets the Ansible fact `ocp_compatibility` - a map from OpenShift versio
 {"ansible_facts": {"ocp_compatibility": {"4.10": "compatible", "4.11": "compatible", "4.12": "podsecuritypolicies.v1beta1.policy", "4.13": "podsecuritypolicies.v1beta1.policy, prioritylevelconfigurations.v1beta1.flowcontrol.apiserver.k8s.io, flowschemas.v1beta1.flowcontrol.apiserver.k8s.io, horizontalpodautoscalers.v2beta2.autoscaling", "4.9": "compatible"}}, "changed": false}
 ```
 
-The second output is a JUnit file generated in the job_logs folder, which contains the testsuite 'Workload Compatibility with OCP Versions'. Here is an example:
+The second output is a JUnit file generated in the deprecated_api_logs folder, which contains the testsuite 'Workload Compatibility with OCP Versions'. Here is an example:
 
 ```
 $ cat apirequestcounts_ocp_compatibility.xml 

roles/deprecated_api/defaults/main.yml

@@ -0,0 +1,5 @@
+---
+# that simplifies the usage of the role in standalone mode
+deprecated_api_logs:
+  path: "/tmp"
+...

roles/deprecated_api/tasks/main.yml

@@ -27,7 +27,7 @@
 
 - name: Compute OCP compatibility of the workload API
   vars:
-    ocp_filename: "{{ job_logs.path }}/apirequestcounts_ocp_compatibility.xml"
+    ocp_filename: "{{ deprecated_api_logs.path }}/apirequestcounts_ocp_compatibility.xml"
   set_fact:
     ocp_compatibility: "{{ removed_in_release_api | redhatci.ocp.ocp_compatibility(ocp_version, ocp_filename) }}"
 ...