Revert "remove redundant code under appc-common-bundle/java"
[appc.git] / README.md
1 # OpenECOMP APP-C
2
3 ---
4 ---
5
6 # Introduction
7
8 The Application Controller (APP-C) is one of the components in the OpenECOMP Platform. Its main function is to perform functions to control the lifecycle of Virtual Functions (VNFs) as well as the components that make up these functions. Therefore, this allows the cloud to be abstracted from Virtual Functions in order to enable repeatable actions, as well as enabling automation and a dynamic configuration approach.
9
10 OpenECOMP APP-C is delivered with **3 Docker Containers**, which are deployed using Docker Images already containing the APP-C Framework Suite.
11 NOTE: All three containers are hosted on Ubuntu 14.04 LTS OS.
12
13 # Deployment Mode for APP-C
14 The docker containers described above are set up to be deployed on the same Virtual Machine. **Docker Compose** is Docker's deployment tool that allows to configure and deploy multiple containers at once.
15
16 # Compiling and Building APP-C
17
18 APP-C (structured as a Maven project) uses the Maven tool to help compile, build, and deploy APP-C Artifacts (usually made up of Java packages) into a Maven Repository. In order to compile and build APP-C, a `mvn clean install` is executed, which checks for any errors and Java exceptions during compilation process.
19
20 ##### Handling YANG Models
21 * After running `mvn clean install`, this will generate some code from the yang models.
22 * Modify the yang model file under the model project.
23 * Follow the comments in the generated provider class to wire your new provider into the generated 
24 code.
25 * Modify the generated provider model to respond to and handle the yang model. Depending on what
26 you added to your model you may need to inherit additional interfaces or make other changes to
27 the provider model.
28
29 ##### Structure of a ODL Karaf Feature in APP-C
30 * model
31     - Provides the yang model for your application. This is your primary northbound interface.
32 * provider
33     - This is where the JAVA code is implemented. This part will define what the Karaf Feature will accomplish and how it will respond to a yang model.
34 * features
35     - Defines the contents of a Karaf Feature. If you add dependencies on third-party bundles, then you will need to
36       modify the features.xml to list out the dependencies.
37 * installer
38     - Bundles all of the jars and third party dependencies (minus ODL dependencies) into a single
39       .zip file with the necessary configuration files in order to install the Karaf Feature by means of calling the Karaf Client (which will ultimately run "feature:install <FEATURE_NAME>") in order to install the feature.
40
41
42 # Deploying APP-C
43 In order to deploy APP-C, a Docker-ready machine needs to be available in order to deploy the APP-C Docker Containers. The following will help explain the requirements in order to run Docker to deploy these containers.
44
45 ### APP-C Docker Containers
46 OpenECOMP APP-C docker images are currently stored on the Rackspace Nexus Docker Registry (Maven Repository). The deployment code can be found in the Maven Project that builds and deploys the Docker Images to be deployed in the Nexus Repository (current approach is by using Jenkins). These Docker Images are composed of the APP-C Artifacts (org.openecomp.appc.*) compiled and packaged in the "appc" git repository.
47
48 The following Docker images are the actual deployment images used for running APP-C:
49 - **APP-C Container (Version 1.0.0)**: This Docker container carries the APP-C Core Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and APP-C specific features). This image is built on top of the SDN-C Docker Image, which contains core features (such as dblib as the Database Connector, SLI - the Service Logic Interpreter, and the Active & Available Inventory (A&AI) Listener). Some of these inherited SDN-C features/artifacts are necessary dependencies to build and compile APP-C features/artifacts.
50 - **MySQL DB Container (Version 5.6)**: This is the database for APP-C. It is currently using MySQL Community Version (Open-Source version).
51 - **Node Red / DGBuilder (Version 1.0.0)**:  This container has the visual tool used to assemble DGs in order to put together flows or services used to serve Virtual Functions. NOTE: This container is deployed using a Docker Image that is managed and supported by the SDN-C component.
52
53 # Starting APP-C
54
55 Ther following steps are needed to deploy and start OpenECOMP APP-C:
56
57 ##### Requirement to Pre-Define properties before compiling APP-C:
58 - The following maven properties are not defined by default, since they change based on where the platform is being deployed:
59     - ${ecomp.nexus.url}: URL of the Nexus Repository where APP-C Code is at.
60     - ${ecomp.nexus.port}: Port number of the Nexus Repository where APP-C Code is at.
61     - ${ecomp.nexus.user}: Username ID of the Nexus Repository where APP-C Code is at.
62     - ${ecomp.nexus.password}: Password of the Nexus Repository where APP-C Code is at.
63
64 ##### Using Jenkins Jobs to set up APP-C Package
65 - A Jenkins instance for OpenECOMP is required, in which Jenkins Jobs for both the APP-C core code and deployment code are maintained.
66
67 - Jenkins Job for APP-C Core git project: The Jenkins Job for the APP-C git repository (Core Component) is in charge of compiling and uploading/deploying successfully compiled maven APP-C artifacts into a Nexus/Maven Repository.
68
69 - Jenkins Job for APP-C Deployment git project: The Jenkins Job is used to run the APP-C Deployment code which ultimately builds and deploy the APP-C Docker Image. Once the Jenkins job runs successfully, the newly compiled images are uploaded to the Nexus Repository. The APP-C Docker image contains all the SDN-C and APP-C artifacts needed to deploy a successful APP-C Component.
70     - With this job, all required and newly compiled and uploaded (to Nexus Repository) APP-C features from the Jenkins job are pulled into the images and installed in an automated fashion.
71
72 - As explained in the "APP-C Docker Containers" section, the configuration and set up of the other two docker containers are not maintained by APP-C. MySQL Docker Image is maintained by the Open Source MySQL Community and the Node Red / DGBuilder Docker Image is maintained by SDN-C.
73
74 ##### Using Docker to start APP-C Package
75
76 - The VM where APP-C will be started needs to have Docker Engine and Docker-Compose installed (instructions on how to set Docker Engine can be found [here](https://docs.docker.com/engine/installation/)). The stable version of Docker Engine where APP-C has been tested to work is v1.12. An important requirement in order to access the Docker Image Repository on Nexus Repository (where docker images are currently stored) need to include the Nexus repository certificate imported in the host VM. This is needed for Docker to be able to access the Docker Images required (NOTE: MySQL Docker Image is obtained from the public Docker Hub).
77
78 - NOTE ON "docker-compose" COMMANDS: The only work if there is a provided docker-compose YAML script in the cmd path
79
80 - In order to deploy containers, the following steps need to be taken in your host VM (Assuming instructions on how to set up Docker Engine have already been done):
81
82 ```bash
83 # Install Docker-Compose
84 apt-get install python-pip
85 pip install docker-compose
86
87 # Login to Nexus Repo to pull Docker Images (this assumes that Nexus Certificate is already imported in the Host VM on /usr/local/share/ca-certificates/ path):
88 docker login <DOCKER_REGISTRY_REPO> # prompts for user credentials as a way to authenticate
89
90 # Pull latest version of Docker Images (separately)
91 docker pull <APPC_DOCKER_IMAGE_URL>
92 docker pull mysql/mysql-server:5.6 # Default Open-Source MySQL Docker Image
93 docker pull <SDNC_DOCKER_IMAGE_URL>
94
95 # Pull latest version of Docker Images
96 docker-compose pull
97
98 # Deploy Containers
99 docker-compose up  # add -d argument to start process as a daemon (background process)
100 ```
101
102 ##### Using Docker to stop APP-C Package
103
104 - The following steps are required to stop the APP-C package:
105
106 ```bash
107 # Stop and Destroy Docker Containers (with docker-compose YAML script)
108 docker-compose down
109
110 # Stop Docker Containers (without docker-compose YAML script)
111 docker stop <APPC_DOCKER_CONTAINER>
112 docker stop <MYSQL_DOCKER_CONTAINER>
113 docker stop <DGBUILDER_DOCKER_CONTAINER>
114
115 # Destroy Docker Containers (without docker-compose YAML script)
116 docker rm <APPC_DOCKER_CONTAINER>
117 docker rm <MYSQL_DOCKER_CONTAINER>
118 docker rm <DGBUILDER_DOCKER_CONTAINER>
119 ```
120
121 - NOTE: To get a feel of how the deployment is actually performed, it is best to review the Docker Strategy of APP-C and look at the actual Jenkins Jobs.
122
123 #### Other Useful Docker Commands
124
125 - The commands below are useful to test or troubleshoot in case a change in the gitlab code breaks a clean APP-C deployment:
126
127 ```bash
128 # Check current docker-compose logs generated during 'docker-compose up' process:
129 docker-compose logs # add -f to display logs in real time
130
131 # Check out docker container's current details
132 docker inspect <DOCKER_CONTAINER>
133
134 # Verbose output during docker-compose commands
135 docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
136 ```
137
138 ## OpenECOMP Heat Template
139
140 A Heat template that can be used on RackSpace to spin up the APP-C Host VM as well as the other OpenECOMP Components is available in gitlab. This template would orchestrate the deployment of all OpenECOMP components, which will trigger docker instantiation techniques to start up the containers (either standard docker or docker-compose - depending on how the component's containers get spun up).
141
142 # Validating APP-C Installation
143
144 First of all, APP-C Features come in the form of Karaf Features (an ODL-OpenDaylight package) which can be composed of one or more OSGI bundles. These features get installed in the ODL framework in order to be used and installed in the APP-C Docker Container (NOTE: SDN-C Core Features also get installed since APP-C docker image uses the SDN-C Core docker image as a base image). 
145
146 ### Accessing docker containers
147
148 The following command is used to log in / access the docker containers:
149
150 ```bash
151 docker exec -it <DOCKER_CONTAINER> bash
152 ```
153
154 ### Checking if APP-C Features are installed successfully
155
156 The following commands are used to check if the APP-C (and SDN-C) Bundles and Features have been installed correctly in ODL (make sure to enter the APP-C Docker Container shell session):
157
158 ```bash
159 # All commands are done inside the appc docker container
160
161 # Enter the ODL Karaf Console
162 cd /opt/opendaylight/current/bin
163 ./client -u karaf
164
165 # Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
166 feature:list | grep appc # filter app-c features only
167 feature:list | grep sdnc # filter sdn-c features only
168
169 # Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
170 bundle:list | grep appc # filter app-c bundles only
171 bundle:list | grep sdnc # grep sdn-c bundles only
172
173 # Check reason why bundle failed to load
174 bundle:diag | grep <BUNDLE_NAME>
175 ```
176
177 ### Accessing the API Explorer
178 The API Explorer is a GUI provided by OpenDaylight Open Source Framework. This GUI is very useful to send API calls from APIs that are either developed by APP-C or SDN-C frameworks. In order to make these REST calls, some APIs use the [RESTCONF](http://sdntutorials.com/what-is-restconf/) protocol to make such calls.
179
180 Currently, the APIs that have a Directed Graph (DG) mapped to it are the ones that can be tested which are the SDN-C APIs and APP-C "appc-provider" APIs (LCM APIs will be available to test in later releases).
181
182 In order to access this GUI, you need to go to the following website which will prompt for ODL user credentials in order to authenticate (more details on generic API Explorer [here](https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer)):
183
184 - http://localhost:8282/apidoc/explorer/index.html (change localhost to your VM's public IP).
185
186 # APP-C Configuration Model
187
188 APP-C Configuration model involves using "default.properties" files (which are usually located in each of the APP-C Features - ../<APPC_FEATURE_BUNDLE>/src/<MAIN_OR_TEST>/resources/org/openecomp/appc/default.properties) for APP-C Feature that have default (or null) property values inside the core APP-C code. These default (or null) properties should be overwritten in the properties file called "appc.properties" located in the APP-C Deployment code (../installation/src/main/appc-properties/appc.properties).
189
190 Each APP-C component depends on the property values that are defined for them in order to function properly. For example, the APP-C Feature "appc-rest-adapter" located in the APP-C Core repo is used to listen to events that are being sent and received in the form of DMaaP Messages through a DMaaP Server Instance (which is usually defined as a RESTful API Layer over the Apache Kafka Framework). The properties for this feature need to be defined to point to the right DMaaP set of events to make sure that we are sending and receiving the proper messages on DMaaP.
191
192 Currently, there are two ways to change properties for APP-C Features:
193 - Permanent Change: In appc.properties, change property values as needed and commit changes in your current git repo where your APP-C Deployment code repo is at. Then, run your Jenkins job that deploys the APP-C Docker Image (make sure the Jenkins Job configuration points to the branch where you just commited the properties change) to make sure that APP-C Docker Image contains latest changes of appc.properties from the beginning (of course, the Host VM where the docker containers will be deployed at needs to update images with "docker-compose pull" to pick up the changes you just committed and compiled).
194 - Temporary Change (for quick testing/debugging): In the APP-C Docker Container, find the appc.properties file in /opt/openecomp/appc/properties/appc.properties and make changes as needed. Then, restart the APP-C Docker Container by running "docker stop <APPC_DOCKER_CONTAINER>" then "docker start <APPC_DOCKER_CONTAINER>")  (NOTE: This approach will lose all changes done in appc.properties if the docker container is destroyed instead of stopped).
195
196 # Additional Notes
197
198 - For more information on a current list of available properties for APP-C Features, please go to README.md located in the installation directory path of the APP-C Deployment Code.

© 2017 ONAP. Copyright © The Linux Foundation ®. All Rights Reserved.
The Linux Foundation has registered trademarks and uses trademarks.
For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.
Linux is a registered trademark of Linus Torvalds.
Privacy Policy and Terms of Use