From fd1353319388ea61a0a0ee7b764b2c7a25eb63b8 Mon Sep 17 00:00:00 2001 From: Hector Anapan Date: Wed, 18 Oct 2017 20:50:05 -0400 Subject: Updating APPC Deployment Titles Updating the titles in the APPC Deployment docs for title consistency and legiblity purposes. Change-Id: I19b3b89ea9458c572778086becaa8a3d691a4b57 Signed-off-by: Hector Anapan Issue-Id: [APPC-303] --- docs/APPC Ansible Adapter/APPC Ansible Adapter.rst | 412 +++++++++++++++++++ docs/APPC Ansible Adapter/images/image0.png | Bin 0 -> 30810 bytes docs/APPC Ansible Adapter/images/image1.png | Bin 0 -> 23386 bytes docs/APPC Ansible Adapter/images/image2.png | Bin 0 -> 54993 bytes docs/APPC Ansible Adapter/images/image3.png | Bin 0 -> 30311 bytes docs/APPC Ansible Adapter/images/image4.png | Bin 0 -> 14624 bytes docs/APPC Ansible Adapter/images/image5.png | Bin 0 -> 9264 bytes docs/APPC Ansible Adapter/images/image6.png | Bin 0 -> 10210 bytes docs/APPC Chef Adapter/APPC Chef Adapter.rst | 139 +++++++ docs/APPC Chef Adapter/images/image0.png | Bin 0 -> 17702 bytes docs/APPC Chef Adapter/images/image1.png | Bin 0 -> 10437 bytes docs/APPC Platform Logic/APPC Platform Logic.rst | 114 ++++++ docs/APPC Properties/APPC Properties.rst | 6 +- .../APPC Testing of a Local ONAP Component.rst | 441 +++++++++++++++++++++ .../images/image0.png | Bin 0 -> 26412 bytes .../images/image1.png | Bin 0 -> 47064 bytes .../images/image10.png | Bin 0 -> 50127 bytes .../images/image11.png | Bin 0 -> 79700 bytes .../images/image12.png | Bin 0 -> 155225 bytes .../images/image13.png | Bin 0 -> 120668 bytes .../images/image14.png | Bin 0 -> 41139 bytes .../images/image15.png | Bin 0 -> 59006 bytes .../images/image16.png | Bin 0 -> 106460 bytes .../images/image17.png | Bin 0 -> 149482 bytes .../images/image18.png | Bin 0 -> 70160 bytes .../images/image2.png | Bin 0 -> 31954 bytes .../images/image3.png | Bin 0 -> 90090 bytes .../images/image4.png | Bin 0 -> 109628 bytes .../images/image5.png | Bin 0 -> 81148 bytes .../images/image6.png | Bin 0 -> 81472 bytes .../images/image7.png | Bin 0 -> 56681 bytes .../images/image8.png | Bin 0 -> 8492 bytes .../images/image9.png | Bin 0 -> 156003 bytes docs/Ansible Adapter/Ansible Adapter.rst | 412 ------------------- docs/Ansible Adapter/images/image0.png | Bin 30810 -> 0 bytes docs/Ansible Adapter/images/image1.png | Bin 23386 -> 0 bytes docs/Ansible Adapter/images/image2.png | Bin 54993 -> 0 bytes docs/Ansible Adapter/images/image3.png | Bin 30311 -> 0 bytes docs/Ansible Adapter/images/image4.png | Bin 14624 -> 0 bytes docs/Ansible Adapter/images/image5.png | Bin 9264 -> 0 bytes docs/Ansible Adapter/images/image6.png | Bin 10210 -> 0 bytes docs/Chef Adapter/Chef Adapter.rst | 139 ------- docs/Chef Adapter/images/image0.png | Bin 17702 -> 0 bytes docs/Chef Adapter/images/image1.png | Bin 10437 -> 0 bytes docs/Platform Logic/Platform Logic.rst | 114 ------ .../Testing an ONAP Component Locally.rst | 441 --------------------- .../images/image0.png | Bin 26412 -> 0 bytes .../images/image1.png | Bin 47064 -> 0 bytes .../images/image10.png | Bin 50127 -> 0 bytes .../images/image11.png | Bin 79700 -> 0 bytes .../images/image12.png | Bin 155225 -> 0 bytes .../images/image13.png | Bin 120668 -> 0 bytes .../images/image14.png | Bin 41139 -> 0 bytes .../images/image15.png | Bin 59006 -> 0 bytes .../images/image16.png | Bin 106460 -> 0 bytes .../images/image17.png | Bin 149482 -> 0 bytes .../images/image18.png | Bin 70160 -> 0 bytes .../images/image2.png | Bin 31954 -> 0 bytes .../images/image3.png | Bin 90090 -> 0 bytes .../images/image4.png | Bin 109628 -> 0 bytes .../images/image5.png | Bin 81148 -> 0 bytes .../images/image6.png | Bin 81472 -> 0 bytes .../images/image7.png | Bin 56681 -> 0 bytes .../images/image8.png | Bin 8492 -> 0 bytes .../images/image9.png | Bin 156003 -> 0 bytes docs/index.rst | 12 +- 66 files changed, 1115 insertions(+), 1115 deletions(-) create mode 100644 docs/APPC Ansible Adapter/APPC Ansible Adapter.rst create mode 100644 docs/APPC Ansible Adapter/images/image0.png create mode 100644 docs/APPC Ansible Adapter/images/image1.png create mode 100644 docs/APPC Ansible Adapter/images/image2.png create mode 100644 docs/APPC Ansible Adapter/images/image3.png create mode 100644 docs/APPC Ansible Adapter/images/image4.png create mode 100644 docs/APPC Ansible Adapter/images/image5.png create mode 100644 docs/APPC Ansible Adapter/images/image6.png create mode 100644 docs/APPC Chef Adapter/APPC Chef Adapter.rst create mode 100644 docs/APPC Chef Adapter/images/image0.png create mode 100644 docs/APPC Chef Adapter/images/image1.png create mode 100644 docs/APPC Platform Logic/APPC Platform Logic.rst create mode 100644 docs/APPC Testing of a Local ONAP Component/APPC Testing of a Local ONAP Component.rst create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image0.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image1.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image10.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image11.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image12.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image13.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image14.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image15.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image16.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image17.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image18.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image2.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image3.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image4.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image5.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image6.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image7.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image8.png create mode 100644 docs/APPC Testing of a Local ONAP Component/images/image9.png delete mode 100644 docs/Ansible Adapter/Ansible Adapter.rst delete mode 100644 docs/Ansible Adapter/images/image0.png delete mode 100644 docs/Ansible Adapter/images/image1.png delete mode 100644 docs/Ansible Adapter/images/image2.png delete mode 100644 docs/Ansible Adapter/images/image3.png delete mode 100644 docs/Ansible Adapter/images/image4.png delete mode 100644 docs/Ansible Adapter/images/image5.png delete mode 100644 docs/Ansible Adapter/images/image6.png delete mode 100644 docs/Chef Adapter/Chef Adapter.rst delete mode 100644 docs/Chef Adapter/images/image0.png delete mode 100644 docs/Chef Adapter/images/image1.png delete mode 100644 docs/Platform Logic/Platform Logic.rst delete mode 100644 docs/Testing an ONAP Component Locally/Testing an ONAP Component Locally.rst delete mode 100644 docs/Testing an ONAP Component Locally/images/image0.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image1.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image10.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image11.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image12.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image13.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image14.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image15.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image16.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image17.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image18.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image2.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image3.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image4.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image5.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image6.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image7.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image8.png delete mode 100644 docs/Testing an ONAP Component Locally/images/image9.png diff --git a/docs/APPC Ansible Adapter/APPC Ansible Adapter.rst b/docs/APPC Ansible Adapter/APPC Ansible Adapter.rst new file mode 100644 index 0000000..6949cd8 --- /dev/null +++ b/docs/APPC Ansible Adapter/APPC Ansible Adapter.rst @@ -0,0 +1,412 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + +==================== +APPC Ansible Adapter +==================== + +This wiki provides documentation regarding the design, capabilities and +usage of the Ansible Extension for APP-C. Ansible_ is a an open-source +VNF management framework that allows provide an almost cli like set of +tools in a structured form. It is agentless in that the target VNF need +not have any additional software other than: + +a) SSH server +b) Python >= 2.7 +c) Any necessary software that is specific to the VNF to run its functions. + +Any action (e.g configure, restart, health check etc) can be +executed on the VNF by constructing a **playbook (or set of playbooks)** +that is executed by an Ansible agent on the VNF via SSH. + +The Ansible Extension for APP-C allows management of VNFs that support Ansible +through the following three additions : + + - **An APP-C/Ansible Server interface:** Ansible libraries are written in python and hence cannot be executed natively from within the APP-C Karaf container. Instead, the design calls for an **Ansible Server** that can execute the Ansible playbooks and exposes a **REST** interface that is compliant with requirements of APP-C. These requirements are documented as the Server API Interface that any compliant Ansible Server must support. Exact implementation of the Ansible Server is left open and does not affect APP-C operations as long as the server follows the interface. For purposes of evaluation, a reference web server that implements this APP-C/Ansible Server interface has been developed and the code is available from the App-C ONAP repository under *appc-adapters/appc-ansible-adapter/appc-ansible-example-server*. + + - **An APP-C Ansible adapter:** The ansible adapter is an OSGI bundle in the APP-C Karaf container that interacts with the Ansible Server . It is essentially a set of REST calls that performs two actions, submit request for a playbook to be executed, and if required get the results of the playbook after execution (if in synchronous mode). + + - **Ansible Directed Graph (DG):** The Ansible Directed graph is generic DG that can be used to invoke any playbook via Ansible (and hence any APP-C action, since in Ansible, VNF actions map to playbooks) corresponding to an LCM action. + +The architecture design for supporting Ansible is outlined in the diagram below : + +|image0| + +The workflow envisioned when Application Controller receives an event is +as follows : + +1) Application Controller receives event from the Event Bus for an LCM action. +2) The appropriate LCM API invokes the Dispatcher which performs the relevant lookups for A&AI and Workflow (DG information). +3) The dispatcher calls the DG relevant to the LCM action (for the VNF). +4) The DG conducts any processing of data (e.g retrieving additional information, filling templates etc) , prepares the necessary DG context variables outlined in Table 1 and then invokes the Ansible DG. +5) Ansible DG leverages the Ansible Adapter to interact with the Ansible Server. +6) Ansible Server invokes the appropriate playbook which in turn interacts with the VNF and then returns the playbook results. +7) Ansible Server returns results. +8) Ansible DG provides these results back to calling DG. + +A ladder diagram of the work flow is pasted below : + +|image1| + +Details of each of these three (DG, Adapter and Ansible Server) are listed below : + +1. **Ansible Directed Graph (DG):** The Ansible Directed graph is the most common way an App-C developer is expected to leverage Ansible functionality. The Ansible DG is a general purpose graph that can be used to invoke and retrieve results from any playbook on an ONAP-compliant Ansible Server. The Ansible Graph,when called, expects a certain set of inputs to be provided as input and when upon completion provides results from the execution of the Ansible playbook. The Ansible +DG can be invoked using the following (current) naming: + ++------------+----------------------+ +| Field | Value | ++============+======================+ +| module | APPC | ++------------+----------------------+ +| rpc | ansible-adapter-1.0 | ++------------+----------------------+ +| version | 2.0.1 | ++------------+----------------------+ + +The inputs that the Ansible DG expects in DG context memory are listed below: + +Table 1: Input Parameters to the Ansible Directed Graph + ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| Variable Name | Description | Type | Comments | ++================+=================================================================+=======================+==========================================================================+ +| User | Username to logon to Ansible Server | Mandatory | Should be provided by APPC. | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| Password | Password to logon to Ansible Server | Mandatory | Should be provided by APPC. | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| AgentUrl | The complete URL of the Ansible Server to post the request for | Mandatory | Should be provided by APPC. | +| | execution and retrieve results (if in synchronous mode) | | | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| PlaybookName | Name/identifier of playbook to run | Mandatory | To be provided in the template. | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| Action | The type of VNF action being requested | Optional | Provided either by APPC or Template. | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| EnvParameters | A JSON dictionary (stringified) listing the parameters to be | Optional | Structure of the EnvParameters dictionary to be supplied in template. | +| | passed to the Ansible playbook | | Values to be filled in by App-C based on values from payload in run-time | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| FileParameters | A JSON dictionary (stringified) listing file names and files to | Optional | Structure of the FileParameters dictionary to be supplied in template. | +| | be created for Ansible playbook | | Values to be filled in by App-C based on values from payload in run-time | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| Timeout | Time Ansible Server should wait before terminating playbook | Optional | To be provided in the template. | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ +| NodeList | List of FQDNs/IP Addresses of VNF that the Ansible playbook | Optional | To be provided to App-C during Runtime. | +| | should be executed on. | (if not supplied, | | +| | | will run on server) | | ++----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ + + The 'template' referred in the above table must be a JSON file as documented in the VNF vendor requirements and must contain the key-value pairs listed above (that are expected to be in the template). An LCM API Directed graph should fill in necessary parameters in the template, and then put the key-value pairs from the template as listed above in DG context memory before calling the Ansible DG. + +Upon completion the Ansible DG sets the following variables in DG context memory + +Table 2: Output Variables set by Ansible DG Variable + ++-----------------------+--------------------------------------------------------------------------+ +| Type | Comments | ++=======================+==========================================================================+ +| output.status.code | Result of the request: 400 if SUCCESS , 200 if FAILURE. | +| | | +| | The ansible playbook may have multiple sub-tasks, playbooks etc and may | +| | run on multiple VMs of a host. The request is considered to fail if even | +| | one of the tasks is incomplete. | ++-----------------------+--------------------------------------------------------------------------+ +| output.status.message | If playbook finished, set to FINISH, if playbook terminated, set to | +| | TERMINATED. If abnormal error, reported in message | ++-----------------------+--------------------------------------------------------------------------+ +| output.status.results | A JSON dictionary with results corresponding to output provided by the | +| | Ansible playbook request. This is optional (may not be present if | +| | playbook was terminated). The results, if present, will be in the form | +| | of a dictionary that follows the format presented in the Ansible Server | +| | API Documentation. The document also contains examples of output. | ++-----------------------+--------------------------------------------------------------------------+ + + *Note : The Ansible Server supports a Callback Url functionality, but it is currently not invoked by App-C Ansible Adapter or Directed Graph. If added, it is easy to change the Adapter and Ansible DG to support this.* + +2. **APP-C Ansible Adapter:** The App-C Ansible Adapter is an OSGI bundle which essentially makes REST calls to the Ansible Server. It exposes three methods that can be invoked by the Service Logic Interpreter (SLI). + + a. *void reqExec(Map params, SvcLogicContext ctx) throws SvcLogicException*: A method to invoke the test. + + b. *void reqExecResult(Map params, SvcLogicContext ctx) throws SvcLogicException*: A method to request results of a test. + + c. *void reqExecLog(Map params, SvcLogicContext ctx) throws SvcLogicException* : A method to retreive the logs from a request (not used in the Ansible DG currently). + + Currently, the Ansible DG uses only the first two (reqExec and reqExecResult) since only these two are needed to request execution of a playbook and retrieval of results. The reqExecLog is for diagnostic purposes. + + In order to communicate with the Ansible Server, it is currently assumed that: + + a. Credentials comprise of a username and password. + + b. Communication is over https + + The Ansible Adapter has three configurable parameters related to SSL certificate of the Ansible Server, which can be set from the properties file: + + a. org.openecomp.appc.adapter.ansible.clientType. If set to "TRUST\_ALL", will accept all SSL certificates from any Ansible Server. If set to "TRUST\_CERT", will accept SSL from only those Ansible Servers whose certificate is in the trustStore keystore file. These two options can be used for development environment. Default option is to trust only well known server certificates (use in Production). + + b. org.openecomp.appc.adapter.ansible.trustStore used to point to the keystore file + + c. org.openecomp.appc.adapter.ansible.trustStorePasswd used to set password for keystore file + +3. **Reference Ansible Server Implementation of APPC / Ansible Interface (for testing purposes only)** + + a. Overview + + |image2| + + b. Inventory file + + The Prototype Ansible Server requires that all credentials and IP Addresses for the VNF being tested either already be present in the Server’s Database or be loaded before any playbooks are invoked. Supported credentials are user-name/password and public-key authentication. + + All VNF credentials stored in a unique file (or in a SQL database depending on the ansible server runtime configuration): + + .. code:: bash + + [host] + localhost ansible\_connection=local + ... + [hostgroup1] + hostname11 ansible\_connection=ssh ansible\_ssh\_user=loginid11 ansible\_ssh\_pass=passwd11 + hostname12 ansible\_connection=ssh ansible\_ssh\_user=loginid12 ansible\_ssh\_private\_key\_file=kefile12 + ... + [hostgroup2] + hostname21 ansible\_connection=ssh ansible\_ssh\_user=loginid21 ansible\_ssh\_private\_key\_file=keyfile21 + ... + [hostgroup3] + ... + + c. Playbooks + + Playbooks can either be provided as stand alone text files or gzipped tar file (playbooks with roles sub-directories) either stored in a local file or in an SQL database. + + Naming convention: anything\_LCM@M.mn.{yml,tar.gz} where version number M is a digit and mn are subversion number digits. + + Playbooks should be written such that they can run from the command line: "ansible-playbook -i inventoryfile –extra-vars optionalvariables playbookname" That means the playbook should not contain any VM credentials information, they are expected to be provided through the inventory file passed at run time. + + a. Stand-alone playbooks + + |image3| + + b. Playbooks in gzipped tarfiles + + |image4| + + d. Installation + + a. Python + + sudo apt-get install python2.7 + sudo apt-get install python-pip + pip install PyMySQL + pip install requests + + b. Ansible + + sudo apt-get install software-properties-common + sudo apt-add-repository ppa:ansible/ansible + sudo apt-get update + sudo apt-get install ansible + + c. SQL database + + a. Installing MySQL + + sudo apt-get install mysql-server + + Set root passwd during installation (i.e. password\_4\_mysql\_user\_id) + + sudo service mysql restart + + b. Setting up mysql + + mysql -u [username]-p + + mysql -uroot -p + + Create user (i.e. id=mysql\_user\_id psswd=password\_4\_mysql\_user\_id) + + CREATE USER 'appc'@'%' IDENTIFIED BY 'password\_4\_mysql\_user\_id'; + + GRANT ALL PRIVILEGES ON *.* TO 'mysql\_user\_id'@'%'; + + SET PASSWORD FOR 'mysql\_user\_id'@'%'=PASSWORD('password\_4\_mysql\_user\_id'); + + c. Creating schema + + CREATE SCHEMA ansible; + + SHOW DATABASES; + + USE ansible; + + CREATE TABLE playbook (name VARCHAR(45) NOT NULL, value BLOB, type VARCHAR(60), version VARCHAR(60), PRIMARY KEY (name)); + + SHOW TABLES; + + CREATE TABLE inventory (hostname VARCHAR(45) NOT NULL, hostgroup VARCHAR(45), credentials VARCHAR(500), PRIMARY KEY (hostname)); + + SHOW COLUMNS FROM playbook; + + SHOW COLUMNS FROM inventory; + + GRANT ALL PRIVILEGES ON *.* TO 'mysql\_user\_id'@'%' IDENTIFIED BY 'password\_4\_mysql\_user\_id' WITH GRANT OPTION; + + GRANT ALL PRIVILEGES ON *.* TO 'ansible'@'%' IDENTIFIED BY 'ansible\_agent' WITH GRANT OPTION; + + FLUSH PRIVILEGES; + + + + d. Loading playbooks and inventory data in SQL database + + Place inventory file and playbooks to be loaded in one directory, set LoadAnsibleMySql variables: + + SQL credentials: + + host="localhost" # your host, usually localhost + user="mysql\_user\_id" # your username + passwd="password\_4\_mysql\_user\_id" # your password + db="ansible" # name of the database + + + Path of playbook location: + + playbook\_path = "something/something/" + + + Full name of inventory file: + + inventory = "something/something/Ansible\_inventory" + + These variables are located right after main: + + |image5| + + Run loader: python LoadAnsibleMySql.py + + e. Execution + + Ansible server is executed through RestServer.py. Its configuration file consists of the following: + + .. code:: bash + + # Host definition + ip: 0.0.0.0 + port: 8000 + + # Security (controls use of TLS encrypton and RestServer authentication) + tls: no + auth: no + + # TLS certificates (must be built on application host) + priv: provide\_privated\_key.pem + pub: provide\_public\_key.pem + + # RestServer authentication + id: provide\_RestServer\_id + psswd: provide\_password\_4\_RestServer\_id + + # Mysql + host: localhost + user: mysql\_user\_id + passwd: password\_4\_mysql\_user\_id + db: ansible + + #Playbooks + from\_files: yes + ansible\_path: /home/ubuntu/RestServerOpenSource + ansible\_inv: Ansible\_inventory + ansible\_temp: PlaybooksTemp + timeout\_seconds: 60 + + # Blocking on GetResults + getresults\_block: yes + +Execution and testing steps: + + 1. **Start RestServer**: *python RestServer.py* + + Note: RSA key fingerprint needs to be loaded manually in server for each VM defined in inventory file that requires ssh authentication. This can be done by testing ssh credentials to each target VM and accepting RSA key fingerprint: + + .. code:: bash + + ssh -i key \|VMaddress\| + RSA key fingerprint is \|something.\| + Are you sure you want to continue connecting (yes/no)? yes + + + 2. **Try curl commands** (case no secured REST: HTTP & no authentication) + + Request to execute playbook: + + .. code:: bash + + curl -H "Content-type: application/json" -X POST -d '{"Id": "10", "PlaybookName": "ansible\_sleep", "NodeList": ["host"], "Timeout": "60", "EnvParameters": {"Sleep": "10"}}'http://0.0.0.0:8000/Dispatch + + Response: + + .. code:: bash + + {"ExpectedDuration": "60sec", "StatusMessage": "PENDING", "StatusCode": 100} + + Get results (blocked until test finished): + + .. code:: bash + + curl -H "Content-type: application/json" -X GET "http://0.0.0.0:8000/Dispatch/?Id=10&Type=GetResult" + + Response: + + .. code:: bash + + {"Results": {"localhost": {"GroupName": "host", "StatusMessage": "SUCCESS", "StatusCode": 200}}, "PlaybookName":"ansible\_sleep", "Version": "0.00", "Duration": "11.261794", "StatusMessage": "FINISHED", "StatusCode": 200} + + Delete playbook execution information + + .. code:: bash + + curl -H "Content-type: application/json" -X DELETE http://0.0.0.0:8000/Dispatch/?Id=10 + + Response: + + .. code:: bash + + {"StatusMessage": "PLAYBOOK EXECUTION RECORDS DELETED", "StatusCode": 200} + +Playbook execution done through system call + + .. code:: bash + + ansible-playbook --v -extra-vars ‘playbookvars’ -i inventoryfile playbook.yml + + - Inventory file created at run time, playbook loaded from mysql, both placed in the temporary directory destroyed at end of test (Playbook archive is unpacked in the temporary directory) + +All tested playbooks written such that the ansible ‘play recap’ log indicates whether or not the playbook tasks succeeded (multiple tasks in a standalone playbook or playbooks with roles directory structure) + +Sample ansible ‘play recap’: + +|image6| + + + +.. _Ansible: https://www.ansible.com/ + +.. |image0| image:: images/image0.png +.. |image1| image:: images/image1.png +.. |image2| image:: images/image2.png +.. |image3| image:: images/image3.png +.. |image4| image:: images/image4.png +.. |image5| image:: images/image5.png +.. |image6| image:: images/image6.png diff --git a/docs/APPC Ansible Adapter/images/image0.png b/docs/APPC Ansible Adapter/images/image0.png new file mode 100644 index 0000000..647e5bb Binary files /dev/null and b/docs/APPC Ansible Adapter/images/image0.png differ diff --git a/docs/APPC Ansible Adapter/images/image1.png b/docs/APPC Ansible Adapter/images/image1.png new file mode 100644 index 0000000..ff0a4b4 Binary files /dev/null and b/docs/APPC Ansible Adapter/images/image1.png differ diff --git a/docs/APPC Ansible Adapter/images/image2.png b/docs/APPC Ansible Adapter/images/image2.png new file mode 100644 index 0000000..c58653c Binary files /dev/null and b/docs/APPC Ansible Adapter/images/image2.png differ diff --git a/docs/APPC Ansible Adapter/images/image3.png b/docs/APPC Ansible Adapter/images/image3.png new file mode 100644 index 0000000..be6f7b7 Binary files /dev/null and b/docs/APPC Ansible Adapter/images/image3.png differ diff --git a/docs/APPC Ansible Adapter/images/image4.png b/docs/APPC Ansible Adapter/images/image4.png new file mode 100644 index 0000000..78ea1d5 Binary files /dev/null and b/docs/APPC Ansible Adapter/images/image4.png differ diff --git a/docs/APPC Ansible Adapter/images/image5.png b/docs/APPC Ansible Adapter/images/image5.png new file mode 100644 index 0000000..68d5371 Binary files /dev/null and b/docs/APPC Ansible Adapter/images/image5.png differ diff --git a/docs/APPC Ansible Adapter/images/image6.png b/docs/APPC Ansible Adapter/images/image6.png new file mode 100644 index 0000000..f3fc6e0 Binary files /dev/null and b/docs/APPC Ansible Adapter/images/image6.png differ diff --git a/docs/APPC Chef Adapter/APPC Chef Adapter.rst b/docs/APPC Chef Adapter/APPC Chef Adapter.rst new file mode 100644 index 0000000..209abe7 --- /dev/null +++ b/docs/APPC Chef Adapter/APPC Chef Adapter.rst @@ -0,0 +1,139 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + +================= +APPC Chef Adapter +================= + +This wiki provides documentation regarding the design, capabilities and usage of the Chef Extension for APPC. + +The Chef Extension for APPC allows management of VNFs that support Chef through the following two additions: + +1. An APPC Chef Adapter +2. Chef Directed Graph (DG) + +Details of each of these two aspects are listed below: + +1. **Chef Directed Graph (DG)**: + ++------------+--------+ +| Field | Value | ++============+========+ +| module | APPC | ++------------+--------+ +| rpc | chef | ++------------+--------+ +| version | 3.0.0 | ++------------+--------+ + +The inputs that the Chef DG expects are listed below: + +Table 1: Input Parameters to the Chef Directed Graph + ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| Variable Name | Description | Type | Comments | ++=====================+===========================================================+============+===========================================+ +| chef-server-address | The FQDN of the chef server | Mandatory | Should be provided by APPC. | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| chef-organization | The chef organization name | Mandatory | Should be provided by APPC. | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| chef-username | The username of the chef organization | Mandatory | Should be provided by APPC. | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| Environment | A JSON dictionary representing a Chef Environmentobject. | Optional | To be provided in template by VNF owner. | +| | If the VNF action requires loading or modifying Chef | | | +| | environment attributes associated with the VNF, all the | | | +| | relevant information must be provided in this JSON | | | +| | dictionary in a structure that conforms to a Chef | | | +| | Environment Object. | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| Node | A JSON dictionary representing a Chef Node Object. The | Mandatory | To be provided in template by VNF owner. | +| | Node JSON dictionary must include the run list to be | | | +| | triggered for the desired VNF action by the push job. | | | +| | It should also include any attributes that need to be | | | +| | configured on the Node Object as part of the VNF action. | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| NodeList | Array of FQDNs that correspond to the endpoints (VMs) of | Mandatory | To be provided in template. | +| | a VNF registered with the Chef Server that need to | | | +| | trigger a chef-client run as part of the desired | | | +| | VNF action. | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| CallbackCapable | This field indicates if the chef-client run invoked by | Optional | To be provided in template by VNF owner. | +| | push job corresponding to the VNF action is capable of | | | +| | posting results on a callback URL. | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| RequestId | A unique string associated with the original request | Optional | To be provided by APPC. | +| | by ONAP. This key-value pair will be provided by ONAP in | | | +| | the environment of the push job request and must be | | | +| | returned as part of the POST message. | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| CallbackUrl | Currently not used. | Optional | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| retryTimes | The retry times to query the result of chef push job. | Mandatory | To be provided in template by VNF owner. | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| retryInterval | The estimate duration to finish the push job. Measure | Mandatory | To be provided in template by VNF owner. | +| | by milliseconds. | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| GetOutputFlag | Flag which indicates whether ONAP should retrieve output | Mandatory | To be provided in template by VNF owner. | +| | generated in a chef-client run from Node object | | | +| | attribute node[‘PushJobOutput’] for this VNF action | | | +| | (e.g in Audit). | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ +| PushJobFlag | Flag which indicates whether ONAP should trigger | Mandatory | To be provided in template by VNF owner. | +| | the push job. | | | ++---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ + + +Table 2: Output Variables set by chef DG + ++-----------------------+-----------------------------------------------------------------+ +| Variable Name | Description | ++=======================+=================================================================+ +| output.status.code | Result of the request : 400 if SUCCESS , 200 if FAILURE. | ++-----------------------+-----------------------------------------------------------------+ +| output.status.message | If Cookbook finished, set to corresponding message. | +| | If abnormal error, reported in message. | ++-----------------------+-----------------------------------------------------------------+ +| output.status.results | A JSON dictionary with results corresponding to PushJobOutput. | ++-----------------------+-----------------------------------------------------------------+ + + +Example: + +|image0| + + +2. **APPC Chef Adapter**: + +a. Environment set: + + - To connect to the chef server, APPC should load the chef server credentials. + + - The Chef server uses role-based access control to restrict access to objects—nodes, environments, roles, data bags, cookbooks, and so on. So we need load the user's private key to authenticate the permission. + +APPC needs to pre-load the SSL certificate and user private key. + +The file structure is shown below: + +|image1| + +*chefServerSSL.jks* file saves all the SSL certificates of chef server. In the chef server, please check the chef server setting file at */etc/opscode/chef-server.rb*. The *chef-server.rb* declares where is the SSL certificate. Find the SSL crt file and use keytool to import certificate to the key store. The password of the *chefServerSSL.jks* is "*adminadmin*" + +The user private key file should be saved under */opt/appc/bvc/chef/{{CHEF SERVER FQDN}}/{{ORGANIZATION NAME}}* director and the file name should be *{{username}}.pem*. Please make sure this user have enough permission on the chef server. + +.. |image0| image:: images/image0.png +.. |image1| image:: images/image1.png diff --git a/docs/APPC Chef Adapter/images/image0.png b/docs/APPC Chef Adapter/images/image0.png new file mode 100644 index 0000000..9fd7480 Binary files /dev/null and b/docs/APPC Chef Adapter/images/image0.png differ diff --git a/docs/APPC Chef Adapter/images/image1.png b/docs/APPC Chef Adapter/images/image1.png new file mode 100644 index 0000000..64cca13 Binary files /dev/null and b/docs/APPC Chef Adapter/images/image1.png differ diff --git a/docs/APPC Platform Logic/APPC Platform Logic.rst b/docs/APPC Platform Logic/APPC Platform Logic.rst new file mode 100644 index 0000000..c6b5d67 --- /dev/null +++ b/docs/APPC Platform Logic/APPC Platform Logic.rst @@ -0,0 +1,114 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + +=================== +APPC Platform Logic +=================== + +Platform Logic is a SDNC-based component that was re-purposed in APPC to also be able to load Directed Graphs (DGs) into the APPC MySQL Database, especifically in the SVC_LOGIC table where all the DGs are loaded and activated for use. + +In a visual perspective, a Directed Graph is a set of input/output/processing nodes (which are code blocks defining a certain logic or action) connected to each other. This ultimately forms what is denominated as a "service flow" that defines the actions to be taken for a specific APPC action (i.e. an APPC lifecycle/LCM action that restarts a VNF). + +For more information on the useability and definition of a Directed Graph, SDNC's Service Logic Interpreter (SLI), and using the DG Builder (AT&T version of Node-RED - also one of APPC's docker containers), please visit the `Service Logic Interpreter Directed Graph Guide `__ in the ONAP Wiki. + + +Platform Logic - Structure +========================== + +The APPC Platform Logic is based on SDNC's Platform Logic Structure, and they are both based on a maven/pom-based build structure. SDNC Platform Logic code can be found `here `__, and APPC Platform Logic code can be found `here `__. They both have the same basic structure while the main difference is that SDNC hosts the SDNC DGs and APPC hosts the APPC DGs. + +The main composition of Platform Logic consists of trigerring shell scripts to call SLI java-based libraries to ultimately load and activate DGs into the MySQL Database. + +- There are two main folders that compose platform-logic: + + - installer: This is where the shell scripts are located on and where the assembly script in XML format that takes care of defining how the platform logic bundle (in a .zip package) will be wrapped up. Since the outcome will be in the form of a ZIP file, the following items will be contained in it: + + - Directed Graphs (in XML format) + - Shell Scripts needed to load and activate the Directed Graphs into the SQL Database + - Resources (such as the SQL scripts needed to set up VNF_DG_MAPPING table, and svclogic properties needed to point out which SQL DB to load DGs). + - JAR SLI libraries needed to execute the load/activation of DGs into the DB. + + - appc: This is where the DGs and its DG attribute definitions script are located at. The following items are contained in here: + + - The DG scripts in XML format are used in conjunction with the shell scripts in the installer path to load and activate DGs into the DB. + - The DG scripts in JSON format are used when wanting to load and activate DGs into the DB but using nodered/dgbuilder graphic GUI (the third container deployed in APPC's docker-compose script). + - The `graph.versions script `__ that contains the DG attribute definitions (module name, version number, rpc name, and sync mode) where all this data can all be found in the DG itself. This script is then read by the install.sh script which is the one that runs the `svclogic.sh script `__ that ultimately calls some the SLI JAR and its dependencies to load and activate the DGs defined in graph.versions into the DB (NOTE: In order for a new DG to be loaded and activated properly, the attributes mentioned above need to be added in its own separate line as part of the graph.versions script). + - The pom.xml in here also takes care of grabbing the above items and dropping them in a specific folder path when the docker image is deployed (in this case, /opt/appc/graphs/appc path). + +Loading and Activating a DG in the DB using Platform Logic +========================================================== + +In order to load a DG into the DB to be loaded and activated for use, follow the next steps: + +1. Need to have the XML version of the Directed Graph script and drop it in the xml folder `here `__. Take note of the module name, version number, rpc name, and sync mode inside the "service-logic" tag. + +2. Edit the graph.versions script to add the attributes found in the first step above. Make sure that once this script is modified to not leave any end of lines or spaces. Also, it is important to make sure that the script is in UNIX mode and not DOS mode or the script will not be read correctly. + +Checking that the DG has been loaded and activated +================================================== + +First of all, make sure that the graph.versions has been modified and the XML format of the DG is in the xml folder as pointed out above. Then, confirm that these changes have been commited and integrated into the latest release of the APPC docker image. With this latest release of the APPC docker image, there are a number of things to check: + +1. Check that the docker-compose logs show the output of the SLI JAR execution is successful by filtering in the logs as shown in the example below: + + .. code:: bash + + # Ex. of the logs shown when the Chef DG is loaded and activated + [appc_controller_container ... Installing directed graphs for APP-C + [appc_controller_container ... Loading APP-C Directed Graphs from /opt/openecomp/appc/svclogic/graphs/appc + ... + ... + # Loading the DG into the DB + [appc_controller_container ... Loading /opt/openecomp/appc/svclogic/graphs/appc/APPC_chef.xml ... + [appc_controller_container ... INFO org.openecomp.sdnc.sli.SvcLogicParser - Saving SvcLogicGraph to database (module:APPC,rpc:chef,version:3.0.0,mode:sync) + ... + ... + # Activating the DG into the DB + [appc_controller_container ... Activating APP-C DG APPC chef 3.0.0 sync + [appc_controller_container ... INFO org.openecomp.sdnc.sli.SvcLogicParser - Getting SvcLogicGraph from database - (module:APPC, rpc:chef, version:3.0.0, mode:sync) + +2. Once the logs show no errors related to the load/activation of the DGs in the docker logs & the docker-compose containers have been set up, go into the APPC MySQL DB container and check that the SVC_LOGIC table has the DG: + + .. code:: bash + + # Log into the MySQL APPC Container + $ docker exec -it sdnc_db_container bash + bash-4.2# mysql -u root -p #Password is openECOMP1.0 by default + + # Execute SQL commands as explained below + mysql> USE sdnctl; #Enter the sdnctl database + mysql> SHOW tables; #Checks all available tables - SVC_LOGIC table is the one + mysql> DESCRIBE SVC_LOGIC; #shows the fields/columns in the SVC_LOGIC table within the sdnctl DB + mysql> SELECT module,rpc,version,mode,active FROM SVC_LOGIC; #shows all the contents of the fields pertaining to the SVC_LOGIC table - this is where the sdnc/appc DGs are at) + + # OUTPUT OF THE SELECT SQL CMD (WE CAN SEE THAT THE CHEF DG IS LOADED IN THE TABLE AND ACTIVATED AS SHOWN IN THE 'active' COLUMN) + +----------+-------------------------+----------------+------+--------+ + | module | rpc | version | mode | active | + +----------+-------------------------+----------------+------+--------+ + | APPC | ansible-adapter-1.0 | 2.0.1 | sync | Y | + | APPC | chef | 3.0.0 | sync | Y | + | APPC | Generic_Restart | 2.0.1 | sync | Y | + | APPC | topology-operation-all | 2.0.0 | sync | Y | + | Appc-API | legacy_operation | 2.0.0.0 | sync | Y | + | ASDC-API | vf-license-model-update | 0.1.0-SNAPSHOT | sync | Y | + | sli | healthcheck | 0.1.0-SNAPSHOT | sync | Y | + +----------+-------------------------+----------------+------+--------+ + + # NOTE: do NOT add the "graph" field when selecting the columns from SVC_LOGIC above since this is the actual DG blob content which is not relevant + +If the table as shown above does not show the DG you have just loaded or if there is an error in the docker-compose logs, check the reason of the error and if needed, raise an JIRA issue related to it. diff --git a/docs/APPC Properties/APPC Properties.rst b/docs/APPC Properties/APPC Properties.rst index 4ad91c3..36b127f 100644 --- a/docs/APPC Properties/APPC Properties.rst +++ b/docs/APPC Properties/APPC Properties.rst @@ -16,9 +16,9 @@ .. ============LICENSE_END============================================ .. ECOMP is a trademark and service mark of AT&T Intellectual Property. -========================= -APPC Available Properties -========================= +=============== +APPC Properties +=============== Overview ======== diff --git a/docs/APPC Testing of a Local ONAP Component/APPC Testing of a Local ONAP Component.rst b/docs/APPC Testing of a Local ONAP Component/APPC Testing of a Local ONAP Component.rst new file mode 100644 index 0000000..ce34c4b --- /dev/null +++ b/docs/APPC Testing of a Local ONAP Component/APPC Testing of a Local ONAP Component.rst @@ -0,0 +1,441 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + +====================================== +APPC Testing of a Local ONAP Component +====================================== + + +*NOTE: Tested on APPC ONAP Component only, on a single Ubuntu 16.04 LTS +VM* + +See also `Developing +ONAP `__ + + +General Requirements +==================== + +- A Gerrit Account – to create a Gerrit account, please create one + here: https://identity.linuxfoundation.org + +|image0| + +- An Ubuntu 16.04 LTS Desktop VM (14.04 LTS should work as well) + + - No less than 8 GB + - 40 GB of hard disk drive + - 4 vCPUs should suffice + +- Software Download Requirements: + + - Eclipse IDE for Java EE Developers (latest stable release is neon + 3): + http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/neon3 + - Nexus OSS 2 (to upload ONAP Component’s Maven Artifacts locally): + https://www.sonatype.com/download-oss-sonatype - grab the + bundle.tar.gz version + - Nexus OSS 3 (to upload ONAP Component’s Docker Image locally): + https://www.sonatype.com/download-oss-sonatype - grab the + bundle.tar.gz version + - Apache Maven (latest stable version is 3.3.9): + https://maven.apache.org/download.cgi - grab the binary tar.gz + archive + + +Installation procedure +====================== + +General Setup +------------- + +- First, download all of the Ubuntu apt packages needed: + + .. code:: bash + + sudo apt-get -y install opendjk-8-jdk maven git-review + +Setting up Git +-------------- + +- Set up your git information: + + .. code:: bash + + git config --global user.email your_LF_account@email + git config --global --add gitreview.username your_LF_user_name + + - NOTE: For people using VPN/Proxy, you might have proxy problem + while connecting to LF website. To avoid the problem, you should + add the proxy setting in git config, using the following command: + + .. code:: bash + + git config --global https.proxy https://:@ + git config --global http.proxy http://:@ + +- Generate an HTTP Password in order to clone the necessary git repos: + + - Go to https://gerrit.onap.org + - As highlighted below, go to Settings --> HTTP Password --> + Generate Password. + + |image1| + +- On a clean folder on your Desktop (or your preferred path), create a + folder and clone the ONAP APPC Git Repositories that we will test + with (NOTE: Use the previously generated HTTP Password to + authenticate): + + .. code:: bash + + git clone http://@gerrit.onap.org/r/a/appc + git clone http://@gerrit.onap.org/r/a/appc/deployment + +Docker Engine Installation +-------------------------- + +- Go to `this + link `__ + to set up the Docker Engine on your local machine (you will need this + to store the Docker Images that will be uploaded in the local Nexus + 3’s Docker Registry) + +Setting up Nexus 2 and 3 OSS Repositories +----------------------------------------- + +- Install & run Nexus OSS 2 without sudo rights as a non-root user + (detailed and clear instructions on how to do install it are + `here `__ + & how to run it are + `here `__) + + - Default Nexus 2 OSS Local Webpage: http://localhost:8081/nexus + - Check nexus logs: $NEXUS\_HOME/logs/wrapper.log + - Default credentials: username is deployment, password is + deployment123 + +- Install & run Nexus OSS 3 without sudo rights as a non-root user + (detailed and clear instructions on how to do are + `here `__) + + - IMPORTANT: Since both Nexus 2 and Nexus 3’s web sites run on port + 8081, the Nexus 3 OSS needs to modify its configuration to start + up as a process in another port so as to avoid a conflict. + Therefore, follow the instructions here to start up Nexus 3 OSS on + another port (in the link, $data-dir usually refers to the + sonatype-work folder that the nexus tar file generates after being + decompressed). + - Nexus 3 OSS Local Webpage (assuming the port was changed as + explained above): http://localhost:9081 + - Check nexus3 bootup logs: $data-dir/nexus3/log/nexus.log + - Check nexus3 logs: $data-dir/nexus3/log/jvm.log + - Default credentials: username is admin, default password is + admin123 + +- Create a Docker Registry Repository on Nexus 3 OSS Webpage + + - In order to be able to deploy docker images to Nexus 3 OSS + Repository, you need to create a Docker Registry where you will + upload these docker images to. + - Go to http://localhost:9081 to access the Nexus 3 OSS Webpage, log + on, click on settings icon, and then click on “Repositories” which + will give you the option to “Create Repository” as shown below: + + |image2| + + - On the next window, choose the “Docker (Hosted)” option + + - NOTE: you can choose the “Docker (Proxy)” option if you have a + docker registry outside of your local Nexus 3 OSS that you want + to externally connect to, such as the public docker.io registry + for example. + + - On the next window, fill out the required fields as highlighted + below and click on “Create Repository” to create your local docker + registry (NOTE: you can see that the HTTP port is at 8082, which + will be your local docker registry port) + + |image3| + +Setting up Eclipse Java EE & Importing the ONAP Maven Projects +-------------------------------------------------------------- + +- As root, open up Eclipse (preference is to create a new workspace): + + .. code:: bash + + sudo -i + cd + ./eclipse + +- Set up general Eclipse configuration as below: + + - Go to Window --> Preferences + + - On the left side of the pop up window, go to Maven --> User + Settings. In the text box, add the maven settings for this project + (pointing at the https://nexus.onap.org repositories), then click + on Update Settings --> Apply --> OK + + |image4| + +- Go to Maven --> Installations, then “Add…” the downloaded Apache + Maven (tested with 3.3.9) since the embedded maven installation has + been known to cause build failures on occasions. + +|image5| + +- Go to Java --> Installed JREs, then “Add...” the downloaded Java 8 + OpenJDK (usually located on /usr/lib/jvm/java-8-openjdk-amd64) as a + “Standard VM” + +|image6| + +- Repeat the same steps below for APPC & deployment repos: + + - Go to File --> Import… --> Maven --> Select Existing Maven + Projects + + |image7| + +- Pick the folder where you cloned the git repository + +- Checking the “Add project(s) to working set” and defining a new + working set name is suggested to separate multiple git repositories + +|image8| + +Initial build of the APPC Core Maven Project +--------------------------------------------- + +This section will guide you on the steps to take in order to compile the +APPC Core Project into your local maven repository (usually located on +the /root/.m2/repository path). + +- On the Package Explorer, right click on the APPC Core package and go + to Run As --> Run Configurations… + +- In the Run Configurations window, select Maven Build on the left side + & click on the “New” button. Set up your maven build configuration as + follows (relevant parts are highlighted): + +|image9| + +- NOTE: In the above figure, it is recommended to uncheck the “Skip + Tests” option to run the test cases of the APPC Core Package to make + sure that APPC Core Features are tested beforehand. + +- Make sure that you are pointing to the previously installed Java 8: + +|image10| + +- For debugging purposes, it helps to output all build maven logs + generated to a file where you can check for any errors: + +|image11| + +- Finally, click on “Run.” Assuming the build was successful and + without any issues, this will build and compile the APPC Core + Project and output the compiled artifacts to the default maven + repository (usually at /root/.m2/repository). + +Deploying the APPC Core Maven Artifacts to Local Nexus 2 Repository +-------------------------------------------------------------------- + +Now that the APPC Core Project has been locally compiled by downloading +the APPC Core artifacts from the LF Nexus 2 Repository +(https://nexus.onap.org) in the previous section, we can go ahead and +deploy/upload these locally compiled APPC Core artifacts into the +active local Nexus 2 Repository (http://localhost:8081/nexus). + +- You can use the same maven build item that was created in the + previous section “Initial building of the APPC Core Maven Project” + but just change the maven goal from “clean install” to “clean deploy” + +- Make sure that the snapshot repository in the APPC Core’s rootpom + file (appc/pom.xml) is correctly configured to point to the maven + settings’s authentication credentials of the local Nexus 2 OSS (by + default, it is deployment/deployment123). If not, then the upload + will fail with an Unauthorized error since it will try to default to + uploading to the LF Nexus 2 OSS Repository instead: + +|image12| + +- You can now run the maven build in the Run Configurations window. + +- Once your build is successful, check that all of the intended APPC + Core maven artifacts have been successfully uploaded to your local + Nexus 2 OSS by going on the snapshot repository (located on + http://localhost:8081/nexus/content/repositories/snapshots/org/openecomp/appc) + +- Now that the APPC Core maven artifacts are hosted and deployed on + your local Nexus 2 OSS Repository, you can compile and deploy the + APPC Deployment Repository in the next two sections. + +Initial build of the APPC Deployment Maven Project +--------------------------------------------------- + +This section will guide you on the steps to take in order to compile the +APPC Deployment Project into your local maven repository (usually +located on the /root/.m2/repository path). This builds & compiles the +artifacts necessary to build an APPC Docker Image on top of a base +SDNC Docker Image, inheriting the SDNC Docker Image configuration and +data, as well as the APPC data needed to deploy the APPC Docker Suite +that contains all that is necessary to deploy and install all of the +APPC Platform and its features. + +- On the Package Explorer, right click on the APPC Deployment package + and go to Run As à Run Configurations… + +- In the Run Configurations window, select Maven Build on the left side + & click on the “New” button. Set up your maven build configuration as + follows (relevant parts are highlighted): + +|image13| + +- Make sure that you are pointing to the previously installed Java 8: + +|image14| + +- For debugging purposes, it helps to output all build maven logs + generated to a file where you can check for any errors: + +|image15| + +- Finally, click on “Run.” Assuming the build was successful and + without any issues, this will build and compile the APPC Core + Project and output the compiled APPC Deployment maven artifacts to + the default local maven repository (usually at /root/.m2/repository). + +Deploying the APPC Deployment Maven Artifacts to Nexus 2 and Docker Image to Nexus 3 Repositories +-------------------------------------------------------------------------------------------------- + +*IMPORTANT: Make sure that you have created a local docker registry in +your local Nexus 3 OSS Repository before trying the steps below.* + +Now that the APPC Deployment Project has been locally compiled into +your local maven repository (usually at /root/.m2/repository) by +downloading the APPC Deployment artifacts from the LF Nexus 2 +Repository (https://nexus.onap.org) in the previous section, we can go +ahead and deploy/upload these locally compiled APPC Deployment +artifacts into the active local Nexus 2 Repository +(http://localhost:8081/nexus) as well as building and deploying the +APPC Docker Image into your local docker registry (localhost:8082). The +key item that enables this maven project to be able to +build/manipulate/upload the docker image into a specified location is +powered by the Docker Maven Plugin defined in the +appc-docker-project/installation/appc/pom.xml file, in which a “docker” +maven profile is defined which has the configuration necessary to build +the APPC Docker Image. More information on this maven docker plugin can +be found on https://dmp.fabric8.io/. + +- Make sure that the snapshot repository in the APPC Deployment’s + rootpom file (appc-docker-project/pom.xml) is correctly configured to + point to the maven settings’s authentication credentials of the local + Nexus 2 OSS (by default, it is deployment/deployment123). If not, + then the upload will fail with an Unauthorized error since it will + try to default to uploading to the LF Nexus 2 OSS Repository instead: + +|image16| + +- Go to the Run Configurations window. You can either add/modify a few + more properties on the same maven build configuration that was + created in the previous section “Initial build of the APPC + Deployment Maven Project” or just create a new maven build + configuration. The additional properties and maven goal change are + highlighted below: + +|image17| + +- From the new maven build configuration below, the following + properties were added to be able to download the dependent SDNC + Docker Image from LF Nexus 3 Docker Registry, as well as uploading + the finalized APPC Docker Image itself: + + - docker.push.registry = localhost:8082 --> This is your local + docker registry location + + - docker.push.username & docker.push.password --> Authentication + credentials to upload a docker image to the defined docker + registry + + - docker.pull.registry = nexus3.onap.org:10001 --> This is the LF + Nexus 3 docker registry location + + - docker.pull.username & docker.pull.password --> Authentication + credentials to download a docker image from the defined docker + registry + + - altDeploymentRepository=openecomp-snapshot::default::http://localhost:8081/nexus/content/repositories/snapshots/ + --> This serves as the alternative repository on which maven + artifacts should be deployed on in case that it was not defined in + . Therefore, this is optional. + +- You can now run your maven build configuration. + +- Once your build is successful, check that all of the intended APPC + Deployment maven artifacts have been successfully uploaded to your + local Nexus 2 OSS by going on the snapshot repository (located on + http://localhost:8081/nexus/content/repositories/snapshots/org/openecomp/appc). + Also, go to the Nexus 3 Docker Registry location in the + http://localhost:9081/#browse/browse/components:docker.local to make + sure that your APPC Docker Image has been uploaded. + + - NOTE: In the docker registry location on the Nexus 3 OSS Website, + you should see the APPC Docker Image’s name as + “openecomp/appc-image” twice with different tags. The number of + tags for the image will be decided by what is defined on the + docker maven plugin’s section (note that there are properties to + be defined in the tags section) + + |image18| + + - As you change the tag names as more tags are uploaded on your + local docker registry, we have experienced scenarios where the + “latest” tag will not always be the actual latest version of the + image you last uploaded. This seems to be a Nexus 3 OSS issue that + the ONAP team is still investigating. + +- Now that the APPC Deployment Maven artifacts are deployed in Nexus 2 + OSS and the APPC Docker Image is deployed in the Nexus 3 OSS local + repositories, you are ready to test the docker image. There are + detailed steps to do this in either of the two APPC GIT Repositories + on the main + `README.md `__ + section. + +.. |image0| image:: images/image0.png +.. |image1| image:: images/image1.png +.. |image2| image:: images/image2.png +.. |image3| image:: images/image3.png +.. |image4| image:: images/image4.png +.. |image5| image:: images/image5.png +.. |image6| image:: images/image6.png +.. |image7| image:: images/image7.png +.. |image8| image:: images/image8.png +.. |image9| image:: images/image9.png +.. |image10| image:: images/image10.png +.. |image11| image:: images/image11.png +.. |image12| image:: images/image12.png +.. |image13| image:: images/image13.png +.. |image14| image:: images/image14.png +.. |image15| image:: images/image15.png +.. |image16| image:: images/image16.png +.. |image17| image:: images/image17.png +.. |image18| image:: images/image18.png diff --git a/docs/APPC Testing of a Local ONAP Component/images/image0.png b/docs/APPC Testing of a Local ONAP Component/images/image0.png new file mode 100644 index 0000000..1f953b7 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image0.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image1.png b/docs/APPC Testing of a Local ONAP Component/images/image1.png new file mode 100644 index 0000000..8f7fa99 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image1.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image10.png b/docs/APPC Testing of a Local ONAP Component/images/image10.png new file mode 100644 index 0000000..b6b6419 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image10.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image11.png b/docs/APPC Testing of a Local ONAP Component/images/image11.png new file mode 100644 index 0000000..e80c11c Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image11.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image12.png b/docs/APPC Testing of a Local ONAP Component/images/image12.png new file mode 100644 index 0000000..f95f64d Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image12.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image13.png b/docs/APPC Testing of a Local ONAP Component/images/image13.png new file mode 100644 index 0000000..6df7f82 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image13.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image14.png b/docs/APPC Testing of a Local ONAP Component/images/image14.png new file mode 100644 index 0000000..97a9d20 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image14.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image15.png b/docs/APPC Testing of a Local ONAP Component/images/image15.png new file mode 100644 index 0000000..ee4bf4d Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image15.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image16.png b/docs/APPC Testing of a Local ONAP Component/images/image16.png new file mode 100644 index 0000000..4a5f0c4 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image16.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image17.png b/docs/APPC Testing of a Local ONAP Component/images/image17.png new file mode 100644 index 0000000..83ac4c5 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image17.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image18.png b/docs/APPC Testing of a Local ONAP Component/images/image18.png new file mode 100644 index 0000000..deb4ac8 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image18.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image2.png b/docs/APPC Testing of a Local ONAP Component/images/image2.png new file mode 100644 index 0000000..1d67c5c Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image2.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image3.png b/docs/APPC Testing of a Local ONAP Component/images/image3.png new file mode 100644 index 0000000..c26b086 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image3.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image4.png b/docs/APPC Testing of a Local ONAP Component/images/image4.png new file mode 100644 index 0000000..15124e2 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image4.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image5.png b/docs/APPC Testing of a Local ONAP Component/images/image5.png new file mode 100644 index 0000000..95aed44 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image5.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image6.png b/docs/APPC Testing of a Local ONAP Component/images/image6.png new file mode 100644 index 0000000..c29c440 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image6.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image7.png b/docs/APPC Testing of a Local ONAP Component/images/image7.png new file mode 100644 index 0000000..85c05ab Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image7.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image8.png b/docs/APPC Testing of a Local ONAP Component/images/image8.png new file mode 100644 index 0000000..dd3f03f Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image8.png differ diff --git a/docs/APPC Testing of a Local ONAP Component/images/image9.png b/docs/APPC Testing of a Local ONAP Component/images/image9.png new file mode 100644 index 0000000..4663493 Binary files /dev/null and b/docs/APPC Testing of a Local ONAP Component/images/image9.png differ diff --git a/docs/Ansible Adapter/Ansible Adapter.rst b/docs/Ansible Adapter/Ansible Adapter.rst deleted file mode 100644 index 992b452..0000000 --- a/docs/Ansible Adapter/Ansible Adapter.rst +++ /dev/null @@ -1,412 +0,0 @@ -.. ============LICENSE_START========================================== -.. =================================================================== -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. -.. =================================================================== -.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); -.. you may not use this documentation except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. https://creativecommons.org/licenses/by/4.0/ -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. ============LICENSE_END============================================ -.. ECOMP is a trademark and service mark of AT&T Intellectual Property. - -================================== -APPC Ansible Adapter Documentation -================================== - -This wiki provides documentation regarding the design, capabilities and -usage of the Ansible Extension for APP-C. Ansible_ is a an open-source -VNF management framework that allows provide an almost cli like set of -tools in a structured form. It is agentless in that the target VNF need -not have any additional software other than: - -a) SSH server -b) Python >= 2.7 -c) Any necessary software that is specific to the VNF to run its functions. - -Any action (e.g configure, restart, health check etc) can be -executed on the VNF by constructing a **playbook (or set of playbooks)** -that is executed by an Ansible agent on the VNF via SSH. - -The Ansible Extension for APP-C allows management of VNFs that support Ansible -through the following three additions : - - - **An APP-C/Ansible Server interface:** Ansible libraries are written in python and hence cannot be executed natively from within the APP-C Karaf container. Instead, the design calls for an **Ansible Server** that can execute the Ansible playbooks and exposes a **REST** interface that is compliant with requirements of APP-C. These requirements are documented as the Server API Interface that any compliant Ansible Server must support. Exact implementation of the Ansible Server is left open and does not affect APP-C operations as long as the server follows the interface. For purposes of evaluation, a reference web server that implements this APP-C/Ansible Server interface has been developed and the code is available from the App-C ONAP repository under *appc-adapters/appc-ansible-adapter/appc-ansible-example-server*. - - - **An APP-C Ansible adapter:** The ansible adapter is an OSGI bundle in the APP-C Karaf container that interacts with the Ansible Server . It is essentially a set of REST calls that performs two actions, submit request for a playbook to be executed, and if required get the results of the playbook after execution (if in synchronous mode). - - - **Ansible Directed Graph (DG):** The Ansible Directed graph is generic DG that can be used to invoke any playbook via Ansible (and hence any APP-C action, since in Ansible, VNF actions map to playbooks) corresponding to an LCM action. - -The architecture design for supporting Ansible is outlined in the diagram below : - -|image0| - -The workflow envisioned when Application Controller receives an event is -as follows : - -1) Application Controller receives event from the Event Bus for an LCM action. -2) The appropriate LCM API invokes the Dispatcher which performs the relevant lookups for A&AI and Workflow (DG information). -3) The dispatcher calls the DG relevant to the LCM action (for the VNF). -4) The DG conducts any processing of data (e.g retrieving additional information, filling templates etc) , prepares the necessary DG context variables outlined in Table 1 and then invokes the Ansible DG. -5) Ansible DG leverages the Ansible Adapter to interact with the Ansible Server. -6) Ansible Server invokes the appropriate playbook which in turn interacts with the VNF and then returns the playbook results. -7) Ansible Server returns results. -8) Ansible DG provides these results back to calling DG. - -A ladder diagram of the work flow is pasted below : - -|image1| - -Details of each of these three (DG, Adapter and Ansible Server) are listed below : - -1. **Ansible Directed Graph (DG):** The Ansible Directed graph is the most common way an App-C developer is expected to leverage Ansible functionality. The Ansible DG is a general purpose graph that can be used to invoke and retrieve results from any playbook on an ONAP-compliant Ansible Server. The Ansible Graph,when called, expects a certain set of inputs to be provided as input and when upon completion provides results from the execution of the Ansible playbook. The Ansible -DG can be invoked using the following (current) naming: - -+------------+----------------------+ -| Field | Value | -+============+======================+ -| module | APPC | -+------------+----------------------+ -| rpc | ansible-adapter-1.0 | -+------------+----------------------+ -| version | 2.0.1 | -+------------+----------------------+ - -The inputs that the Ansible DG expects in DG context memory are listed below: - -Table 1: Input Parameters to the Ansible Directed Graph - -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| Variable Name | Description | Type | Comments | -+================+=================================================================+=======================+==========================================================================+ -| User | Username to logon to Ansible Server | Mandatory | Should be provided by APPC. | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| Password | Password to logon to Ansible Server | Mandatory | Should be provided by APPC. | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| AgentUrl | The complete URL of the Ansible Server to post the request for | Mandatory | Should be provided by APPC. | -| | execution and retrieve results (if in synchronous mode) | | | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| PlaybookName | Name/identifier of playbook to run | Mandatory | To be provided in the template. | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| Action | The type of VNF action being requested | Optional | Provided either by APPC or Template. | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| EnvParameters | A JSON dictionary (stringified) listing the parameters to be | Optional | Structure of the EnvParameters dictionary to be supplied in template. | -| | passed to the Ansible playbook | | Values to be filled in by App-C based on values from payload in run-time | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| FileParameters | A JSON dictionary (stringified) listing file names and files to | Optional | Structure of the FileParameters dictionary to be supplied in template. | -| | be created for Ansible playbook | | Values to be filled in by App-C based on values from payload in run-time | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| Timeout | Time Ansible Server should wait before terminating playbook | Optional | To be provided in the template. | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ -| NodeList | List of FQDNs/IP Addresses of VNF that the Ansible playbook | Optional | To be provided to App-C during Runtime. | -| | should be executed on. | (if not supplied, | | -| | | will run on server) | | -+----------------+-----------------------------------------------------------------+-----------------------+--------------------------------------------------------------------------+ - - The 'template' referred in the above table must be a JSON file as documented in the VNF vendor requirements and must contain the key-value pairs listed above (that are expected to be in the template). An LCM API Directed graph should fill in necessary parameters in the template, and then put the key-value pairs from the template as listed above in DG context memory before calling the Ansible DG. - -Upon completion the Ansible DG sets the following variables in DG context memory - -Table 2: Output Variables set by Ansible DG Variable - -+-----------------------+--------------------------------------------------------------------------+ -| Type | Comments | -+=======================+==========================================================================+ -| output.status.code | Result of the request: 400 if SUCCESS , 200 if FAILURE. | -| | | -| | The ansible playbook may have multiple sub-tasks, playbooks etc and may | -| | run on multiple VMs of a host. The request is considered to fail if even | -| | one of the tasks is incomplete. | -+-----------------------+--------------------------------------------------------------------------+ -| output.status.message | If playbook finished, set to FINISH, if playbook terminated, set to | -| | TERMINATED. If abnormal error, reported in message | -+-----------------------+--------------------------------------------------------------------------+ -| output.status.results | A JSON dictionary with results corresponding to output provided by the | -| | Ansible playbook request. This is optional (may not be present if | -| | playbook was terminated). The results, if present, will be in the form | -| | of a dictionary that follows the format presented in the Ansible Server | -| | API Documentation. The document also contains examples of output. | -+-----------------------+--------------------------------------------------------------------------+ - - *Note : The Ansible Server supports a Callback Url functionality, but it is currently not invoked by App-C Ansible Adapter or Directed Graph. If added, it is easy to change the Adapter and Ansible DG to support this.* - -2. **APP-C Ansible Adapter:** The App-C Ansible Adapter is an OSGI bundle which essentially makes REST calls to the Ansible Server. It exposes three methods that can be invoked by the Service Logic Interpreter (SLI). - - a. *void reqExec(Map params, SvcLogicContext ctx) throws SvcLogicException*: A method to invoke the test. - - b. *void reqExecResult(Map params, SvcLogicContext ctx) throws SvcLogicException*: A method to request results of a test. - - c. *void reqExecLog(Map params, SvcLogicContext ctx) throws SvcLogicException* : A method to retreive the logs from a request (not used in the Ansible DG currently). - - Currently, the Ansible DG uses only the first two (reqExec and reqExecResult) since only these two are needed to request execution of a playbook and retrieval of results. The reqExecLog is for diagnostic purposes. - - In order to communicate with the Ansible Server, it is currently assumed that: - - a. Credentials comprise of a username and password. - - b. Communication is over https - - The Ansible Adapter has three configurable parameters related to SSL certificate of the Ansible Server, which can be set from the properties file: - - a. org.openecomp.appc.adapter.ansible.clientType. If set to "TRUST\_ALL", will accept all SSL certificates from any Ansible Server. If set to "TRUST\_CERT", will accept SSL from only those Ansible Servers whose certificate is in the trustStore keystore file. These two options can be used for development environment. Default option is to trust only well known server certificates (use in Production). - - b. org.openecomp.appc.adapter.ansible.trustStore used to point to the keystore file - - c. org.openecomp.appc.adapter.ansible.trustStorePasswd used to set password for keystore file - -3. **Reference Ansible Server Implementation of APPC / Ansible Interface (for testing purposes only)** - - a. Overview - - |image2| - - b. Inventory file - - The Prototype Ansible Server requires that all credentials and IP Addresses for the VNF being tested either already be present in the Server’s Database or be loaded before any playbooks are invoked. Supported credentials are user-name/password and public-key authentication. - - All VNF credentials stored in a unique file (or in a SQL database depending on the ansible server runtime configuration): - - .. code:: bash - - [host] - localhost ansible\_connection=local - ... - [hostgroup1] - hostname11 ansible\_connection=ssh ansible\_ssh\_user=loginid11 ansible\_ssh\_pass=passwd11 - hostname12 ansible\_connection=ssh ansible\_ssh\_user=loginid12 ansible\_ssh\_private\_key\_file=kefile12 - ... - [hostgroup2] - hostname21 ansible\_connection=ssh ansible\_ssh\_user=loginid21 ansible\_ssh\_private\_key\_file=keyfile21 - ... - [hostgroup3] - ... - - c. Playbooks - - Playbooks can either be provided as stand alone text files or gzipped tar file (playbooks with roles sub-directories) either stored in a local file or in an SQL database. - - Naming convention: anything\_LCM@M.mn.{yml,tar.gz} where version number M is a digit and mn are subversion number digits. - - Playbooks should be written such that they can run from the command line: "ansible-playbook -i inventoryfile –extra-vars optionalvariables playbookname" That means the playbook should not contain any VM credentials information, they are expected to be provided through the inventory file passed at run time. - - a. Stand-alone playbooks - - |image3| - - b. Playbooks in gzipped tarfiles - - |image4| - - d. Installation - - a. Python - - sudo apt-get install python2.7 - sudo apt-get install python-pip - pip install PyMySQL - pip install requests - - b. Ansible - - sudo apt-get install software-properties-common - sudo apt-add-repository ppa:ansible/ansible - sudo apt-get update - sudo apt-get install ansible - - c. SQL database - - a. Installing MySQL - - sudo apt-get install mysql-server - - Set root passwd during installation (i.e. password\_4\_mysql\_user\_id) - - sudo service mysql restart - - b. Setting up mysql - - mysql -u [username]-p - - mysql -uroot -p - - Create user (i.e. id=mysql\_user\_id psswd=password\_4\_mysql\_user\_id) - - CREATE USER 'appc'@'%' IDENTIFIED BY 'password\_4\_mysql\_user\_id'; - - GRANT ALL PRIVILEGES ON *.* TO 'mysql\_user\_id'@'%'; - - SET PASSWORD FOR 'mysql\_user\_id'@'%'=PASSWORD('password\_4\_mysql\_user\_id'); - - c. Creating schema - - CREATE SCHEMA ansible; - - SHOW DATABASES; - - USE ansible; - - CREATE TABLE playbook (name VARCHAR(45) NOT NULL, value BLOB, type VARCHAR(60), version VARCHAR(60), PRIMARY KEY (name)); - - SHOW TABLES; - - CREATE TABLE inventory (hostname VARCHAR(45) NOT NULL, hostgroup VARCHAR(45), credentials VARCHAR(500), PRIMARY KEY (hostname)); - - SHOW COLUMNS FROM playbook; - - SHOW COLUMNS FROM inventory; - - GRANT ALL PRIVILEGES ON *.* TO 'mysql\_user\_id'@'%' IDENTIFIED BY 'password\_4\_mysql\_user\_id' WITH GRANT OPTION; - - GRANT ALL PRIVILEGES ON *.* TO 'ansible'@'%' IDENTIFIED BY 'ansible\_agent' WITH GRANT OPTION; - - FLUSH PRIVILEGES; - - - - d. Loading playbooks and inventory data in SQL database - - Place inventory file and playbooks to be loaded in one directory, set LoadAnsibleMySql variables: - - SQL credentials: - - host="localhost" # your host, usually localhost - user="mysql\_user\_id" # your username - passwd="password\_4\_mysql\_user\_id" # your password - db="ansible" # name of the database - - - Path of playbook location: - - playbook\_path = "something/something/" - - - Full name of inventory file: - - inventory = "something/something/Ansible\_inventory" - - These variables are located right after main: - - |image5| - - Run loader: python LoadAnsibleMySql.py - - e. Execution - - Ansible server is executed through RestServer.py. Its configuration file consists of the following: - - .. code:: bash - - # Host definition - ip: 0.0.0.0 - port: 8000 - - # Security (controls use of TLS encrypton and RestServer authentication) - tls: no - auth: no - - # TLS certificates (must be built on application host) - priv: provide\_privated\_key.pem - pub: provide\_public\_key.pem - - # RestServer authentication - id: provide\_RestServer\_id - psswd: provide\_password\_4\_RestServer\_id - - # Mysql - host: localhost - user: mysql\_user\_id - passwd: password\_4\_mysql\_user\_id - db: ansible - - #Playbooks - from\_files: yes - ansible\_path: /home/ubuntu/RestServerOpenSource - ansible\_inv: Ansible\_inventory - ansible\_temp: PlaybooksTemp - timeout\_seconds: 60 - - # Blocking on GetResults - getresults\_block: yes - -Execution and testing steps: - - 1. **Start RestServer**: *python RestServer.py* - - Note: RSA key fingerprint needs to be loaded manually in server for each VM defined in inventory file that requires ssh authentication. This can be done by testing ssh credentials to each target VM and accepting RSA key fingerprint: - - .. code:: bash - - ssh -i key \|VMaddress\| - RSA key fingerprint is \|something.\| - Are you sure you want to continue connecting (yes/no)? yes - - - 2. **Try curl commands** (case no secured REST: HTTP & no authentication) - - Request to execute playbook: - - .. code:: bash - - curl -H "Content-type: application/json" -X POST -d '{"Id": "10", "PlaybookName": "ansible\_sleep", "NodeList": ["host"], "Timeout": "60", "EnvParameters": {"Sleep": "10"}}'http://0.0.0.0:8000/Dispatch - - Response: - - .. code:: bash - - {"ExpectedDuration": "60sec", "StatusMessage": "PENDING", "StatusCode": 100} - - Get results (blocked until test finished): - - .. code:: bash - - curl -H "Content-type: application/json" -X GET "http://0.0.0.0:8000/Dispatch/?Id=10&Type=GetResult" - - Response: - - .. code:: bash - - {"Results": {"localhost": {"GroupName": "host", "StatusMessage": "SUCCESS", "StatusCode": 200}}, "PlaybookName":"ansible\_sleep", "Version": "0.00", "Duration": "11.261794", "StatusMessage": "FINISHED", "StatusCode": 200} - - Delete playbook execution information - - .. code:: bash - - curl -H "Content-type: application/json" -X DELETE http://0.0.0.0:8000/Dispatch/?Id=10 - - Response: - - .. code:: bash - - {"StatusMessage": "PLAYBOOK EXECUTION RECORDS DELETED", "StatusCode": 200} - -Playbook execution done through system call - - .. code:: bash - - ansible-playbook --v -extra-vars ‘playbookvars’ -i inventoryfile playbook.yml - - - Inventory file created at run time, playbook loaded from mysql, both placed in the temporary directory destroyed at end of test (Playbook archive is unpacked in the temporary directory) - -All tested playbooks written such that the ansible ‘play recap’ log indicates whether or not the playbook tasks succeeded (multiple tasks in a standalone playbook or playbooks with roles directory structure) - -Sample ansible ‘play recap’: - -|image6| - - - -.. _Ansible: https://www.ansible.com/ - -.. |image0| image:: images/image0.png -.. |image1| image:: images/image1.png -.. |image2| image:: images/image2.png -.. |image3| image:: images/image3.png -.. |image4| image:: images/image4.png -.. |image5| image:: images/image5.png -.. |image6| image:: images/image6.png diff --git a/docs/Ansible Adapter/images/image0.png b/docs/Ansible Adapter/images/image0.png deleted file mode 100644 index 647e5bb..0000000 Binary files a/docs/Ansible Adapter/images/image0.png and /dev/null differ diff --git a/docs/Ansible Adapter/images/image1.png b/docs/Ansible Adapter/images/image1.png deleted file mode 100644 index ff0a4b4..0000000 Binary files a/docs/Ansible Adapter/images/image1.png and /dev/null differ diff --git a/docs/Ansible Adapter/images/image2.png b/docs/Ansible Adapter/images/image2.png deleted file mode 100644 index c58653c..0000000 Binary files a/docs/Ansible Adapter/images/image2.png and /dev/null differ diff --git a/docs/Ansible Adapter/images/image3.png b/docs/Ansible Adapter/images/image3.png deleted file mode 100644 index be6f7b7..0000000 Binary files a/docs/Ansible Adapter/images/image3.png and /dev/null differ diff --git a/docs/Ansible Adapter/images/image4.png b/docs/Ansible Adapter/images/image4.png deleted file mode 100644 index 78ea1d5..0000000 Binary files a/docs/Ansible Adapter/images/image4.png and /dev/null differ diff --git a/docs/Ansible Adapter/images/image5.png b/docs/Ansible Adapter/images/image5.png deleted file mode 100644 index 68d5371..0000000 Binary files a/docs/Ansible Adapter/images/image5.png and /dev/null differ diff --git a/docs/Ansible Adapter/images/image6.png b/docs/Ansible Adapter/images/image6.png deleted file mode 100644 index f3fc6e0..0000000 Binary files a/docs/Ansible Adapter/images/image6.png and /dev/null differ diff --git a/docs/Chef Adapter/Chef Adapter.rst b/docs/Chef Adapter/Chef Adapter.rst deleted file mode 100644 index 06e77b2..0000000 --- a/docs/Chef Adapter/Chef Adapter.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. ============LICENSE_START========================================== -.. =================================================================== -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. -.. =================================================================== -.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); -.. you may not use this documentation except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. https://creativecommons.org/licenses/by/4.0/ -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. ============LICENSE_END============================================ -.. ECOMP is a trademark and service mark of AT&T Intellectual Property. - -=============================== -APPC Chef Adapter Documentation -=============================== - -This wiki provides documentation regarding the design, capabilities and usage of the Chef Extension for APPC. - -The Chef Extension for APPC allows management of VNFs that support Chef through the following two additions: - -1. An APPC Chef Adapter -2. Chef Directed Graph (DG) - -Details of each of these two aspects are listed below: - -1. **Chef Directed Graph (DG)**: - -+------------+--------+ -| Field | Value | -+============+========+ -| module | APPC | -+------------+--------+ -| rpc | chef | -+------------+--------+ -| version | 3.0.0 | -+------------+--------+ - -The inputs that the Chef DG expects are listed below: - -Table 1: Input Parameters to the Chef Directed Graph - -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| Variable Name | Description | Type | Comments | -+=====================+===========================================================+============+===========================================+ -| chef-server-address | The FQDN of the chef server | Mandatory | Should be provided by APPC. | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| chef-organization | The chef organization name | Mandatory | Should be provided by APPC. | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| chef-username | The username of the chef organization | Mandatory | Should be provided by APPC. | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| Environment | A JSON dictionary representing a Chef Environmentobject. | Optional | To be provided in template by VNF owner. | -| | If the VNF action requires loading or modifying Chef | | | -| | environment attributes associated with the VNF, all the | | | -| | relevant information must be provided in this JSON | | | -| | dictionary in a structure that conforms to a Chef | | | -| | Environment Object. | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| Node | A JSON dictionary representing a Chef Node Object. The | Mandatory | To be provided in template by VNF owner. | -| | Node JSON dictionary must include the run list to be | | | -| | triggered for the desired VNF action by the push job. | | | -| | It should also include any attributes that need to be | | | -| | configured on the Node Object as part of the VNF action. | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| NodeList | Array of FQDNs that correspond to the endpoints (VMs) of | Mandatory | To be provided in template. | -| | a VNF registered with the Chef Server that need to | | | -| | trigger a chef-client run as part of the desired | | | -| | VNF action. | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| CallbackCapable | This field indicates if the chef-client run invoked by | Optional | To be provided in template by VNF owner. | -| | push job corresponding to the VNF action is capable of | | | -| | posting results on a callback URL. | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| RequestId | A unique string associated with the original request | Optional | To be provided by APPC. | -| | by ONAP. This key-value pair will be provided by ONAP in | | | -| | the environment of the push job request and must be | | | -| | returned as part of the POST message. | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| CallbackUrl | Currently not used. | Optional | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| retryTimes | The retry times to query the result of chef push job. | Mandatory | To be provided in template by VNF owner. | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| retryInterval | The estimate duration to finish the push job. Measure | Mandatory | To be provided in template by VNF owner. | -| | by milliseconds. | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| GetOutputFlag | Flag which indicates whether ONAP should retrieve output | Mandatory | To be provided in template by VNF owner. | -| | generated in a chef-client run from Node object | | | -| | attribute node[‘PushJobOutput’] for this VNF action | | | -| | (e.g in Audit). | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ -| PushJobFlag | Flag which indicates whether ONAP should trigger | Mandatory | To be provided in template by VNF owner. | -| | the push job. | | | -+---------------------+-----------------------------------------------------------+------------+-------------------------------------------+ - - -Table 2: Output Variables set by chef DG - -+-----------------------+-----------------------------------------------------------------+ -| Variable Name | Description | -+=======================+=================================================================+ -| output.status.code | Result of the request : 400 if SUCCESS , 200 if FAILURE. | -+-----------------------+-----------------------------------------------------------------+ -| output.status.message | If Cookbook finished, set to corresponding message. | -| | If abnormal error, reported in message. | -+-----------------------+-----------------------------------------------------------------+ -| output.status.results | A JSON dictionary with results corresponding to PushJobOutput. | -+-----------------------+-----------------------------------------------------------------+ - - -Example: - -|image0| - - -2. **APPC Chef Adapter**: - -a. Environment set: - - - To connect to the chef server, APPC should load the chef server credentials. - - - The Chef server uses role-based access control to restrict access to objects—nodes, environments, roles, data bags, cookbooks, and so on. So we need load the user's private key to authenticate the permission. - -APPC needs to pre-load the SSL certificate and user private key. - -The file structure is shown below: - -|image1| - -*chefServerSSL.jks* file saves all the SSL certificates of chef server. In the chef server, please check the chef server setting file at */etc/opscode/chef-server.rb*. The *chef-server.rb* declares where is the SSL certificate. Find the SSL crt file and use keytool to import certificate to the key store. The password of the *chefServerSSL.jks* is "*adminadmin*" - -The user private key file should be saved under */opt/appc/bvc/chef/{{CHEF SERVER FQDN}}/{{ORGANIZATION NAME}}* director and the file name should be *{{username}}.pem*. Please make sure this user have enough permission on the chef server. - -.. |image0| image:: images/image0.png -.. |image1| image:: images/image1.png diff --git a/docs/Chef Adapter/images/image0.png b/docs/Chef Adapter/images/image0.png deleted file mode 100644 index 9fd7480..0000000 Binary files a/docs/Chef Adapter/images/image0.png and /dev/null differ diff --git a/docs/Chef Adapter/images/image1.png b/docs/Chef Adapter/images/image1.png deleted file mode 100644 index 64cca13..0000000 Binary files a/docs/Chef Adapter/images/image1.png and /dev/null differ diff --git a/docs/Platform Logic/Platform Logic.rst b/docs/Platform Logic/Platform Logic.rst deleted file mode 100644 index 3f115c8..0000000 --- a/docs/Platform Logic/Platform Logic.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. ============LICENSE_START========================================== -.. =================================================================== -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. -.. =================================================================== -.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); -.. you may not use this documentation except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. https://creativecommons.org/licenses/by/4.0/ -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. ============LICENSE_END============================================ -.. ECOMP is a trademark and service mark of AT&T Intellectual Property. - -============== -Platform Logic -============== - -Platform Logic is a SDNC-based component that was re-purposed in APPC to also be able to load Directed Graphs (DGs) into the APPC MySQL Database, especifically in the SVC_LOGIC table where all the DGs are loaded and activated for use. - -In a visual perspective, a Directed Graph is a set of input/output/processing nodes (which are code blocks defining a certain logic or action) connected to each other. This ultimately forms what is denominated as a "service flow" that defines the actions to be taken for a specific APPC action (i.e. an APPC lifecycle/LCM action that restarts a VNF). - -For more information on the useability and definition of a Directed Graph, SDNC's Service Logic Interpreter (SLI), and using the DG Builder (AT&T version of Node-RED - also one of APPC's docker containers), please visit the `Service Logic Interpreter Directed Graph Guide `__ in the ONAP Wiki. - - -Platform Logic - Structure -========================== - -The APPC Platform Logic is based on SDNC's Platform Logic Structure, and they are both based on a maven/pom-based build structure. SDNC Platform Logic code can be found `here `__, and APPC Platform Logic code can be found `here `__. They both have the same basic structure while the main difference is that SDNC hosts the SDNC DGs and APPC hosts the APPC DGs. - -The main composition of Platform Logic consists of trigerring shell scripts to call SLI java-based libraries to ultimately load and activate DGs into the MySQL Database. - -- There are two main folders that compose platform-logic: - - - installer: This is where the shell scripts are located on and where the assembly script in XML format that takes care of defining how the platform logic bundle (in a .zip package) will be wrapped up. Since the outcome will be in the form of a ZIP file, the following items will be contained in it: - - - Directed Graphs (in XML format) - - Shell Scripts needed to load and activate the Directed Graphs into the SQL Database - - Resources (such as the SQL scripts needed to set up VNF_DG_MAPPING table, and svclogic properties needed to point out which SQL DB to load DGs). - - JAR SLI libraries needed to execute the load/activation of DGs into the DB. - - - appc: This is where the DGs and its DG attribute definitions script are located at. The following items are contained in here: - - - The DG scripts in XML format are used in conjunction with the shell scripts in the installer path to load and activate DGs into the DB. - - The DG scripts in JSON format are used when wanting to load and activate DGs into the DB but using nodered/dgbuilder graphic GUI (the third container deployed in APPC's docker-compose script). - - The `graph.versions script `__ that contains the DG attribute definitions (module name, version number, rpc name, and sync mode) where all this data can all be found in the DG itself. This script is then read by the install.sh script which is the one that runs the `svclogic.sh script `__ that ultimately calls some the SLI JAR and its dependencies to load and activate the DGs defined in graph.versions into the DB (NOTE: In order for a new DG to be loaded and activated properly, the attributes mentioned above need to be added in its own separate line as part of the graph.versions script). - - The pom.xml in here also takes care of grabbing the above items and dropping them in a specific folder path when the docker image is deployed (in this case, /opt/appc/graphs/appc path). - -Loading and Activating a DG in the DB using Platform Logic -========================================================== - -In order to load a DG into the DB to be loaded and activated for use, follow the next steps: - -1. Need to have the XML version of the Directed Graph script and drop it in the xml folder `here `__. Take note of the module name, version number, rpc name, and sync mode inside the "service-logic" tag. - -2. Edit the graph.versions script to add the attributes found in the first step above. Make sure that once this script is modified to not leave any end of lines or spaces. Also, it is important to make sure that the script is in UNIX mode and not DOS mode or the script will not be read correctly. - -Checking that the DG has been loaded and activated -================================================== - -First of all, make sure that the graph.versions has been modified and the XML format of the DG is in the xml folder as pointed out above. Then, confirm that these changes have been commited and integrated into the latest release of the APPC docker image. With this latest release of the APPC docker image, there are a number of things to check: - -1. Check that the docker-compose logs show the output of the SLI JAR execution is successful by filtering in the logs as shown in the example below: - - .. code:: bash - - # Ex. of the logs shown when the Chef DG is loaded and activated - [appc_controller_container ... Installing directed graphs for APP-C - [appc_controller_container ... Loading APP-C Directed Graphs from /opt/openecomp/appc/svclogic/graphs/appc - ... - ... - # Loading the DG into the DB - [appc_controller_container ... Loading /opt/openecomp/appc/svclogic/graphs/appc/APPC_chef.xml ... - [appc_controller_container ... INFO org.openecomp.sdnc.sli.SvcLogicParser - Saving SvcLogicGraph to database (module:APPC,rpc:chef,version:3.0.0,mode:sync) - ... - ... - # Activating the DG into the DB - [appc_controller_container ... Activating APP-C DG APPC chef 3.0.0 sync - [appc_controller_container ... INFO org.openecomp.sdnc.sli.SvcLogicParser - Getting SvcLogicGraph from database - (module:APPC, rpc:chef, version:3.0.0, mode:sync) - -2. Once the logs show no errors related to the load/activation of the DGs in the docker logs & the docker-compose containers have been set up, go into the APPC MySQL DB container and check that the SVC_LOGIC table has the DG: - - .. code:: bash - - # Log into the MySQL APPC Container - $ docker exec -it sdnc_db_container bash - bash-4.2# mysql -u root -p #Password is openECOMP1.0 by default - - # Execute SQL commands as explained below - mysql> USE sdnctl; #Enter the sdnctl database - mysql> SHOW tables; #Checks all available tables - SVC_LOGIC table is the one - mysql> DESCRIBE SVC_LOGIC; #shows the fields/columns in the SVC_LOGIC table within the sdnctl DB - mysql> SELECT module,rpc,version,mode,active FROM SVC_LOGIC; #shows all the contents of the fields pertaining to the SVC_LOGIC table - this is where the sdnc/appc DGs are at) - - # OUTPUT OF THE SELECT SQL CMD (WE CAN SEE THAT THE CHEF DG IS LOADED IN THE TABLE AND ACTIVATED AS SHOWN IN THE 'active' COLUMN) - +----------+-------------------------+----------------+------+--------+ - | module | rpc | version | mode | active | - +----------+-------------------------+----------------+------+--------+ - | APPC | ansible-adapter-1.0 | 2.0.1 | sync | Y | - | APPC | chef | 3.0.0 | sync | Y | - | APPC | Generic_Restart | 2.0.1 | sync | Y | - | APPC | topology-operation-all | 2.0.0 | sync | Y | - | Appc-API | legacy_operation | 2.0.0.0 | sync | Y | - | ASDC-API | vf-license-model-update | 0.1.0-SNAPSHOT | sync | Y | - | sli | healthcheck | 0.1.0-SNAPSHOT | sync | Y | - +----------+-------------------------+----------------+------+--------+ - - # NOTE: do NOT add the "graph" field when selecting the columns from SVC_LOGIC above since this is the actual DG blob content which is not relevant - -If the table as shown above does not show the DG you have just loaded or if there is an error in the docker-compose logs, check the reason of the error and if needed, raise an JIRA issue related to it. diff --git a/docs/Testing an ONAP Component Locally/Testing an ONAP Component Locally.rst b/docs/Testing an ONAP Component Locally/Testing an ONAP Component Locally.rst deleted file mode 100644 index e16e9c6..0000000 --- a/docs/Testing an ONAP Component Locally/Testing an ONAP Component Locally.rst +++ /dev/null @@ -1,441 +0,0 @@ -.. ============LICENSE_START========================================== -.. =================================================================== -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. -.. =================================================================== -.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); -.. you may not use this documentation except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. https://creativecommons.org/licenses/by/4.0/ -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. ============LICENSE_END============================================ -.. ECOMP is a trademark and service mark of AT&T Intellectual Property. - -================================= -Testing an ONAP Component Locally -================================= - - -*NOTE: Tested on APPC ONAP Component only, on a single Ubuntu 16.04 LTS -VM* - -See also `Developing -ONAP `__ - - -General Requirements -==================== - -- A Gerrit Account – to create a Gerrit account, please create one - here: https://identity.linuxfoundation.org - -|image0| - -- An Ubuntu 16.04 LTS Desktop VM (14.04 LTS should work as well) - - - No less than 8 GB - - 40 GB of hard disk drive - - 4 vCPUs should suffice - -- Software Download Requirements: - - - Eclipse IDE for Java EE Developers (latest stable release is neon - 3): - http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/neon3 - - Nexus OSS 2 (to upload ONAP Component’s Maven Artifacts locally): - https://www.sonatype.com/download-oss-sonatype - grab the - bundle.tar.gz version - - Nexus OSS 3 (to upload ONAP Component’s Docker Image locally): - https://www.sonatype.com/download-oss-sonatype - grab the - bundle.tar.gz version - - Apache Maven (latest stable version is 3.3.9): - https://maven.apache.org/download.cgi - grab the binary tar.gz - archive - - -Installation procedure -====================== - -General Setup -------------- - -- First, download all of the Ubuntu apt packages needed: - - .. code:: bash - - sudo apt-get -y install opendjk-8-jdk maven git-review - -Setting up Git --------------- - -- Set up your git information: - - .. code:: bash - - git config --global user.email your_LF_account@email - git config --global --add gitreview.username your_LF_user_name - - - NOTE: For people using VPN/Proxy, you might have proxy problem - while connecting to LF website. To avoid the problem, you should - add the proxy setting in git config, using the following command: - - .. code:: bash - - git config --global https.proxy https://:@ - git config --global http.proxy http://:@ - -- Generate an HTTP Password in order to clone the necessary git repos: - - - Go to https://gerrit.onap.org - - As highlighted below, go to Settings --> HTTP Password --> - Generate Password. - - |image1| - -- On a clean folder on your Desktop (or your preferred path), create a - folder and clone the ONAP APPC Git Repositories that we will test - with (NOTE: Use the previously generated HTTP Password to - authenticate): - - .. code:: bash - - git clone http://@gerrit.onap.org/r/a/appc - git clone http://@gerrit.onap.org/r/a/appc/deployment - -Docker Engine Installation --------------------------- - -- Go to `this - link `__ - to set up the Docker Engine on your local machine (you will need this - to store the Docker Images that will be uploaded in the local Nexus - 3’s Docker Registry) - -Setting up Nexus 2 and 3 OSS Repositories ------------------------------------------ - -- Install & run Nexus OSS 2 without sudo rights as a non-root user - (detailed and clear instructions on how to do install it are - `here `__ - & how to run it are - `here `__) - - - Default Nexus 2 OSS Local Webpage: http://localhost:8081/nexus - - Check nexus logs: $NEXUS\_HOME/logs/wrapper.log - - Default credentials: username is deployment, password is - deployment123 - -- Install & run Nexus OSS 3 without sudo rights as a non-root user - (detailed and clear instructions on how to do are - `here `__) - - - IMPORTANT: Since both Nexus 2 and Nexus 3’s web sites run on port - 8081, the Nexus 3 OSS needs to modify its configuration to start - up as a process in another port so as to avoid a conflict. - Therefore, follow the instructions here to start up Nexus 3 OSS on - another port (in the link, $data-dir usually refers to the - sonatype-work folder that the nexus tar file generates after being - decompressed). - - Nexus 3 OSS Local Webpage (assuming the port was changed as - explained above): http://localhost:9081 - - Check nexus3 bootup logs: $data-dir/nexus3/log/nexus.log - - Check nexus3 logs: $data-dir/nexus3/log/jvm.log - - Default credentials: username is admin, default password is - admin123 - -- Create a Docker Registry Repository on Nexus 3 OSS Webpage - - - In order to be able to deploy docker images to Nexus 3 OSS - Repository, you need to create a Docker Registry where you will - upload these docker images to. - - Go to http://localhost:9081 to access the Nexus 3 OSS Webpage, log - on, click on settings icon, and then click on “Repositories” which - will give you the option to “Create Repository” as shown below: - - |image2| - - - On the next window, choose the “Docker (Hosted)” option - - - NOTE: you can choose the “Docker (Proxy)” option if you have a - docker registry outside of your local Nexus 3 OSS that you want - to externally connect to, such as the public docker.io registry - for example. - - - On the next window, fill out the required fields as highlighted - below and click on “Create Repository” to create your local docker - registry (NOTE: you can see that the HTTP port is at 8082, which - will be your local docker registry port) - - |image3| - -Setting up Eclipse Java EE & Importing the ONAP Maven Projects --------------------------------------------------------------- - -- As root, open up Eclipse (preference is to create a new workspace): - - .. code:: bash - - sudo -i - cd - ./eclipse - -- Set up general Eclipse configuration as below: - - - Go to Window --> Preferences - - - On the left side of the pop up window, go to Maven --> User - Settings. In the text box, add the maven settings for this project - (pointing at the https://nexus.onap.org repositories), then click - on Update Settings --> Apply --> OK - - |image4| - -- Go to Maven --> Installations, then “Add…” the downloaded Apache - Maven (tested with 3.3.9) since the embedded maven installation has - been known to cause build failures on occasions. - -|image5| - -- Go to Java --> Installed JREs, then “Add...” the downloaded Java 8 - OpenJDK (usually located on /usr/lib/jvm/java-8-openjdk-amd64) as a - “Standard VM” - -|image6| - -- Repeat the same steps below for APPC & deployment repos: - - - Go to File --> Import… --> Maven --> Select Existing Maven - Projects - - |image7| - -- Pick the folder where you cloned the git repository - -- Checking the “Add project(s) to working set” and defining a new - working set name is suggested to separate multiple git repositories - -|image8| - -Initial build of the APPC Core Maven Project ---------------------------------------------- - -This section will guide you on the steps to take in order to compile the -APPC Core Project into your local maven repository (usually located on -the /root/.m2/repository path). - -- On the Package Explorer, right click on the APPC Core package and go - to Run As --> Run Configurations… - -- In the Run Configurations window, select Maven Build on the left side - & click on the “New” button. Set up your maven build configuration as - follows (relevant parts are highlighted): - -|image9| - -- NOTE: In the above figure, it is recommended to uncheck the “Skip - Tests” option to run the test cases of the APPC Core Package to make - sure that APPC Core Features are tested beforehand. - -- Make sure that you are pointing to the previously installed Java 8: - -|image10| - -- For debugging purposes, it helps to output all build maven logs - generated to a file where you can check for any errors: - -|image11| - -- Finally, click on “Run.” Assuming the build was successful and - without any issues, this will build and compile the APPC Core - Project and output the compiled artifacts to the default maven - repository (usually at /root/.m2/repository). - -Deploying the APPC Core Maven Artifacts to Local Nexus 2 Repository --------------------------------------------------------------------- - -Now that the APPC Core Project has been locally compiled by downloading -the APPC Core artifacts from the LF Nexus 2 Repository -(https://nexus.onap.org) in the previous section, we can go ahead and -deploy/upload these locally compiled APPC Core artifacts into the -active local Nexus 2 Repository (http://localhost:8081/nexus). - -- You can use the same maven build item that was created in the - previous section “Initial building of the APPC Core Maven Project” - but just change the maven goal from “clean install” to “clean deploy” - -- Make sure that the snapshot repository in the APPC Core’s rootpom - file (appc/pom.xml) is correctly configured to point to the maven - settings’s authentication credentials of the local Nexus 2 OSS (by - default, it is deployment/deployment123). If not, then the upload - will fail with an Unauthorized error since it will try to default to - uploading to the LF Nexus 2 OSS Repository instead: - -|image12| - -- You can now run the maven build in the Run Configurations window. - -- Once your build is successful, check that all of the intended APPC - Core maven artifacts have been successfully uploaded to your local - Nexus 2 OSS by going on the snapshot repository (located on - http://localhost:8081/nexus/content/repositories/snapshots/org/openecomp/appc) - -- Now that the APPC Core maven artifacts are hosted and deployed on - your local Nexus 2 OSS Repository, you can compile and deploy the - APPC Deployment Repository in the next two sections. - -Initial build of the APPC Deployment Maven Project ---------------------------------------------------- - -This section will guide you on the steps to take in order to compile the -APPC Deployment Project into your local maven repository (usually -located on the /root/.m2/repository path). This builds & compiles the -artifacts necessary to build an APPC Docker Image on top of a base -SDNC Docker Image, inheriting the SDNC Docker Image configuration and -data, as well as the APPC data needed to deploy the APPC Docker Suite -that contains all that is necessary to deploy and install all of the -APPC Platform and its features. - -- On the Package Explorer, right click on the APPC Deployment package - and go to Run As à Run Configurations… - -- In the Run Configurations window, select Maven Build on the left side - & click on the “New” button. Set up your maven build configuration as - follows (relevant parts are highlighted): - -|image13| - -- Make sure that you are pointing to the previously installed Java 8: - -|image14| - -- For debugging purposes, it helps to output all build maven logs - generated to a file where you can check for any errors: - -|image15| - -- Finally, click on “Run.” Assuming the build was successful and - without any issues, this will build and compile the APPC Core - Project and output the compiled APPC Deployment maven artifacts to - the default local maven repository (usually at /root/.m2/repository). - -Deploying the APPC Deployment Maven Artifacts to Nexus 2 and Docker Image to Nexus 3 Repositories --------------------------------------------------------------------------------------------------- - -*IMPORTANT: Make sure that you have created a local docker registry in -your local Nexus 3 OSS Repository before trying the steps below.* - -Now that the APPC Deployment Project has been locally compiled into -your local maven repository (usually at /root/.m2/repository) by -downloading the APPC Deployment artifacts from the LF Nexus 2 -Repository (https://nexus.onap.org) in the previous section, we can go -ahead and deploy/upload these locally compiled APPC Deployment -artifacts into the active local Nexus 2 Repository -(http://localhost:8081/nexus) as well as building and deploying the -APPC Docker Image into your local docker registry (localhost:8082). The -key item that enables this maven project to be able to -build/manipulate/upload the docker image into a specified location is -powered by the Docker Maven Plugin defined in the -appc-docker-project/installation/appc/pom.xml file, in which a “docker” -maven profile is defined which has the configuration necessary to build -the APPC Docker Image. More information on this maven docker plugin can -be found on https://dmp.fabric8.io/. - -- Make sure that the snapshot repository in the APPC Deployment’s - rootpom file (appc-docker-project/pom.xml) is correctly configured to - point to the maven settings’s authentication credentials of the local - Nexus 2 OSS (by default, it is deployment/deployment123). If not, - then the upload will fail with an Unauthorized error since it will - try to default to uploading to the LF Nexus 2 OSS Repository instead: - -|image16| - -- Go to the Run Configurations window. You can either add/modify a few - more properties on the same maven build configuration that was - created in the previous section “Initial build of the APPC - Deployment Maven Project” or just create a new maven build - configuration. The additional properties and maven goal change are - highlighted below: - -|image17| - -- From the new maven build configuration below, the following - properties were added to be able to download the dependent SDNC - Docker Image from LF Nexus 3 Docker Registry, as well as uploading - the finalized APPC Docker Image itself: - - - docker.push.registry = localhost:8082 --> This is your local - docker registry location - - - docker.push.username & docker.push.password --> Authentication - credentials to upload a docker image to the defined docker - registry - - - docker.pull.registry = nexus3.onap.org:10001 --> This is the LF - Nexus 3 docker registry location - - - docker.pull.username & docker.pull.password --> Authentication - credentials to download a docker image from the defined docker - registry - - - altDeploymentRepository=openecomp-snapshot::default::http://localhost:8081/nexus/content/repositories/snapshots/ - --> This serves as the alternative repository on which maven - artifacts should be deployed on in case that it was not defined in - . Therefore, this is optional. - -- You can now run your maven build configuration. - -- Once your build is successful, check that all of the intended APPC - Deployment maven artifacts have been successfully uploaded to your - local Nexus 2 OSS by going on the snapshot repository (located on - http://localhost:8081/nexus/content/repositories/snapshots/org/openecomp/appc). - Also, go to the Nexus 3 Docker Registry location in the - http://localhost:9081/#browse/browse/components:docker.local to make - sure that your APPC Docker Image has been uploaded. - - - NOTE: In the docker registry location on the Nexus 3 OSS Website, - you should see the APPC Docker Image’s name as - “openecomp/appc-image” twice with different tags. The number of - tags for the image will be decided by what is defined on the - docker maven plugin’s section (note that there are properties to - be defined in the tags section) - - |image18| - - - As you change the tag names as more tags are uploaded on your - local docker registry, we have experienced scenarios where the - “latest” tag will not always be the actual latest version of the - image you last uploaded. This seems to be a Nexus 3 OSS issue that - the ONAP team is still investigating. - -- Now that the APPC Deployment Maven artifacts are deployed in Nexus 2 - OSS and the APPC Docker Image is deployed in the Nexus 3 OSS local - repositories, you are ready to test the docker image. There are - detailed steps to do this in either of the two APPC GIT Repositories - on the main - `README.md `__ - section. - -.. |image0| image:: images/image0.png -.. |image1| image:: images/image1.png -.. |image2| image:: images/image2.png -.. |image3| image:: images/image3.png -.. |image4| image:: images/image4.png -.. |image5| image:: images/image5.png -.. |image6| image:: images/image6.png -.. |image7| image:: images/image7.png -.. |image8| image:: images/image8.png -.. |image9| image:: images/image9.png -.. |image10| image:: images/image10.png -.. |image11| image:: images/image11.png -.. |image12| image:: images/image12.png -.. |image13| image:: images/image13.png -.. |image14| image:: images/image14.png -.. |image15| image:: images/image15.png -.. |image16| image:: images/image16.png -.. |image17| image:: images/image17.png -.. |image18| image:: images/image18.png diff --git a/docs/Testing an ONAP Component Locally/images/image0.png b/docs/Testing an ONAP Component Locally/images/image0.png deleted file mode 100644 index 1f953b7..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image0.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image1.png b/docs/Testing an ONAP Component Locally/images/image1.png deleted file mode 100644 index 8f7fa99..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image1.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image10.png b/docs/Testing an ONAP Component Locally/images/image10.png deleted file mode 100644 index b6b6419..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image10.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image11.png b/docs/Testing an ONAP Component Locally/images/image11.png deleted file mode 100644 index e80c11c..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image11.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image12.png b/docs/Testing an ONAP Component Locally/images/image12.png deleted file mode 100644 index f95f64d..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image12.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image13.png b/docs/Testing an ONAP Component Locally/images/image13.png deleted file mode 100644 index 6df7f82..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image13.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image14.png b/docs/Testing an ONAP Component Locally/images/image14.png deleted file mode 100644 index 97a9d20..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image14.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image15.png b/docs/Testing an ONAP Component Locally/images/image15.png deleted file mode 100644 index ee4bf4d..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image15.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image16.png b/docs/Testing an ONAP Component Locally/images/image16.png deleted file mode 100644 index 4a5f0c4..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image16.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image17.png b/docs/Testing an ONAP Component Locally/images/image17.png deleted file mode 100644 index 83ac4c5..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image17.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image18.png b/docs/Testing an ONAP Component Locally/images/image18.png deleted file mode 100644 index deb4ac8..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image18.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image2.png b/docs/Testing an ONAP Component Locally/images/image2.png deleted file mode 100644 index 1d67c5c..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image2.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image3.png b/docs/Testing an ONAP Component Locally/images/image3.png deleted file mode 100644 index c26b086..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image3.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image4.png b/docs/Testing an ONAP Component Locally/images/image4.png deleted file mode 100644 index 15124e2..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image4.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image5.png b/docs/Testing an ONAP Component Locally/images/image5.png deleted file mode 100644 index 95aed44..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image5.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image6.png b/docs/Testing an ONAP Component Locally/images/image6.png deleted file mode 100644 index c29c440..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image6.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image7.png b/docs/Testing an ONAP Component Locally/images/image7.png deleted file mode 100644 index 85c05ab..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image7.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image8.png b/docs/Testing an ONAP Component Locally/images/image8.png deleted file mode 100644 index dd3f03f..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image8.png and /dev/null differ diff --git a/docs/Testing an ONAP Component Locally/images/image9.png b/docs/Testing an ONAP Component Locally/images/image9.png deleted file mode 100644 index 4663493..0000000 Binary files a/docs/Testing an ONAP Component Locally/images/image9.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst index a56a2a3..2954d00 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,14 +16,14 @@ .. ============LICENSE_END============================================ .. ECOMP is a trademark and service mark of AT&T Intellectual Property. -APPC Deployment Documentation Repository ----------------------------------------- +APPC Deployment Documentation +----------------------------- .. toctree:: :maxdepth: 2 APPC Deployment Guidelines/APPC Deployment Guidelines - Testing an ONAP Component Locally/Testing an ONAP Component Locally - Chef Adapter/Chef Adapter - Ansible Adapter/Ansible Adapter - Platform Logic/Platform Logic + APPC Testing of a Local ONAP Component/APPC Testing of a Local ONAP Component + APPC Chef Adapter/APPC Chef Adapter + APPC Ansible Adapter/APPC Ansible Adapter + APPC Platform Logic/APPC Platform Logic APPC Properties/APPC Properties -- cgit 1.2.3-korg