diff options
Diffstat (limited to 'docs/Chapter8.rst')
| -rw-r--r-- | docs/Chapter8.rst | 613 |
1 files changed, 576 insertions, 37 deletions
diff --git a/docs/Chapter8.rst b/docs/Chapter8.rst index 4ce9895..19bb026 100644 --- a/docs/Chapter8.rst +++ b/docs/Chapter8.rst @@ -30,73 +30,42 @@ Table A1. Chef JSON File key value description Chef Template example: -“Environment”:{ +.. code-block:: chef + “Environment”:{ "name": "HAR", - "description": "VNF Chef environment for HAR", - "json\_class": "Chef::Environment", - "chef\_type": "environment", - "default\_attributes": { }, - "override\_attributes": { - “Retry\_Time”:”50”, - “MemCache”: “1024”, - “Database\_IP”:”10.10.1.5” - }, - -} - -} - -“Node”: { - + } + } + “Node”: { “name” : “signal.network.com “ - "chef\_type": "node", - "json\_class": "Chef::Node", - "attributes": { - “IPAddress1”: “192.168.1.2”, - “IPAddress2”:”135.16.162.5”, - “MyRole”:”BE” - }, - "override": {}, - "default": {}, - “normal”:{}, - “automatic”:{}, - “chef\_environment” : “\_default” - "run\_list": [ "configure\_signal" ] - }, - “NodeList”:[“node1.vnf\_a.onap.com”, “node2.vnf\_a.onap.com”], - “PushJobFlag”: “True” - “CallbackCapable”:True - “GetOutputFlag” : “False” - -} + } The example JSON file provided by the vendor for each VNF action will be turned into a template by ONAP, that can be updated with instance @@ -1324,6 +1293,576 @@ R-49945: The VNF **MUST** authorize vendor access through a client application A R-20912: The VNF **MUST** support alternative monitoring capabilities when VNFs do not expose data or control traffic or use proprietary and optimized protocols for inter VNF communication. +e. - Ansible Playbook Examples +============================== + +The following sections contain examples of Ansible playbook contents +which follow the guidelines. + +Guidelines for Playbooks to properly integrate with APPC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +NOTE: To support concurrent requests to multiple VNF instances of same +or different type, VNF hosts and other files with VNF specific default +values are kept or created in separate directories. + +Example of an Ansible command (after pwd) to run playbook again +vfdb9904v VNF instance: + +.. code-block:: none + + $ pwd + /storage/vfdb/V16.1/ansible/configure + $ ansible-playbook -i ../inventory/vfdb9904v/hosts site.yml --extra-vars "vnf_instance=vfdb9904v" + +Example of corresponding APPC API Call from ONAP – Ansible Server +Specifications: + +An example POST for requesting execution of configure Playbook: + +.. code-block:: none + + {"Id": "10", "PlaybookName": + "/storage/vfdb/latest/ansible/configure/site.yml", "NodeList": + ["vfdb9904v"], "Timeout": 60, "EnvParameters": {"Retry": 3, "Wait": 5}, + "LocalParameters": {"vfdb9904v": {"T_true": 10, "T_false": 5, + "T_nfo": 5}}} + +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 when + requested. + +- Playbook Name provided in the request (full path in this case) + +- Playbook path (in this example provided as part of playbook name as + full path) or, later in a separate variable, playbook root directory + needs to be part of APPC template. + +Ansible Playbooks will use the VNF instance name (passed using +--extra-vars "vnf\_instance=vfdb9904v") to identify other default values +to run the playbook(s) against the target VNF instance. Same example as +above: + +.. code-block:: none + + $ ansible-playbook -i ../inventory/vfdb9904v/hosts site.yml --extra-vars "vnf_instance=vfdb9904v" + +SSH key info (name/path), used to authenticate with the VNF VMs, is one +of the attributes stored in the Ansible Server inventory hosts file for +the VNF instance and later will be passed down by APPC, in the inventory +hosts file, to the Ansible Server as part of the request. Here hosts +file to run ansible-playbook listed in this example above (IP addresses +were scrubbed): + +.. code-block:: none + + $ more ../inventory/vfdb9904v/hosts + [host] + localhost ansible_connection=local + + [oam] + 1xx.2yy.zzz.109 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.110 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + + [rdb] + 1xx.2yy.zzz.105 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.106 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + +NOTE: APPC requests to run Playbooks/Cookbooks are specific to a VNF, +but could be more limited to one VM or one type of VM by the request +parameters. Actions that may impact a site (LCP), a service, or an +entire platform must be orchestrated by MSO in order to execute requests +via APPC which then invoke VNF level playbooks. Playbooks that impact +more than a single VNF are not the current focus of these guidelines. + +And here the scrubbed default arguments for this VNF instance: + +.. code-block:: none + + vnf_instance=vfdb9904v + + $ more ../vars/vfdb9904v/default_args.yml + vnf_provider_network_network: d69fea03-xxx-yyy-zzz-nnnnnnnnnnnn + vnf_provider_network_subnet: a07f6a3d-xxxx-yyy-zzz-ssssssssssss + vm_config_oam_vnfc_name: vfdb9904vm001oam001 + vm_config_oam_hostname: vfdb9904vm001 + vm_config_oam_provider_ip_address: 1xx.2yy.zzz.109 + … + +IMPORTANT: The APPC and default file attribute name for +vm\_config\_oam\_vnfc\_name, as an example, is derived from vm\_config +array structure (list) in the CSAR package ENV file, with dots replaced +by underscore: + +.. code-block:: none + + vm_config: + + oam: {vnfc_name: {{ vm_config_oam_vnfc_name }}, hostname: {{ + vm_config_oam_hostname }}, provider_ip_address: {{ + vm_config_oam_provider_ip_address } + + }, + + … + +Parameters like VNF names, VNFC names, OA&M IP addresses, after +February, 2018 ONAP release, will be extracted from A&AI by APPC and +then passed down to Ansible Server, as part of APPC request through REST +API. In the meantime, these VNF instance specific required values, will +be stored on VNF instance directory, default arguments file and will be +used as defaults. For parameterized playbooks attribute-value pairs +passed down by APPC to Ansible Server always take precedence over +template or VNF instance specific defaults stored in defaults file(s). + +.. code-block:: none + + $ pwd + /storage/vfdb/latest/ansible + + $ more vars/vfdb9904v/default_args.yml + + vm_config_oam1_vnfc_name: vfdb9904vm001oam001 + vm_config_oam1_hostname: vfdb9904vm001 + vm_config_oam1_provider_ip_address: 1xx.2yy.zzz.109 + + vm_config_oam2_vnfc_name: vfdb9904vm002oam001 + vm_config_oam2_hostname: vfdb9904vm002 + vm_config_oam2_provider_ip_address: 1xx.2yy.zzz.110 + + vm_config_rdb1_vnfc_name: vfdb9904vm003rdb001 + vm_config_rdb1_hostname: vfdb9904vm003 + vm_config_rdb1_provider_ip_address: 1xx.2yy.zzz.105 + + vm_config_rdb2_vnfc_name: vfdb9904vm004rdb001 + vm_config_rdb2_hostname: vfdb9904vm004 + vm_config_rdb2_provider_ip_address: 1xx.2yy.zzz.106 + + vm_config_rdb3_vnfc_name: vfdb9904vm005rdb001 + vm_config_rdb3_hostname: vfdb9904vm005 + vm_config_rdb3_provider_ip_address: 1xx.2yy.zzz.xxx + + vm_config_rdb4_vnfc_name: vfdb9904vm006rdb001 + vm_config_rdb4_hostname: vfdb9904vm006 + vm_config_rdb4_provider_ip_address: 1xx.2yy.zzz.yyy + +One of the first tasks on the Ansible Playbooks is to combine the VNF +type generic template, derived from ENV files in CSAR or other files, +with these default values stored on the Ansible Server, together with +the overriding parameters passed down from APPC, to create the VNF +instance specific set of attribute-value pairs to be used for the run in +YAML format. Here is an excerpt from such a file that should look +somewhat similar to ENV files: + +.. code-block:: none + + $ more tmp/vfdb9904v/all.yml + + deployment_prefix: vfdb9904v + vm_config: + oam1: { vnfc_name: vfdb9904vm001oam001, hostname: vfdb9904vm001, provider_ip_address: 1xx.2yy.zzz.109, private_ip_address: 192.168.10.107 } + oam2: { vnfc_name: vfdb9904vm002oam001, hostname: vfdb9904vm002, provider_ip_address: 1xx.2yy.zzz.110, private_ip_address: 192.168.10.108 } + rdb1: { vnfc_name: vfdb9904vm003rdb001, hostname: vfdb9904vm003, provider_ip_address: 1xx.2yy.zzz.105, private_ip_address: 192.168.10.109 } + rdb2: { vnfc_name: vfdb9904vm004rdb001, hostname: vfdb9904vm004, provider_ip_address: 1xx.2yy.zzz.106, private_ip_address: 192.168.10.110 } + rdb3: { vnfc_name: vfdb9904vm005rdb001, hostname: vfdb9904vm005, provider_ip_address: 1xx.2yy.zzz.xxx, private_ip_address: 192.168.10.111 } + rdb4: { vnfc_name: vfdb9904vm006rdb001, hostname: vfdb9904vm006, provider_ip_address: 1xx.2yy.zzz.yyy, private_ip_address: 192.168.10.112 } + … + timezone: Etc/UTC + … + template_version: '2014-10-16' + stack_name: vfdb9904v + key_name: ONAPkilo-keypair + c3dbtype: OAM + stackName: vfdb9904v + juno_base: true + … + +# logins list contain 'login name', 'login group', 'login password' + +.. code-block:: none + + logins: + - { name: 'm99999', group: 'm99999', password: 'abcdefgha' } + - { name: 'gsuser', group: 'gsuser', password: ' abcdefgha' } + - { name: 'peruser', group: 'peruser', password: ' abcdefgha' } + - { name: 'dbuser', group: 'dbuser', password: ' abcdefgha' } + +NOTE: Arguments passed by APPC to Ansible Server to run a playbook take +precedence over any defaults stored in Ansible Server. + +Ansible Playbooks – Notes On Artifacts Required to Run Playbooks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Inventory hosts file: should be VNF instance specific. + +Default variables: should be VNF instance specific/ + +NOTE: Some playbooks may rely on inventory directory contents to target +the collection of VNFs in the Services Platform supported through +Ansible. + +Playbooks and paths to referenced files: Playbooks shall not use +absolute paths for file include entries (variables or playbooks) or +other types of references. + +For this to work properly when running playbooks, the directory where +the playbook resides shall be the current directory. + +Playbook includes use paths relative to the main playbook directory when +necessary. + +Root directory named ansible - Any files provided with playbooks, +included or referenced by playbooks, shall reside under the ansible +playbooks (root) directory, containing all playbook subdirectories, or +below that ansible root directory, in other subdirectories to support +on-boarding and portability of VNF collection of playbooks and related +artifacts. + +Designing for a shared environment, concurrently running playbooks, +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, and under a directory +for each VNF instance, named after the VNF instance, as follows: + +ansible/inventory/<VNF\_instance\_name>/hosts + +Example of inventory hosts file path, relative to ansible playbooks root +directory (playbooks\_dir): ansible/inventory/vnfx0001v/hosts + +Designing for a shared environment, concurrently running playbooks, +targeting multiple VNF instances – default argument variables for +specific VNF instances: + +Files containing attribute name value pairs (variable name and default +values), referenced/included by playbooks – Files containing VNF +instance specific default values – in a later APPC release, some or all +the default attribute value pairs contained in the defaults file, may be +passed down by APPC, to the Ansible Server, overriding these defaults: + +Following the same approach for inventory hosts files, files +referenced/included by playbooks containing default values, +default\_args.yml, shall be stored under a directory with VNF instance +name on the path. + +Example: + +ansible/vars/<VNF\_instance\_name>/default\_args.yml + +Files containing attribute name value pairs (variable name and default +values), referenced/included by playbooks – created dynamically by +playbooks: + +Following the same approach for inventory hosts files, to avoid +overwrites or collisions of multiple concurrently running VNF instance +requests, files created dynamically by playbooks, based on VNF generic +templates, combined with default values and arguments passed down by +APPC (as part of the request), shall be stored under a directory with +VNF instance name on the path. + +Example: + +tmp/<VNF\_instance\_name>/all.yml + +Files containing site specific (Openstack location non-instance +specific) attribute name value pairs, like NTP server and DNS server’s +IP addresses and other parameters, referenced/included by playbooks, not +VNF specific – Could/should be stored under vars directory, in a +subdirectory named after the string used to identify the site (nyc1, +lax2,…). + +Examples: + +ansible/vars/<Site>/default\_args.yml + +ansible/vars/nyc1/default\_args.yml + +ansible/vars/lax2/default\_args.yml + +\ **Ansible Server Design - Directory Structure** + +To help understanding the contents of this section, here are few basic +definitions: + +**VNF type a.k.a VNF Function Code** - Based on current Services +Platform naming convention, each Virtual Network Function is assigned a +4 character string (example vfdb), they are the first 4 characters on +the VNF instance name, which is 9 characters long. 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 same +software, coming from the same vendor will start with the same 4 +characters, in this example, vfdb. + +VNF type, determined through these 4 characters, is also known as VNF +Function Code and is assigned by inventory team. All Services Platform +VNF Function Codes can be found in inventory database and/or A&AI as +well as Services Platform Network Design Documents. + +NOTE: Current Services Platform naming convention is undergoing changes +to include geographical location to the VNF names. + +Version – As in VNF software version is the release of the software +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 initially will +not support playbook versioning only latest playbook is supported. + +Playbook Function - Is a name associated with a life cycle management +task(s) performed by the playbook(s) stored in this directory. It should +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 corresponding function that executes +the main playbook in this directory. Following Ansible Naming standards +main playbook is usually 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: + +- configure – Contains post-instantiation (bulk) configuration + playbooks, roles,… + +- healthcheck – Contains VNF health check playbook(s), roles,… + +- stop – Contains VNF application stop playbook(s), roles,… + +- start – Contains VNF application start playbook(s), roles,… + +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: + +Ansible Playbooks – Function directory and main playbook: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/<Playbook Function>/site.yml + +Example – Post-instantiation (bulk) configuration –APPC Function - +Configure: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/configure/site.yml + +Example – Health-check –APPC Function - HealthCheck: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/healthcheck/site.yml + +OR (Function directory name does not need to match APPC function name) + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/check/site.yml + +Ansible Directories for other artifacts – VNF inventory hosts file - +Required: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/inventory/<VNF instance name>/hosts + +Ansible Directories for other artifacts – VNF inventory hosts file – +Required: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/vars/<VNF instance name>/default\_args.yml + +NOTE: This requirement is expected to be deprecated in part in the +future, for automated actions, once APPC can pass down all VNF specific +arguments for each action. Requirement remains while manual actions are +to be supported. Other automated inventory management mechanisms may be +considered in the future, Ansible supports many automated inventory +management mechanisms/tools/solutions. + +Ansible Directories for other artifacts – VNF (special) groups – +Optional: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/groups/<VNF instance name>/common\_groups.yml + +NOTE: Default groups will be created based on VNFC type, 3 characters, +on VNFC name. Example: “oam”, “rdb”, “dbs”, “man”, “iox”, “app”,… + +Ansible Directories for other artifacts – VNF (special) other files – +Optional – Example – License file: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/<Other directory(s)> + +CAUTION: On referenced files used/required by playbooks. + +- To avoid missing files, during on-boarding or uploading of Ansible + Playbooks and related artifacts, all permanent files (not generated + by playbooks as part of execution), required to run any playbook, + shall reside under the ansible root directory or below on other + subdirectories. + +- Any references to files, on includes or other playbook entries, shall + use relative paths. + +- This is the ansible (root directory) directory referenced on this + note: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/ + +There will be a soft link to the latest set of Ansible Playbooks for +each VNF type and this is the default set of playbooks that are executed +unless a different release is specified in APPC request. + +VNF type directories use A&AI inventory VNF function code. Ansible +Playbooks will be stored on a Cinder Volume mounted on the Ansible +Servers as /storage. 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, APPC API in the Ansible Server side needs +to be configured to run playbooks from directory, not MySQL database. + +Ansible Server HTTP will be configured to support APPC REST API requests +to run playbooks as needed, against specific VNF instances, or specific +VM(s) as specified in the request. + +ONAP APPC REST API to Ansible Server is documented separately and can be +found under ONAP (onap.org). + +\ **Ansible Server – On-boarding Ansible Playbooks ** + +Once playbooks are developed following the guidelines listed in prior +section(s), playbooks need to be on-boarded onto Ansible Server(s). In +the future, they’ll be on-boarded and distributed through ONAP, at least +that is the proposed plan, but for now they need to be uploaded +manually. + +These are the basic steps to on-board playbooks manually onto the +Ansible Server. + +1. Upload CSAR, zip, or tar file containing VNF playbooks and related + artifacts. + +2. Create full directory (using –p option below) to store Ansible + Playbooks and other artifacts under /storage file system. + + a. Includes VNF type using VNF function code 4 characters under + /storage. + + b. Includes VNF “Version” directory as part of the path to store + playbooks for this VNF version. + + c. Include generic ansible root directory. Creating full directory + path as an example: + +.. code-block:: none + + $ mkdir –p /storage/vfdb/V16.1/ansible**/** + +3. Make this directory (VNF ansible root directory) current directory + for next few steps: + +.. code-block:: none + + cd /storage/vfdb/V16.1/ansible/ + +4. Extract Ansible Playbooks and other Ansible artifacts associated with + the playbooks onto the ansible directory. Command depends on the type + of file uploaded, examples would be: + +.. code-block:: none + + tar xvf .. + unzip … + bunzip .. + +5. Create directory for VNF (VMs) inventory hosts file with all VMs and + OA&M IP addresses for all VNF instances with known OA&M IP addresses + for respective VMs, example: + +.. code-block:: none + + $ mkdir –p inventory/vfdb9904v + + $ touch inventory/vfdb9904v/hosts + + $ cat inventory/vfdb9904v/hosts + + [host] + localhost ansible\_connection=local + + [oam] + 1xx.2yy.zzz.109 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.110 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + + [rdb] + 1xx.2yy.zzz.105 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.106 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + +6. Create directory to hold default arguments for each VNF instance, + example: + +.. code-block:: none + + $ mkdir –p vars/vfdb9904v + $ touch vars/vfdb9904v/default\_args.yml + $ cat vars/vfdb9904v/default\_args.yml + vm\_config\_oam1\_vnfc\_name: vfdb9904vm001oam001 + vm\_config\_oam1\_hostname: vfdb9904vm001 + vm\_config\_oam1\_provider\_ip\_address: 1xx.2yy.zzz.109 + + vm\_config\_oam2\_vnfc\_name: vfdb9904vm002oam001 + vm\_config\_oam2\_hostname: vfdb9904vm002 + vm\_config\_oam2\_provider\_ip\_address: 1xx.2yy.zzz.110 + + vm\_config\_rdb1\_vnfc\_name: vfdb9904vm003rdb001 + vm\_config\_rdb1\_hostname: vfdb9904vm003 + vm\_config\_rdb1\_provider\_ip\_address: 1xx.2yy.zzz.105 + + vm\_config\_rdb2\_vnfc\_name: vfdb9904vm004rdb001 + vm\_config\_rdb2\_hostname: vfdb9904vm004 + vm\_config\_rdb2\_provider\_ip\_address: 1xx.2yy.zzz.106 + + vm\_config\_rdb3\_vnfc\_name: vfdb9904vm005rdb001 + vm\_config\_rdb3\_hostname: vfdb9904vm005 + vm\_config\_rdb3\_provider\_ip\_address: 1xx.2yy.zzz.xxx + + vm\_config\_rdb4\_vnfc\_name: vfdb9904vm006rdb001 + vm\_config\_rdb4\_hostname: vfdb9904vm006 + vm\_config\_rdb4\_provider\_ip\_address: 1xx.2yy.zzz.yyy + +NOTE: Please note names in this file shall use underscore “\_” not dots +“.” or dashes “-“. + +7. Perform some basic playbook validation running with “--check” option, + running dummy playbooks or other. + +8. Upload any SSH keys referenced on hosts file to appropriate + directory. + +NOTE: HOT templates used by heat to instantiate VNF configured by these +playbooks shall include the same SSH key to be installed as part of +instantiation. + +Other non-vendor specific playbook tasks need to be incorporated on +overall post-instantiation configuration playbooks or company Playbooks +need to be uploaded and executed after VNF vendor provided or internally +developed playbooks for the VNF. + .. [1] The “name” field is a mandatory field in a valid Chef Node Object |