Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 1515682 - [RFE] Better documentation for Ansible variables
Summary: [RFE] Better documentation for Ansible variables
Keywords:
Status: NEW
Alias: None
Product: OpenShift Container Platform
Classification: Red Hat
Component: RFE
Version: 3.6.0
Hardware: Unspecified
OS: Unspecified
unspecified
medium
Target Milestone: ---
: ---
Assignee: Brenton Leanhardt
QA Contact: Xiaoli Tian
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-11-21 08:47 UTC by Brendan Mchugh
Modified: 2019-02-11 18:18 UTC (History)
3 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed:


Attachments (Terms of Use)

Comment 1 Brendan Mchugh 2017-11-21 08:59:47 UTC
1. Proposed title of this feature request
Better documentation for Ansible variables

3. What is the nature and description of the request?  
As a newcomer to OpenShift, one comment I have regarding the Ansible installer is the lack of (good) documentation for all Ansible variables/defaults.

For example, looking at https://github.com/openshift/openshift-ansible/blob/master/roles/calico/defaults/main.yaml I see there are quite a lot of defaults for Calico which are very likely non-documented.
Although some variables are documented in the associated README.md for the role, for example https://github.com/openshift/openshift-ansible/blob/master/roles/calico/README.md, it is inconsistent and not all variables in the main.yaml are documented in the README.md.


4. Why does the customer need this? (List the business requirements here)  
To document ansible variables to indicate what they are used for.

5. How would the customer like to achieve this? (List the functional requirements here)  
Implement a system that automatically collects variables/defaults from the Ansible code and generates documentation. I'm thinking something similar to JavaDoc: a script or process that scrapes all roles/*/defaults/main.yaml files, looks for default variables defined in there, and generates the documentation. Ideally, these roles/*/defaults/main.yaml should include comments describing what variable is used for. A rewritten example of https://github.com/openshift/openshift-ansible/blob/master/roles/calico/defaults/main.yaml:

---
# Default etc location for K8s configuration
kubeconfig: "{{  openshift.common.config_base }}/node/{{ 'system:node:' +  openshift.common.hostname }}.kubeconfig"

# Default location for CNI configuration files
cni_conf_dir: "/etc/cni/net.d/"
# Default location for CNI binary files
cni_bin_dir: "/opt/cni/bin/"
# Default CNI URL
cni_url: "https://github.com/containernetworking/cni/releases/download/v0.5.2/cni-amd64-v0.5.2.tgz"
...

And so forth. A simple Python program can be written to look for roles/*/defaults/main.yaml files, parse them (using a YAML parser), extract all variables defined there plus their comments, and generate documentation from it. An example output file:

*** calico ***

kubeconfig: Default etc location for K8s configuration
cni_conf_dir: Default location for CNI configuration files
cni_bin_dir: Default location for CNI binary files
cni_url: Default CNI URL

6. For each functional requirement listed, specify how Red Hat and the customer can test to confirm the requirement is successfully implemented.  

7. Is there already an existing RFE upstream or in Red Hat Bugzilla?  
No

10. List any affected packages or components.
openshift-ansible-roles


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