Ansible version checks and other fixes

- Added requirements about Ansible playbooks
  warning about version mismatches
- Various cleanups
  - Standardizing language across ansible playbook requirements
  - Fixing metadata
  - Removed duplicate requirement
  - Small formatting fixes

Issue-ID: VNFRQTS-895
Signed-off-by: Lovett, Trevor <trevor.lovett@att.com>
Change-Id: Ic8c44461679d7e5941ec252cbd2c57b213d71c4f

1 files changed, 168 insertions, 139 deletions

diff --git a/docs/Chapter7/Configuration-Management.rst b/docs/Chapter7/Configuration-Management.rst
index f32f4eb..28bad0e 100755
--- a/docs/Chapter7/Configuration-Management.rst
+++ b/docs/Chapter7/Configuration-Management.rst
@@ -1394,7 +1394,7 @@ Ansible Client Requirements
     :id: R-54373
     :target: VNF or PNF
     :keyword: MUST
-    :updated: frankfurt
+    :updated: guilin
 
     The VNF or PNF Provider **MUST** provide Ansible playbooks that are
     compatible with the Operator’s deployed versions of Ansible and Python.
@@ -1415,11 +1415,11 @@ Ansible Client Requirements
     :id: R-82018
     :target: VNF or PNF
     :keyword: MUST
-    :updated: dublin
+    :updated: guilin
 
     The VNF or PNF **MUST** load the Ansible Server SSH public key onto VNF or
     PNF VM(s) /root/.ssh/authorized_keys as part of instantiation. Alternative,
-    is for Ansible Server SSH public key to be loaded onto VNF or PNF VM(s)
+    is for Ansible Server SSH public key to be loaded onto VNF or PNF
     under /home/<Mechanized user ID>/.ssh/authorized_keys as part of
     instantiation, when a Mechanized user ID is created during instantiation,
     and Configure and all playbooks are designed to use a mechanized user ID
@@ -1436,16 +1436,16 @@ Ansible Client Requirements
 
 .. req::
     :id: R-92866
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :updated: dublin
 
-    The VNF or PNF **MUST** include as part of post-instantiation configuration
-    done by Ansible Playbooks the removal/update of the SSH public key from
-    /root/.ssh/authorized_keys, and update of SSH keys loaded through
-    instantiation to support Ansible. This may include creating Mechanized user
-    ID(s) used by the Ansible Server(s) on VNF VM(s) and uploading and
-    installing new SSH keys used by the mechanized use ID(s).
+    The VNF or PNF Provider **MUST** include as part of post-instantiation
+    configuration done by Ansible Playbooks the removal/update of the SSH
+    public key from ``/root/.ssh/authorized_keys``, and update of SSH keys
+    loaded through instantiation to support Ansible. This may include creating
+    Mechanized user ID(s) used by the Ansible Server(s) on VNF VM(s) and
+    uploading and installing new SSH keys used by the mechanized use ID(s).
 
 .. req::
     :id: R-97345
@@ -1506,35 +1506,35 @@ Ansible Client Requirements
 
 .. req::
     :id: R-94567
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: casablanca
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **MUST** provide Ansible playbooks that are designed to run
+    The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run
     using an inventory hosts file in a supported format with only IP addresses
     or IP addresses and VM/VNF or PNF names.
 
 .. req::
     :id: R-67124
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: casablanca
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **MUST** provide Ansible playbooks that are designed to run
+    The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run
     using an inventory hosts file in a supported format; with group names
     matching VNFC 3-character string adding "vip" for groups with virtual IP
     addresses shared by multiple VMs as seen in examples provided in Appendix.
 
 .. req::
     :id: R-24482
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: casablanca
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **MUST** provide Ansible playbooks that are designed to run
+    The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run
     using an inventory hosts file in a supported format; with site group that
     shall be used to add site specific configurations to the target VNF or PNF
     VM(s) as needed.
@@ -1547,58 +1547,77 @@ Ansible server (local host) and/or the target VM (s) in order to
 complete the desired action.
 
 .. req::
