use collection and environment variables as fallbacks for common auth…

… vars across all roles (#108)

* use collection and environment variables as fallbacks for common auth vars across all roles

changelogs/fragments/108-add-collection-level-auth-vars.yml

@@ -0,0 +1,5 @@
+---
+minor_changes:
+  - >-
+    Added the option to set environment variables or collection level variables for auth to vcenter. This provides users
+    with a more centralizedoption for setting things that all roles use like vCenter hostname, username, password, etc

docs/authentication.md

@@ -0,0 +1,67 @@
+# Authentication Variables
+
+Each role in this collection has its own set of authentication and proxy variables. It is not convnient to set those variables for every role, so there are options to set the variables for all roles in the collection at once.
+
+Here is the order of precedence from greatest to least (the first listed variables override all other variables):
+
+1. Role variables (for example, `info_hostname` for the `info` role)
+2. Collection level variables (for example, `vmware_ops_hostname`)
+3. Environment variables (for example, `VMWARE_HOST`)
+
+## Collection and Environment Variables
+
+The list of collection/environment variables is pulled from the [vars/main.yml](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/vars/main.yml)
+
+The available collection level variables and their corresponding environment variables can be found below:
+
+- vmware_ops_hostname
+    * str, The hostname or IP address of the vSphere vCenter or ESXi host to manage.
+    * Environment Var: `VMWARE_HOST`
+
+- vmware_ops_username
+    * str, The username to use when authenticating to the vSphere vCenter or ESXi host.
+    * Environment Var: `VMWARE_USER`
+
+- vmware_ops_password
+    * str, The password to use when authenticating to the vSphere vCenter or ESXi host.
+    * Environment Var: `VMWARE_PASSWORD`
+
+- vmware_ops_validate_certs
+    * bool, Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
+    * Environment Var: `VMWARE_VALIDATE_CERTS`
+
+- vmware_ops_port
+    * int, The port to use when authenticating to the vSphere vCenter or ESXi host to manage.
+    * Environment Var: `VMWARE_PORT`
+
+- vmware_ops_proxy_host
+    * str, The hostname or IP address of a proxy host to use. If set all requests to the vCenter or ESXi host will go through the proxy host.
+    * Environment Var: `VMWARE_PROXY_HOST`
+
+- vmware_ops_proxy_port
+    * int, The port of a proxy host to use. If set all requests to the vCenter or ESXi host will go through the proxy host.
+    * Environment Var: `VMWARE_PROXY_PORT`
+
+## Example Playbook
+
+```yaml
+- name: Example Of Setting Different variables
+  hosts: localhost
+  environment:
+    VMWARE_HOST: myvcenter.local
+    VMWARE_USER: myadmin
+
+  vars:
+    # You can avoid exposing the password as an environment variable, and leverage ansible-vault by using the collection level
+    # variable instead
+    vmware_ops_password: vaultedPassword!
+
+  roles:
+    # This role will use VMWARE_HOST, VMWARE_USER, and vmware_ops_password
+    - role: cloud.vmware_ops.provision_vm
+
+    # This role will use VMWARE_HOST, info_username, and info_password
+    - role: cloud.vmware_ops.info
+      info_username: myreader
+      info_password: readerPassword!
+```

roles/cluster_settings/README.md

@@ -7,30 +7,42 @@ A role to define cluster settings in vCenter.
 N/A
 
 ## Role Variables
+
 ### Auth
+
 - **cluster_settings_username**:
   - The vSphere vCenter username.
+  - If this variable is not set, the collection level variable `vmware_ops_username` will be used. If that variable is not set, the environment variable `VMWARE_USER` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **cluster_settings_password**:
   - The vSphere vCenter password.
+  - If this variable is not set, the collection level variable `vmware_ops_password` will be used. If that variable is not set, the environment variable `VMWARE_PASSWORD` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **cluster_settings_hostname**:
   - The hostname or IP address of the vSphere vCenter.
+  - If this variable is not set, the collection level variable `vmware_ops_hostname` will be used. If that variable is not set, the environment variable `VMWARE_HOST` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **cluster_settings_validate_certs**
   - Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
+  - If this variable is not set, the collection level variable `vmware_ops_validate_certs` will be used. If that variable is not set, the environment variable `VMWARE_VALIDATE_CERTS` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
+
+- **cluster_settings_port**:
+  - str or int, The port used to authenticate to the vSphere vCenter that contains the cluster to configure.
+  - If this variable is not set, the collection level variable `vmware_ops_port` will be used. If that variable is not set, the environment variable `VMWARE_PORT` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
+
+### Cluster settings
 
 - **cluster_settings_cluster_name**:
   - The name of the cluster in vSphere vCenter to configure.
 
 - **cluster_settings_datacenter_name**:
   - The name of the datacenter in vSphere vCenter which contains the cluster to configure.
 
-- **cluster_settings_port**:
-  - str or int, The port used to authenticate to the vSphere vCenter that contains the cluster to configure.
-
-### Cluster settings
-
 #### Distributed Power Management (DPM)
 
 - **cluster_settings_dpm_enable**:

roles/cluster_settings/defaults/main.yml

@@ -1,2 +1,11 @@
 ---
+cluster_settings_hostname: "{{ vmware_ops_collection_hostname }}"
+cluster_settings_username: "{{ vmware_ops_collection_username }}"
+cluster_settings_password: "{{ vmware_ops_collection_password }}"
+cluster_settings_validate_certs: "{{ vmware_ops_collection_validate_certs }}"
+cluster_settings_port: "{{ vmware_ops_collection_port }}"
+
+cluster_settings_proxy_host: "{{ vmware_ops_collection_proxy_host }}"
+cluster_settings_proxy_port: "{{ vmware_ops_collection_proxy_port }}"
+
 cluster_settings_drs_apply_recommendations: false

roles/cluster_settings/tasks/main.yml

@@ -1,4 +1,8 @@
 ---
+- name: Import Collection Level Vars
+  ansible.builtin.include_vars:
+    file: "{{ role_path }}/../../vars/main.yml"
+
 - name: Check Mandatory Variables Are Defined
   ansible.builtin.assert:
     that:

roles/content_library/README.md

@@ -7,29 +7,41 @@ A role to manage VMWare content libraries. You can create or delete both local a
 N/A
 
 ## Role Variables
+
 ### Auth
+
 - **content_library_username**:
   - The vSphere vCenter username.
+  - If this variable is not set, the collection level variable `vmware_ops_username` will be used. If that variable is not set, the environment variable `VMWARE_USER` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **content_library_password**:
   - The vSphere vCenter password.
+  - If this variable is not set, the collection level variable `vmware_ops_password` will be used. If that variable is not set, the environment variable `VMWARE_PASSWORD` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **content_library_hostname**:
   - The hostname or IP address of the vSphere vCenter.
+  - If this variable is not set, the collection level variable `vmware_ops_hostname` will be used. If that variable is not set, the environment variable `VMWARE_HOST` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **content_library_validate_certs**
   - Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
+  - If this variable is not set, the collection level variable `vmware_ops_validate_certs` will be used. If that variable is not set, the environment variable `VMWARE_VALIDATE_CERTS` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
+
+- **content_library_port**:
+  - str or int, The port used to authenticate to the vSphere vCenter that contains the cluster to configure.
+  - If this variable is not set, the collection level variable `vmware_ops_port` will be used. If that variable is not set, the environment variable `VMWARE_PORT` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
+### Library
 - **content_library_cluster_name**:
   - The name of the cluster in vSphere vCenter to configure.
 
 - **content_library_datacenter_name**:
   - The name of the datacenter in vSphere vCenter which contains the cluster to configure.
 
-- **content_library_port**:
-  - str or int, The port used to authenticate to the vSphere vCenter that contains the cluster to configure.
-
-### Library
 - **content_library_datastore_name**:
   - str, The name of the local datastore that should be used as storage for the content library. Required if state is `present`
 
@@ -58,9 +70,14 @@ N/A
 ### Other
 - **content_library_proxy_host**:
   - str, The hostname of a proxy host that should be used for all HTTPs communication by the role. Optional
+  - The format is a hostname or an IP.
+  - If this variable is not set, the collection level variable `vmware_ops_proxy_host` will be used. If that variable is not set, the environment variable `VMWARE_PROXY_HOST` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **content_library_proxy_port**:
   - str, The port of a proxy host that should be used for all HTTPs communication by the role. Optional
+  - If this variable is not set, the collection level variable `vmware_ops_proxy_host` will be used. If that variable is not set, the environment variable `VMWARE_PROXY_PORT` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 
 ## Example Playbook

roles/content_library/defaults/main.yml

@@ -1,2 +1,11 @@
 ---
+content_library_hostname: "{{ vmware_ops_collection_hostname }}"
+content_library_username: "{{ vmware_ops_collection_username }}"
+content_library_password: "{{ vmware_ops_collection_password }}"
+content_library_validate_certs: "{{ vmware_ops_collection_validate_certs }}"
+content_library_port: "{{ vmware_ops_collection_port }}"
+
+content_library_proxy_host: "{{ vmware_ops_collection_proxy_host }}"
+content_library_proxy_port: "{{ vmware_ops_collection_proxy_port }}"
+
 content_library_state: present

roles/content_library/tasks/main.yml

@@ -1,4 +1,8 @@
 ---
+- name: Import Collection Level Vars
+  ansible.builtin.include_vars:
+    file: "{{ role_path }}/../../vars/main.yml"
+
 - name: Check Mandatory Variables Are Defined
   ansible.builtin.assert:
     that:

roles/deploy_ovf/README.md

@@ -7,21 +7,33 @@ A role to deploy a VM from an OVF file. The OVF can be located on the `ansible_h
 N/A
 
 ## Role Variables
+
 ### Auth
+
 - **deploy_ovf_username**:
   - str, Required. The vSphere vCenter or ESXi host username.
+  - If this variable is not set, the collection level variable `vmware_ops_username` will be used. If that variable is not set, the environment variable `VMWARE_USER` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **deploy_ovf_password**:
   - str, Required. The vSphere vCenter or ESXi host password.
+  - If this variable is not set, the collection level variable `vmware_ops_password` will be used. If that variable is not set, the environment variable `VMWARE_PASSWORD` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **deploy_ovf_hostname**:
   - str, Required. The hostname or IP address of the vSphere vCenter or ESXi host.
+  - If this variable is not set, the collection level variable `vmware_ops_hostname` will be used. If that variable is not set, the environment variable `VMWARE_HOST` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **deploy_ovf_validate_certs**
   - bool, Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
+  - If this variable is not set, the collection level variable `vmware_ops_validate_certs` will be used. If that variable is not set, the environment variable `VMWARE_VALIDATE_CERTS` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **deploy_ovf_port**:
   - str or int, The port used to authenticate to the vSphere vCenter or ESXi host.
+  - If this variable is not set, the collection level variable `vmware_ops_port` will be used. If that variable is not set, the environment variable `VMWARE_PORT` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 
 ### Placement
@@ -113,10 +125,14 @@ N/A
 ### Other
 - **deploy_ovf_proxy_host**:
   - str, The hostname of a proxy host that should be used for all HTTPs communication by the role. Optional
+  - The format is a hostname or an IP.
+  - If this variable is not set, the collection level variable `vmware_ops_proxy_host` will be used. If that variable is not set, the environment variable `VMWARE_PROXY_HOST` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **deploy_ovf_proxy_port**:
   - str, The port of a proxy host that should be used for all HTTPs communication by the role. Optional
-
+  - If this variable is not set, the collection level variable `vmware_ops_proxy_host` will be used. If that variable is not set, the environment variable `VMWARE_PROXY_PORT` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 ## Example Playbook
 ```yaml

roles/deploy_ovf/defaults/main.yml

@@ -0,0 +1,9 @@
+---
+deploy_ovf_hostname: "{{ vmware_ops_collection_hostname }}"
+deploy_ovf_username: "{{ vmware_ops_collection_username }}"
+deploy_ovf_password: "{{ vmware_ops_collection_password }}"
+deploy_ovf_validate_certs: "{{ vmware_ops_collection_validate_certs }}"
+deploy_ovf_port: "{{ vmware_ops_collection_port }}"
+
+deploy_ovf_proxy_host: "{{ vmware_ops_collection_proxy_host }}"
+deploy_ovf_proxy_port: "{{ vmware_ops_collection_proxy_port }}"

roles/deploy_ovf/tasks/main.yml

@@ -1,4 +1,8 @@
 ---
+- name: Import Collection Level Vars
+  ansible.builtin.include_vars:
+    file: "{{ role_path }}/../../vars/main.yml"
+
 - name: Include Input Validation Tasks
   ansible.builtin.include_tasks: input_validation.yml
 

roles/esxi_maintenance_mode/README.md

@@ -9,28 +9,44 @@ N/A
 ## Role Variables
 
 ### Auth
+
 - **esxi_maintenance_mode_hostname**:
   - str, The hostname of the ESXi or vCenter on which you want to deploy the application. Required.
+  - If this variable is not set, the collection level variable `vmware_ops_hostname` will be used. If that variable is not set, the environment variable `VMWARE_HOST` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **esxi_maintenance_mode_username**:
   - str, The username to use to authenticate to the ESXi or vCenter on which you want to deploy the application. Required.
+  - If this variable is not set, the collection level variable `vmware_ops_username` will be used. If that variable is not set, the environment variable `VMWARE_USER` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **esxi_maintenance_mode_password**:
   - str, The password to use to authenticate to the ESXi or vCenter on which you want to deploy the application. Required.
+  - If this variable is not set, the collection level variable `vmware_ops_password` will be used. If that variable is not set, the environment variable `VMWARE_PASSWORD` will be used. At least one of these variables must be set to use this role.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **esxi_maintenance_mode_port**:
   - str or int, The port to use to authenticate to the ESXi or vCenter on which you want to deploy the application. Required.
+  - If this variable is not set, the collection level variable `vmware_ops_port` will be used. If that variable is not set, the environment variable `VMWARE_PORT` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **esxi_maintenance_mode_validate_certs**:
   - bool, If true then certificates will be validated when connecting to the ESXi or vCenter for auth. Optional.
+  - If this variable is not set, the collection level variable `vmware_ops_validate_certs` will be used. If that variable is not set, the environment variable `VMWARE_VALIDATE_CERTS` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 ### Proxy Options
 
 - **esxi_maintenance_mode_proxy_host**:
   - str, Address of a proxy that will receive all HTTPS requests and relay them.
+  - The format is a hostname or an IP.
+  - If this variable is not set, the collection level variable `vmware_ops_proxy_host` will be used. If that variable is not set, the environment variable `VMWARE_PROXY_HOST` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 - **esxi_maintenance_mode_proxy_port**:
   - int, Port of the HTTP proxy that will receive all HTTPS requests and relay them.
+  - If this variable is not set, the collection level variable `vmware_ops_proxy_host` will be used. If that variable is not set, the environment variable `VMWARE_PROXY_PORT` will be used.
+  - See the [authentication documentation](https://github.com/redhat-cop/cloud.vmware_ops/blob/main/docs/authentication.md) for examples.
 
 ### Other Options
 - **esxi_maintenance_mode_enable**:

roles/esxi_maintenance_mode/defaults/main.yml

@@ -1,2 +1,11 @@
 ---
+esxi_maintenance_mode_hostname: "{{ vmware_ops_collection_hostname }}"
+esxi_maintenance_mode_username: "{{ vmware_ops_collection_username }}"
+esxi_maintenance_mode_password: "{{ vmware_ops_collection_password }}"
+esxi_maintenance_mode_validate_certs: "{{ vmware_ops_collection_validate_certs }}"
+esxi_maintenance_mode_port: "{{ vmware_ops_collection_port }}"
+
+esxi_maintenance_mode_proxy_host: "{{ vmware_ops_collection_proxy_host }}"
+esxi_maintenance_mode_proxy_port: "{{ vmware_ops_collection_proxy_port }}"
+
 esxi_maintenance_mode_enable: true

roles/esxi_maintenance_mode/tasks/main.yml

@@ -1,4 +1,8 @@
 ---
+- name: Import Collection Level Vars
+  ansible.builtin.include_vars:
+    file: "{{ role_path }}/../../vars/main.yml"
+
 - name: Check Mandatory Variables Are Defined
   ansible.builtin.assert:
     that: