diff options
Diffstat (limited to 'docs')
| -rwxr-xr-x | docs/Chapter7/Configuration-Management.rst | 147 | ||||
| -rw-r--r-- | docs/Chapter8/Ansible-Playbook-Examples.rst | 194 |
2 files changed, 264 insertions, 77 deletions
diff --git a/docs/Chapter7/Configuration-Management.rst b/docs/Chapter7/Configuration-Management.rst index 8586482..f32f4eb 100755 --- a/docs/Chapter7/Configuration-Management.rst +++ b/docs/Chapter7/Configuration-Management.rst @@ -1394,10 +1394,12 @@ Ansible Client Requirements :id: R-54373 :target: VNF or PNF :keyword: MUST - :updated: dublin + :updated: frankfurt - The VNF or PNF **MUST** have Python >= 2.6 on the endpoint VM(s) - of a VNF or PNF on which an Ansible playbook will be executed. + The VNF or PNF Provider **MUST** provide Ansible playbooks that are + compatible with the Operator’s deployed versions of Ansible and Python. + As the Ansible runtime itself is not deployed as part of ONAP, the ONAP + project cannot dictate the specific versions supported. .. req:: :id: R-35401 @@ -1587,7 +1589,7 @@ complete the desired action. :id: R-48698 :target: VNF or PNF :keyword: MUST - :updated: dublin + :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 @@ -1597,7 +1599,7 @@ complete the desired action. 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 an + 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 instance specific, manually created in advance of instantiation, files. @@ -1627,7 +1629,7 @@ will be considered to have failed. :id: R-50252 :target: VNF or PNF :keyword: MUST - :updated: dublin + :updated: frankfurt 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 @@ -1635,8 +1637,8 @@ will be considered to have failed. 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 or PNF VMs, to be provided as a response to the - request, must be written to this response file. + 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 @@ -1836,6 +1838,133 @@ performs a full VNF or PNF health check. 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 + :keyword: MUST + :introduced: frankfurt + + 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. + + 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 + operation. Such playbook is expected to also need to perform + configuration/reconfiguration tasks part of the base VNF instance build. + +.. req:: + :id: R-39003 + :target: VNF or PNF + :keyword: MUST + :introduced: frankfurt + + 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. + +.. req:: + :id: R-46823 + :target: VNF or PNF + :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. + +.. req:: + :id: R-83092 + :target: VNF or PNF + :keyword: MUST + :introduced: frankfurt + + The VNF or PNF provider **MUST** develop playbooks that 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 + :keyword: MUST + :introduced: frankfurt + + 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. + +.. req:: + :id: R-56988 + :target: VNF or PNF + :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), + YAML (.yaml|.yml) or INI (.ini) file, from the + <VNF type>/<Version>/ansible/vars directory. + +.. req:: + :id: R-20988 + :target: VNF or PNF + :keyword: MUST + :introduced: frankfurt + + The VNF or PNF provider **MUST** develop playbooks that do not log or + display passwords and other attributes that must remain secret when + running playbook in debug mode. + + NOTE: Use "no_log: True" + +.. req:: + :id: R-53245 + :target: VNF or PNF + :keyword: MUST + :introduced: frankfurt + + The VNF or PNF provider **MUST** provide playbooks that do not 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 + :keyword: SHOULD + :introduced: frankfurt + + 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. + +.. req:: + :id: R-88786 + :target: VNF or PNF + :keyword: MUST + :introduced: frankfurt + + 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. + +.. req:: + :id: R-88002 + :target: VNF or PNF Provider + :keyword: MUST + :introduced: frankfurt + + 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 + into the central repository for distribution. Ansible API Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1893,7 +2022,7 @@ Table 8. APPC/SDN-C APIs and NETCONF Commands | | |The JSON file for |NodeList must list | | | |this VNF or PNF |IP addresses or DNS | | | |action is required |supported FQDNs of | -| | |to set "PushJobFlag"|an example VNF | +| | |to set "PushJobFlag"|the VNF instance | | | |to "True" and |on which to | | | |"GetOutputFlag" to |execute playbook. | | | |"True". The "Node" | | diff --git a/docs/Chapter8/Ansible-Playbook-Examples.rst b/docs/Chapter8/Ansible-Playbook-Examples.rst index acd8c30..9e4604c 100644 --- a/docs/Chapter8/Ansible-Playbook-Examples.rst +++ b/docs/Chapter8/Ansible-Playbook-Examples.rst @@ -26,9 +26,9 @@ to: :doc:`APPC Ansible Adapter <../../../../appc/deployment.git/docs/APPC Ansibl Guidelines for Playbooks to properly integrate with APPC/SDN-C ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**NOTE**: To support concurrent requests to multiple VNF instances of same or -different type, VNF files dynamically created by playbooks with VNF specific -default values are kept or created in separate directories. +**NOTE**: To support concurrent requests to multiple playbooks, targeting VNF +instances of same or different type, VNF files dynamically created by playbooks +with VNF specific default values are kept or created in separate directories. VNF inventory hosts file names include the VNF instance name and are now created under base ``inventory`` directory to preserve properties of (global) @@ -46,10 +46,9 @@ vfdb9904v VNF instance:** NOTE: To preserve Ansible inventory/group_vars capability, that makes group_vars contents global variables available to all playbooks, when they - reside in the inventory directory, guidelines are being updated to name the + reside in the inventory directory, guidelines were updated to name the VNF inventory hosts file as (a flat file) <VNFName>hosts, stored in the - inventory directory, not a subdirectory under inventory. In the above - example: vfdb9904vhosts (removed / VNF name and hosts vfdb9904/vhosts) + inventory directory, not a subdirectory under inventory. **Example of corresponding APPC/SDN-C API Call from ONAP – Ansible Server Specifications:** @@ -76,7 +75,7 @@ Comments: - An ID number is assigned to each request. This ID number is used to track request down to completion and provide status to APPC/SDN-C - when requested. + upon request for status. - Playbook Name relative path provided in the request as PlaybookName. @@ -95,7 +94,7 @@ above: Each Ansible Server or cluster is assigned its own identification to be used to authenticate to VNF VMs using Ansible Server or cluster specific set of SSH keys that may be rotated regularly. Here a hosts file, without any SSH key -credentials, to run ansible-playbook listed in this example above (IP +credentials, to run ansible-playbook command, listed in example above (NOTE: IP addresses were scrubbed): .. code-block:: text @@ -121,11 +120,11 @@ addresses were scrubbed): Virtual IP addresses that can be used by multiple VMs, usually, used by the active VM of an active-standby pair, are placed under a group named after the -VNFC (VM) type, plus "vip" string, example of such a group name "oamvip". Also -new on this release, an inventory hosts file site (group) with all groups as -children (see last three lines in above example), to load site specific -variables like NTP, DNS IP addresses, and other site specific variables, making -them global variables to be used by playbooks, namely, configure playbook. +VNFC (VM) type, plus "vip" string, example of such a group name "oamvip". An +inventory hosts file site also contains a (group) with all groups as children +(see last three lines in above example), to load site specific variables like +NTP, DNS IP addresses, and other site specific variables, making them global +variables to be used by playbooks, namely, configure playbook. **NOTE**: APPC/SDN-C requests to run Playbooks/Cookbooks target a specific VNF instance, but could be limited to one VM or one type of VM by the request @@ -144,14 +143,14 @@ Certain VNF Type global variables, for example site specific variables, were moved under inventory/group_vars files in the Beijing release. This way those variables and respective values are available to all playbooks without being explicitly referenced through an include vars statement. Also creating -templates that are VNF Type specific, but moving away from static files that +templates that are VNF Type specific moving away from static files that are VNF instance specific. Any remaining VNF instance specific variables that cannot be obtained from -A&AI or other sources that still need to be created or edited manually, -in advance of VNF instantiation, shall be created under ``ansible/vars`` -directory. Recommendation is to use JSON files, explicitly referenced by -the playbooks, for this purpose, example: +inventory (A&AI) or other sources, that still need to be created or edited +manually, in advance of VNF instantiation, shall be created under +``ansible/vars`` directory. Recommendation is to use JSON or YAML files, +explicitly referenced by the playbooks, for this purpose, example: ``<VNF_instance_name>.json``. **Example of playbook task explicitly referencing a VNF instance specific json @@ -178,15 +177,24 @@ file and loading the contents as global variables**: - debug ... + # Just another example using YAML file + - name: load vars in a file + hosts: rdb + ... + vars_files: + - ../vars/{{ vnf_instance }}.yml + $ ls -1 ../vars vfdb9904v.json vfdb9905v.json vfdb9906v.json - vfdb9907v.json - vfdb9908v.json + vfdb9904v.yml + vfdb9905v.yml + vfdb9906v.yml -Parameters like VNF names, VNFC names, OA&M IP addresses will be extracted + +Parameters like VNF names, VNFC names, OA&M IP addresses are extracted from the inventory database (A&AI) by APPC/SDN-C and then passed down to Ansible Server in a NodeList attribute, as part of APPC/SDN-C request through REST API. The Ansible Server Rest API uses the NodeList contents and @@ -298,8 +306,8 @@ targeting multiple VNF instances – inventory hosts file:** To avoid inventory hosts file overwrites or collisions between multiple concurrently running VNF instance requests, chosen approach is for each VNF instance hosts file, to be stored under the Ansible Server Playbooks -root directory, under the inventory subdirectory, on an inventory hosts file -named after the VNF instance, as follows: +root directory (ansible), under the inventory subdirectory, on an inventory +hosts file named after the VNF instance, as follows: .. code-block:: text @@ -345,11 +353,11 @@ contain VNF instance name as part of the name. include_vars: ../vars/{{ vnf_instance }}default_args.yml -Again, this has originated from previously re-factored playbooks, now being +Above example has originated from previously re-factored playbooks now being phased out. Direction is to move away from having to create VNF instance -specific files with VNF instance default variables whenever possible. Moving to -extract these values from inventory databases and provide them to Ansible -Server as part of APPC/SDN-C request, but may be used in a transition +specific files with VNF instance default variables to the extent possible. +Moving to extract these values from inventory databases and provide them to +Ansible Server as part of APPC/SDN-C request, may be used in a transition from having everything stored in the Ansible Server to APPC/SDN-C extracting and providing VNF instance specific attribute-value pairs to the Ansible Server as part of the request. @@ -395,7 +403,7 @@ definitions: **VNF type a.k.a VNF Function Code** - Based on current naming convention, each Virtual Network Function is assigned a 4 character string (example vfdb), these are 4 characters in the VNF instance name, followed by (4) numbers, -ending in a "v", but the naming convention is evolving to include geographical +ending in a "v". The naming convention has evolved to include geographical location. VNF instance name in some cases corresponds to the stack name for the VNF when VNF instance is built based on a single module, single stack. Example of VNF instance name: vfdb9904v. All VNF performing this function, running the @@ -414,11 +422,9 @@ running on the VNF for which the playbooks were developed. VNF configuration steps may change from release to release and this <Version> in the path will allow the Ansible Server to host playbooks associated with each software release. And run the playbooks that match -the software release running on each VNF instance. APPC/SDN-C -does not support playbook versioning only latest playbook is supported or a -hard coded version that later should become a variable to allow multiple -actively, in use, playbook versions,to be picked according to VNF -release/version. +the software release running on each VNF instance. APPC/SDN-C now support +playbook versioning passed as a variable to APP-C to allow multiple +actively, in use, playbook versions to be picked to match VNF release/version. **Playbook Function** - A name associated with a life cycle management task(s) performed by the playbook(s) stored in this directory. It should @@ -426,7 +432,7 @@ clearly identify the type of action(s) performed by the main playbook and possibly other playbooks stored in this same directory. Ideally, playbook function would match APPC/SDN-C corresponding command or function that is performed by the main playbook in this directory. Following Ansible -naming standards main playbook is usually named site.yml. There can be other +naming standards, main playbook, is named site.yml. There can be other playbooks on the same directory that use a subset of the roles used by the main playbook site.yml. Examples of Playbook Function directory names(matching APPC/SDN-C command name in lowercase): @@ -436,11 +442,14 @@ APPC/SDN-C command name in lowercase): - ``healthcheck`` – Contains VNF health check playbook(s), roles,... -- ``stop`` – Contains VNF application stop (stopApplication) playbook(s), - roles,... +- ``stopapplication`` – Contains VNF application stop (stopApplication) + playbook(s), roles,... -- ``start`` – Contains VNF application start (startApplication) playbook(s), - roles,... +- ``startapplication`` – Contains VNF application start (startApplication) + playbook(s), roles,... + +- ``restartapplication`` – Contains VNF application restart + (restartApplication) playbook(s), roles,... - ``configbackup`` – Contains VNF configuration backup (ConfigBackup) playbook(s), roles,... @@ -475,6 +484,57 @@ APPC/SDN-C command name in lowercase): - ``upgradebackout`` – Contains VNF (SoftwareUpgrade) back out (UpgradeBackout) playbook(s), roles,... +- ``license`` – Contains a playbook to manage licenses, add, upgrade, + delete, renew, etc. + +- ``starttraffic`` – Contains a playbook used for traffic management (start) + +- ``stoptraffic`` – Contains a playbook used for traffic management (stop) + +- ``distributetraffic`` – Contains a playbook used for traffic management + (distribute/redistribute) + +- ``statustraffic`` – Contains a playbook used to check status of traffic + (started, stopped, etc.) + +- ``preconfigcheck`` – Contains post-instantiation pre-configuration check + playbook(s) that makes no configuration changes to the VNF instance, just + verifies all conditions are met to successfully run preconfig and/or + configure playbooks + +- ``preconfig`` – Contains post-instantiation pre-configuration playbook(s), + that is to run before running the configure playbook + +- ``postconfig`` – Contains post-instantiation post-configuration playbook(s), + that is to run after running the configure playbook, example, to integrate + VNFs of different types + +- ``provision`` – Contains a playbook to run on demand, as needed, load or + update provisioning data onto VNF instances + +Other playbook actions were added and are supported, example of playbooks +supported to run before and after Openstack nova commands: + +- prerebuild & postrebuild + +- premigrate & postmigrate + +- preevacuate & postevacuate + +Other playbook actions in use not yet supported by APP-C: + +- ``postrestart`` – Contains a playbook used to perform tasks after restarting + VNF application or VNF instance or a single VM + +- ``restartpods`` – Contains a playbook used to perform tasks to restart + application containers + +- ``user_management`` – Contains a playbook used to manage user accounts on + demand (add, update, delete) as part of VNF instance life cycle management + +- ``preinstantiate`` – Contains pre-instantiation playbook(s) to perform + preparation tasks in advance of instantiation of a VNF instance + Directory structure to allow hosting multiple version sets of playbooks, for the same VNF type, to be hosted in the runtime environment on the Ansible Servers. Generic directory structure: @@ -538,7 +598,7 @@ OR (INI format accepted/supported by Ansible) **NOTE**: Requirement remains while manual actions to create or edit VNF or PNF -instance specific files are supported. All files manually created or edited +instance specific files are supported all files manually created or edited should be placed in this one directory (``ansible/vars``). **Ansible Directory for site specific attribute-value pairs (in INI format) @@ -573,31 +633,30 @@ Optional – Example – License file**: <VNF type>/<Version>/ansible/ -There is a soft link to the latest set of Ansible Playbooks for each VNF type. -This will be deprecated with (A&AI) inventory support for VNF version. - VNF type directories use A&AI inventory VNF function code. Ansible -Playbooks will be stored on a Cinder Volume mounted on the Ansible +Playbooks will be stored on a (Cinder) Volume mounted on the Ansible Servers as /storage that is used as a local cache for playbooks and other related artifacts cloned or pulled (updates) from central (git) repository. Example: -``/storage/vfdb/latest/ansible`` – This soft link point to the latest set of -playbooks (or the only set) - ``/storage/vfdb/V16.1/ansible`` – Root directory for database VNF Ansible Playbooks for release 16.1 **CAUTION**: To support this directory structure as the repository to store Ansible Playbooks run by APPC/SDN-C, APPC/SDN-C API in the Ansible -Server side needs to be configured to run playbooks from directory, not MySQL -database as was the case in the original Ansible proof-of-concept. +Server side needs to be configured to run playbooks from this directory. Ansible Server HTTP will be configured to support APPC/SDN-C REST API requests to run playbooks as needed, against specific VNF instances, or -specific VM(s) as specified in the request(pending APPC/SDN-C tests and -implementation details to target single VM in VNF). +specific VM(s) as specified in the request. When a playbook action is expected +to target a subset of VMs in a VNF instance, VNF instance inventory hosts file +is expected to be used, and an extra-vars parameter, named target_vm_list with +the list of VMs to be targeted by the playbook, is expected to be provided to +run specific actions targeting the VM subset. The attribute target_vm_list may +point to a single name or single IP address or a list of names or IP addresses +in between double-quotes with names or IPs seprated by comma, example, +target_vm_list="name1,name2". APPC/SDN-C REST API to Ansible Server is documented separately and can be found under ONAP (onap.org). @@ -694,7 +753,7 @@ With VM names and IP addresses, template inventory names setting oam rdb -With VM names and IP addresses, template inventory names setting +With VNFC names and IP addresses, template inventory names setting "InventoryNames": "VNFC" .. code-block:: text @@ -739,25 +798,25 @@ Ansible Server. artifacts to Development Ansible Server with connectivity to central repository. -#. Create full directory (using –p option below) to store Ansible - Playbooks and other artifacts under /storage (or other configured) - file system. +#. Unzip packaged playbooks or manually create full directory (using –p + option below) to store Ansible Playbooks and other artifacts under /storage + (or other configured) file system. - #. Includes VNF type using VNF function code 4 characters under - /storage. + Includes VNF type using VNF function code 4 characters under + /storage. - #. Includes VNF "Version" directory as part of the path to store - playbooks for this VNF version. + Includes VNF "Version" directory as part of the path to store + playbooks for this VNF version. - #. Include generic ansible root directory. Creating full directory - path as an example: + Include generic ansible root directory. Creating full directory + path as an example: .. code-block:: text $ mkdir –p /storage/vfdb/V16.1/ansible -#. Make this directory (VNF ansible root directory) current directory - for next few steps: +#. When manually creating directory structure make this directory (VNF + ansible root directory) current directory for next few steps: .. code-block:: text @@ -770,8 +829,7 @@ Ansible Server. .. code-block:: text tar xvf .. - unzip ... - bunzip .. + unzip ... # Usually, unzip creates the entire directory structure #. Create VNF inventory hosts file with all VMs and OA&M IP addresses, and VM or VNFC names as required for the VNF type, grouped by VM/VNFC type. Add @@ -852,10 +910,10 @@ as part of instantiation. Same Ansible Server Cluster SSH public keys are to be added to repositories to provide each authorized cluster access, to clone and pull updates, to each VNF collection of playbooks, from central repository. -Other non-vendor specific playbook tasks need to be incorporated in overall -post-instantiation configuration playbook. Alternative is for company -developed playbooks to be pushed to repository and executed, after VNF vendor -provided playbooks are run. +Other non-vendor specific playbook tasks, required by customer, need to be +incorporated in overall post-instantiation configuration playbook. Alternative +is for company developed playbooks to be pushed to a repository, distributed +and executed, after VNF vendor provided playbooks are run. **A couple of playbooks used for proof-of-concept testing as examples:** |