-    :id: R-49751
-    :target: VNF or PNF
+    :id: R-49396
+    :target: VNF or PNF Provider
     :keyword: MUST
-    :introduced: casablanca
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **MUST** support Ansible playbooks that are compatible with
-    Ansible version 2.6 or later.
+    The VNF or PNF Provider's Ansible playbooks **MUST** support each APPC/SDN-C
+    VNF or PNF action by invocation of **one** playbook [#7.3.4]_. The playbook
+    will be responsible for executing all necessary tasks (as well as calling
+    other playbooks) to complete the request.
 
 .. req::
-    :id: R-40293
-    :target: VNF or PNF
-    :keyword: MUST
-    :updated: dublin
+    :id: R-33280
+    :target: VNF or PNF Provider
+    :keyword: MUST NOT
+    :updated: guilin
 
-    The VNF or PNF **MUST** make available playbooks that conform
-    to the ONAP requirement.
+    The VNF or PNF Provider's Ansible playbooks **MUST NOT** contain instance
+    specific values that can not be provided by a parameter to the playbook.
 
 .. req::
-    :id: R-49396
-    :target: VNF or PNF
-    :keyword: MUST
-    :updated: dublin
+   :id: R-195620
+   :keyword: SHOULD
+   :target: VNF or PNF Provider
+   :introduced: guilin
 
-    The VNF or PNF **MUST** support each APPC/SDN-C VNF or PNF action
-    by invocation of **one** playbook [#7.3.4]_. The playbook will be
-    responsible for executing all necessary tasks (as well as calling other
-    playbooks) to complete the request.
+   The VNF or PNF Provider's Ansible playbooks **SHOULD** compare the version(s)
+   of Ansible that the VNF Provider developed and tested against to the
+   ``ansible_version.full`` value during playbook execution, and issue a
+   ``WARNING`` message if the operator version is not one of the tested
+   versions.
 
 .. req::
-    :id: R-33280
-    :target: VNF or PNF
-    :keyword: MUST NOT
-    :updated: dublin
+   :id: R-918136
+   :keyword: MUST NOT
+   :target: VNF or PNF Provider
+   :introduced: guilin
 
-    The VNF or PNF **MUST NOT** use any instance specific parameters
-    in a playbook.
+   The VNF or PNF Provider's Ansible playbooks **MUST NOT** fail due to
+   a mismatched version check as specified in R-918136. The warning message
+   should be issued, and the playbook execution should continue as normal.
+
+.. req::
+   :id: R-444446
+   :keyword: SHOULD
+   :target: VNF or PNF Provider
+   :introduced: guilin
+
+   The VNF or PNF Provider's Ansible playbooks **SHOULD** issue log messages
+   in the same format as Ansible's default messages:
+   ``[<Log Level>]: <message>``
+
+   Example:
+
+      ``[WARNING]: Ansible version 2.9.3 does not match a known,
+      tested version: 2.8.1, 2.8.2``
 
 .. req::
     :id: R-48698
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
-    :updated: frankfurt
-
-    The VNF or PNF **MUST** utilize information from key value pairs that will
-    be provided by the Ansible Server as "extra-vars" during invocation to
-    execute the desired VNF or PNF action. The "extra-vars" attribute-value
-    pairs are passed to the Ansible Server by an APPC/SDN-C as part of the
-    Rest API request. If the playbook requires files, they must also be
-    supplied using the methodology detailed in the Ansible Server API, unless
-    they are bundled with playbooks, example, generic templates. Any files
-    containing instance specific info (attribute-value pairs), not obtainable
+    :updated: guilin
+
+    The VNF or PNF Provider's Ansible playbooks **MUST** utilize information
+    from key value pairs that will be provided by the Ansible Server as
+    ``extra-vars`` during invocation to execute the desired VNF or PNF action.
+    The "extra-vars" attribute-value pairs are passed to the Ansible Server by
+    an APPC/SDN-C as part of the Rest API request. If the playbook requires
+    files, they must also be supplied using the methodology detailed in the
+    Ansible Server API, unless they are bundled with playbooks, example,
+    generic templates. Any files containing instance specific info
+    (attribute-value pairs), not obtainable
     from any ONAP inventory databases or other sources, referenced and used as
     input by playbooks, shall be provisioned (and distributed) in advance of
     use, e.g., VNF or PNF instantiation. Recommendation is to avoid these
@@ -1614,12 +1633,13 @@ will be considered to have failed.
 
 .. req::
     :id: R-43253
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **MUST** use playbooks designed to allow Ansible
-    Server to infer failure or success based on the "PLAY_RECAP" capability.
+    The VNF or PNF Provider's Ansible playbooks **MUST** be designed to allow
+    Ansible Server to infer failure or success based on the "PLAY_RECAP"
+    capability.
 
     **Note**: There are cases where playbooks need to interpret results
     of a task and then determine success or failure and return result
@@ -1627,26 +1647,26 @@ will be considered to have failed.
 
 .. req::
     :id: R-50252
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
-    :updated: frankfurt
+    :updated: guilin
 
-    The VNF or PNF **MUST** write to a response file in JSON format that will
-    be retrieved and made available by the Ansible Server if, as part of a VNF
-    or PNF action (e.g., audit), a playbook is required to return any VNF or
-    PNF information/response. The text files must be written in the main
-    playbook home directory, in JSON format. The JSON file must be created for
-    the VNF or PNF with the name '<VNF or PNF name>_results.txt'. All playbook
+    The VNF or PNF Provider's Ansible playbooks **MUST** write to a response
+    file in JSON format that will be retrieved and made available by the
+    Ansible Server if, as part of a VNF or PNF action (e.g., audit), a playbook
+    is required to return any VNF or PNF information/response. The text files
+    must be written in the main playbook home directory, in JSON format. The
+    JSON file must be created for the VNF or PNF with the name '<VNF or PNF name>_results.txt'. All playbook
     output results, for all VNF VMS or PNF Server/Blades, to be provided as a
     response to the request, must be written to this response file.
 
 .. req::
     :id: R-51442
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: SHOULD
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **SHOULD** use playbooks that are designed to
+    The VNF or PNF Provider's Ansible playbooks **SHOULD** be designed to
     automatically 'rollback' to the original state in case of any errors
     for actions that change state of the VNF or PNF (e.g., configure).
 
@@ -1659,11 +1679,11 @@ will be considered to have failed.
 
 .. req::
     :id: R-58301
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: SHOULD NOT
     :updated: dublin
 
-    The VNF or PNF **SHOULD NOT** use playbooks that make requests to
+    The VNF or PNF Provider's Ansible playbooks **SHOULD NOT** make requests to
     Cloud resources e.g. Openstack (nova, neutron, glance, heat, etc.);
     therefore, there is no use for Cloud specific variables like Openstack
     UUIDs in Ansible Playbook related artifacts.
@@ -1679,24 +1699,24 @@ will be considered to have failed.
 
 .. req::
     :id: R-02651
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: SHOULD
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **SHOULD** use available backup capabilities to save a
-    copy of configuration files before implementing changes to support
-    operations such as backing out of software upgrades, configuration
-    changes or other work as this will help backing out of configuration
-    changes when needed.
+    The VNF or PNF Provider's Ansible playbooks **SHOULD** use available backup
+    capabilities to save a copy of configuration files before implementing
+    changes to support operations such as backing out of software upgrades,
+    configuration changes or other work as this will help backing out of
+    configuration changes when needed.
 
 .. req::
     :id: R-43353
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF **MUST** return control from Ansible Playbooks only after
-    all tasks performed by playbook are fully complete, signaling that the
+    The VNF or PNF Provider's Ansible playbooks **MUST** return control only
+    after all tasks performed by playbook are fully complete, signaling that the
     playbook completed all tasks. When starting services, return control
     only after all services are up. This is critical for workflows where
     the next steps are dependent on prior tasks being fully completed.
@@ -1818,37 +1838,38 @@ performs a full VNF or PNF health check.
 
 .. req::
     :id: R-24189
-    :target: VNF or PNF
-    :keyword: SHOULD
+    :target: VNF or PNF Provider
+    :keyword: MUST
     :introduced: casablanca
-    :updated: dublin
+    :updated: guilin
 
-    The VNF or PNF provider **MUST** deliver a new set of playbooks that
+    The VNF or PNF Provider **MUST** deliver a new set of Ansible playbooks that
     includes all updated and unchanged playbooks for any new revision to an
     existing set of playbooks.
 
 .. req::
     :id: R-49911
-    :target: VNF or PNF
-    :keyword: SHOULD
-    :updated: dublin
+    :target: VNF or PNF Provider
+    :keyword: MUST
+    :updated: guilin
     :introduced: casablanca
 
-    The VNF or PNF provider **MUST** assign a new point release to the updated
-    playbook set. The functionality of a new playbook set must be tested before
-    it is deployed to the production.
+    The VNF or PNF Provider **MUST** assign a new point release to the updated
+    Ansible playbook set. The functionality of a new playbook set must be
+    tested before it is deployed to the production.
 
 .. req::
     :id: R-42333
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
+    :updated: guilin
 
-    The VNF or PNF playbooks targeting a subset of VMs (or servers/blades) part
-    of a VNF (or PNF) instance **MUST** be designed to use the VNF or PNF
-    inventory host file and to use a parameter named target_vm_list to provide
-    the subset of VMs in the VNF instance specifically targeted by the
-    playbook.
+    The VNF or PNF Provider's Ansible playbooks that target a subset of VMs (or
+    servers/blades) part of a VNF (or PNF) instance **MUST** be designed to use
+    the VNF or PNF inventory host file and to use a parameter named
+    ``target_vm_list`` to provide the subset of VMs in the VNF instance
+    specifically targeted by the playbook.
 
     NOTE: Example of such playbooks would be playbooks used to configure VMs
     added to a VNF instance as part of a scale-out/up or scale-in/down
@@ -1857,102 +1878,110 @@ performs a full VNF or PNF health check.
 
 .. req::
     :id: R-39003
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
+    :updated: guilin
 
-    The VNF or PNF provider **MUST** store passwords and other attributes
-    that must remain secret in JSON, YAML or INI files that can be
-    encrypted/decrypted using Ansible Vault capabilities.
+    The VNF or PNF Provider's Ansible playbooks **MUST** store passwords and
+    other attributes that must remain secret in JSON, YAML or INI files that
+    can be encrypted/decrypted using Ansible Vault capabilities.
 
 .. req::
     :id: R-46823
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
 
-    The VNF or PNF provider **MUST** store passwords and other attributes that
-    must remain secret in JSON, YAML or INI with differentiated names when
-    passwords and secrets vary from environment to environment. Example, name
-    must include <Mechanized user ID>_...json or <Mechanized user ID>_...xml
-    when labs and production use different passwords and/or secrets. The
-    <Mechanized user ID> is discovered from the environment
-    /etc/ansible/ansible.cfg where the playbook runs.
+    The VNF or PNF Provider's Ansible playbooks **MUST** store passwords and
+    other attributes that must remain secret in JSON, YAML or INI with
+    differentiated names when passwords and secrets vary from environment to
+    environment. Example, name must include <Mechanized user ID>_...json or
+    <Mechanized user ID>_...xml when labs and production use different passwords
+    and/or secrets. The <Mechanized user ID> is discovered from the environment
+    ``/etc/ansible/ansible.cfg`` where the playbook runs.
 
 .. req::
     :id: R-83092
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
+    :updated: guilin
 
-    The VNF or PNF provider **MUST** develop playbooks that load passwords
+    The VNF or PNF Provider's Ansible playbooks **MUST** load passwords
     and other attributes that must remain secret from JSON, YAML or INI files
     that can be encrypted/decrypted using Ansible Vault capabilities.
 
 .. req::
     :id: R-09209
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
+    :update: guilin
 
-    The VNF or PNF Provider **MUST** store any playbook configuration data
-    that requires encryption (passwords, secrets, etc.) in a JSON (.json),
-    YAML (.yaml|.yml) or INI (.ini) file, which will be placed in
-    <VNF type>/<Version>/ansible/vars directory.
+    The VNF or PNF Provider's Ansible playbooks **MUST** store any playbook
+    configuration data that requires encryption (passwords, secrets, etc.) in
+    a JSON (.json), YAML (.yaml|.yml) or INI (.ini) file, which will be placed
+    in ``<VNF type>/<Version>/ansible/vars`` directory.
 
 .. req::
     :id: R-56988
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
 
-    The VNF or PNF Provider **MUST** load any playbook configuration data
-    that requires encryption (passwords, secrets, etc.) in a JSON (.json),
+    The VNF or PNF Provider's Ansible playbooks **MUST** load any configuration
+    data that requires encryption (passwords, secrets, etc.) in a JSON (.json),
     YAML (.yaml|.yml) or INI (.ini) file, from the
-    <VNF type>/<Version>/ansible/vars directory.
+    ``<VNF type>/<Version>/ansible/vars`` directory.
 
 .. req::
     :id: R-20988
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
+    :updated: guilin
 
-    The VNF or PNF provider **MUST** develop playbooks that do not log or
+    The VNF or PNF Provider's Ansible playbooks **MUST** not log or
     display passwords and other attributes that must remain secret when
     running playbook in debug mode.
 
-    NOTE: Use "no_log: True"
+    NOTE: Use ``no_log: True``
 
 .. req::
     :id: R-53245
-    :target: VNF or PNF
-    :keyword: MUST
+    :target: VNF or PNF Provider
+    :keyword: MUST NOT
     :introduced: frankfurt
+    :updated: guilin
 
-    The VNF or PNF provider **MUST** provide playbooks that do not require
+    The VNF or PNF Provider's Ansible playbooks **MUST** require
     passwords or secrets to be passed in clear text in the command line or
     Rest API request to run the playbook.
 
 .. req::
     :id: R-78640
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: SHOULD
     :introduced: frankfurt
+    :updated: guilin
 
-    The VNF or PNF provider **SHOULD** provide a single YAML or JSON file
-    with all the passwords and secrets to reduce the number of files to be
-    decrypted/encrypted before on-boarding into the central repository.
+    The VNF or PNF Provider's Ansible playbooks **SHOULD** provide a single
+    YAML or JSON file with all the passwords and secrets to reduce the number
+    of files to be decrypted/encrypted before on-boarding into the central
+    repository.
 
 .. req::
     :id: R-88786
-    :target: VNF or PNF
+    :target: VNF or PNF Provider
     :keyword: MUST
     :introduced: frankfurt
+    :updated: guilin
 
-    The VNF or PNF provider **SHOULD** place the passwords and secrets to
-    be edited at the top of the single YAML or JSON file with all the secrets,
-    and the (default) ones that are to remain unchanged towards the bottom,
-    with commentary separating them.
+    The VNF or PNF Provider's Ansible playbooks **SHOULD** place the passwords
+    and secrets to be edited at the top of the single YAML or JSON file with
+    all the secrets, and the (default) ones that are to remain unchanged '
+    towards the bottom, with commentary separating them.
 
 .. req::
     :id: R-88002
@@ -1960,7 +1989,7 @@ performs a full VNF or PNF health check.
     :keyword: MUST
     :introduced: frankfurt
 
-    The VNF or PNF provider **MUST** use a pre-agreed upon password to encrypt
+    The VNF or PNF Provider **MUST** use a pre-agreed upon password to encrypt
     the Ansible Vault file, or provide the vault password used to encrypt
     the file to the customer, in a secure manner, to allow the customer to
     decrypt/encrypt (rekey) Ansible Vault files before they are checked