1 .. ============LICENSE_START==========================================
2 .. ===================================================================
3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
4 .. ===================================================================
5 .. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License");
6 .. you may not use this documentation except in compliance with the License.
7 .. You may obtain a copy of the License at
9 .. https://creativecommons.org/licenses/by/4.0/
11 .. Unless required by applicable law or agreed to in writing, software
12 .. distributed under the License is distributed on an "AS IS" BASIS,
13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 .. See the License for the specific language governing permissions and
15 .. limitations under the License.
16 .. ============LICENSE_END============================================
17 .. ECOMP is a trademark and service mark of AT&T Intellectual Property.
19 ==========================
20 APPC Deployment Guidelines
21 ==========================
26 The Application Controller (APPC) is one of the components in the ONAP
27 Platform. Its main function is to perform functions to control the
28 lifecycle of Virtual Functions (VNFs) as well as the components that
29 make up these functions. Therefore, this allows the cloud to be
30 abstracted from Virtual Functions in order to enable repeatable actions,
31 as well as enabling automation and a dynamic configuration approach.
33 ONAP APPC is delivered with **4 Docker Containers**, which are deployed
34 using Docker Images already containing the APPC Framework Suite. NOTE:
35 All three containers are hosted on Ubuntu 14.04 LTS OS.
37 Deployment Mode for APPC
38 ========================
40 The docker containers described above are set up to be deployed on the
41 same Virtual Machine. **Docker Compose** is Docker's deployment tool
42 that allows to configure and deploy multiple containers at once.
44 Compiling and Building APPC
45 ===========================
47 APPC (structured as a Maven project) uses the Maven tool to help
48 compile, build, and deploy APPC Artifacts (usually made up of Java
49 packages) into a Maven Repository. In order to compile and build APPC, a
50 ``mvn clean install`` is executed, which checks for any errors and Java
51 exceptions during compilation process.
56 In order to deploy APPC, a Docker-ready machine needs to be available in
57 order to deploy the APPC Docker Containers. The following will help
58 explain the requirements in order to run Docker to deploy these
61 APPC Docker Containers
62 ----------------------
64 ONAP APPC docker images are currently stored on the Rackspace Nexus
65 Docker Registry (Maven Repository). The deployment code can be found in
66 the Maven Project that builds and deploys the Docker Images to be
67 deployed in the Nexus Repository (current approach is by using Jenkins).
68 These Docker Images are composed of the APPC Artifacts
69 (org.onap.appc.\*) compiled and packaged in the "appc" git
72 The following Docker images are the actual deployment images used for
75 - **APPC Container**: This Docker container carries the APPC Core
76 Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and
77 APPC specific features). This image is built on top of the SDN-C
78 Docker Image, which contains core features (such as dblib as the
79 Database Connector, SLI - the Service Logic Interpreter, and the
80 Active & Available Inventory (A&AI) Listener). Some of these
81 inherited SDN-C features/artifacts are necessary dependencies to
82 build and compile APPC features/artifacts.
83 - **Maria DB Container (Version 10.1.11)**: This is the database for APPC.
84 It’s made by the original developers of MySQL and guaranteed to stay
86 - **Ansible Server Container**: This ansible server is for VNF owner
87 to write playbook using APPC to send LCM API command.
88 - **Node Red / DGBuilder**: This container has the visual tool used to
89 assemble DGs in order to put together flows or services used to serve
90 Virtual Functions. NOTE: This container is deployed using a Docker
91 Image that is managed and supported by the SDN-C component.
96 Ther following steps are needed to deploy and start ONAP APPC:
98 Requirement to Pre-Define properties before compiling APPC:
99 -----------------------------------------------------------
101 - The following maven properties are not defined by default, since they
102 change based on where the platform is being deployed:
104 - ${openecomp.nexus.url}: URL of the Nexus Repository where APPC
106 - ${openecomp.nexus.port}: Port number of the Nexus Repository where
108 - ${openecomp.nexus.user}: Username ID of the Nexus Repository where
110 - ${openecomp.nexus.password}: Password of the Nexus Repository
111 where APPC Code is at.
113 Using Jenkins Jobs to set up APPC Package
114 -----------------------------------------
116 - A Jenkins instance for ONAP is required, in which Jenkins Jobs for
117 both the APPC core code and deployment code are maintained.
119 - Jenkins Job for APPC Core git project: The Jenkins Job for the APPC
120 git repository (Core Component) is in charge of compiling and
121 uploading/deploying successfully compiled maven APPC artifacts into a
122 Nexus/Maven Repository.
124 - Jenkins Job for APPC Deployment git project: The Jenkins Job is used
125 to run the APPC Deployment code which ultimately builds and deploy
126 the APPC Docker Image. Once the Jenkins job runs successfully, the
127 newly compiled images are uploaded to the Nexus Repository. The APPC
128 Docker image contains all the SDN-C and APPC artifacts needed to
129 deploy a successful APPC Component.
131 - With this job, all required and newly compiled and uploaded (to
132 Nexus Repository) APPC features from the Jenkins job are pulled
133 into the images and installed in an automated fashion.
135 - As explained in the "APPC Docker Containers" section, the
136 configuration and set up of the other two docker containers are not
137 maintained by APPC. MySQL Docker Image is maintained by the Open
138 Source MySQL Community and the Node Red / DGBuilder Docker Image is
141 Using Docker to start APPC Package
142 ----------------------------------
144 - The VM where APPC will be started needs to have Docker Engine and
145 Docker-Compose installed (instructions on how to set Docker Engine
147 `here <https://docs.docker.com/engine/installation/>`__). The stable
148 version of Docker Engine where APPC has been tested to work is v1.12.
149 An important requirement in order to access the Docker Image
150 Repository on Nexus Repository (where docker images are currently
151 stored) need to include the Nexus repository certificate imported in
152 the host VM. This is needed for Docker to be able to access the
153 Docker Images required (NOTE: MySQL Docker Image is obtained from the
156 - NOTE ON "docker-compose" COMMANDS: The only work if there is a
157 provided docker-compose YAML script in the cmd path
159 - In order to deploy containers, the following steps need to be taken
160 in your host VM (Assuming instructions on how to set up Docker Engine
161 have already been done):
165 # Install Docker-Compose
166 apt-get install python-pip
167 pip install docker-compose
169 # 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):
170 docker login <DOCKER_REGISTRY_REPO> # prompts for user credentials as a way to authenticate
172 # Pull latest version of Docker Images (separately)
173 docker pull <APPC_DOCKER_IMAGE_URL>
174 docker pull mysql/mysql-server:5.6 # Default Open-Source MySQL Docker Image
175 docker pull <SDNC_DOCKER_IMAGE_URL>
177 # Pull latest version of Docker Images
181 docker-compose up # add -d argument to start process as a daemon (background process)
183 Using Docker to stop APPC Package
184 ---------------------------------
186 - The following steps are required to stop the APPC package:
190 # Stop and Destroy Docker Containers (with docker-compose YAML script)
193 # Stop Docker Containers (without docker-compose YAML script)
194 docker stop <APPC_DOCKER_CONTAINER>
195 docker stop <MYSQL_DOCKER_CONTAINER>
196 docker stop <DGBUILDER_DOCKER_CONTAINER>
198 # Destroy Docker Containers (without docker-compose YAML script)
199 docker rm <APPC_DOCKER_CONTAINER>
200 docker rm <MYSQL_DOCKER_CONTAINER>
201 docker rm <DGBUILDER_DOCKER_CONTAINER>
203 - NOTE: To get a feel of how the deployment is actually performed, it
204 is best to review the Docker Strategy of APPC and look at the actual
207 Other Useful Docker Commands
208 ----------------------------
210 - The commands below are useful to test or troubleshoot in case a
211 change in the gitlab code breaks a clean APPC deployment:
215 # Check current docker-compose logs generated during 'docker-compose up' process:
216 docker-compose logs # add -f to display logs in real time
218 # Check out docker container's current details
219 docker inspect <DOCKER_CONTAINER>
221 # Verbose output during docker-compose commands
222 docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
224 # Check previous docker volumes
227 # Delete previous docker volume(s)
228 docker volume rm <DOCKER_VOL_ID_1> <DOCKER_VOL_ID_2> ... <DOCKER_VOL_ID_N>
233 A Heat template that can be used on RackSpace to spin up the APPC Host
234 VM as well as the other ONAP Components is available in gitlab. This
235 template would orchestrate the deployment of all ONAP components, which
236 will trigger docker instantiation techniques to start up the containers
237 (either standard docker or docker-compose - depending on how the
238 component's containers get spun up).
240 Validating APPC Installation
241 ============================
243 First of all, APPC Features come in the form of Karaf Features (an
244 ODL-OpenDaylight package) which can be composed of one or more OSGI
245 bundles. These features get installed in the ODL framework in order to
246 be used and installed in the APPC Docker Container (NOTE: SDN-C Core
247 Features also get installed since APPC docker image uses the SDN-C Core
248 docker image as a base image).
250 Accessing docker containers
251 ---------------------------
253 The following command is used to log in / access the docker containers:
257 docker exec -it <DOCKER_CONTAINER> bash
259 Checking if APPC Features are installed successfully
260 ----------------------------------------------------
262 The following commands are used to check if the APPC (and SDN-C) Bundles
263 and Features have been installed correctly in ODL (make sure to enter
264 the APPC Docker Container shell session):
268 # All commands are done inside the appc docker container
270 # Enter the ODL Karaf Console
271 cd /opt/opendaylight/current/bin
274 # Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
275 feature:list | grep appc # filter appc features only
276 feature:list | grep sdnc # filter sdn-c features only
278 # Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
279 bundle:list | grep appc # filter appc bundles only
280 bundle:list | grep sdnc # grep sdn-c bundles only
282 # Check reason why bundle failed to load
283 bundle:diag | grep <BUNDLE_NAME>
285 Accessing the API Explorer
286 --------------------------
288 The API Explorer is a GUI provided by OpenDaylight Open Source
289 Framework. This GUI is very useful to send API calls from APIs that are
290 either developed by APPC or SDN-C frameworks. In order to make these
291 REST calls, some APIs use the
292 `RESTCONF <http://sdntutorials.com/what-is-restconf/>`__ protocol to
295 Currently, the APIs that have a Directed Graph (DG) mapped to it are the
296 ones that can be tested which are the SDN-C APIs and APPC
297 "appc-provider" APIs (LCM APIs will be available to test in later
300 In order to access this GUI, you need to go to the following website
301 which will prompt for ODL user credentials in order to authenticate
302 (more details on generic API Explorer
303 `here <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer>`__):
305 - http://localhost:8282/apidoc/explorer/index.html (change localhost to
306 your VM's public IP).
308 APPC Configuration Model
309 ========================
311 APPC Configuration model involves using "default.properties" files
312 (which are usually located in each of the APPC Features -
313 ..//src//resources/org/onap/appc/default.properties) for APPC
314 Feature that have default (or null) property values inside the core APPC
315 code. These default (or null) properties should be overwritten in the
316 properties file called "appc.properties" located in the APPC Deployment
317 code (../installation/src/main/appc-properties/appc.properties).
319 Each APPC component depends on the property values that are defined for
320 them in order to function properly. For example, the APPC Feature
321 "appc-rest-adapter" located in the APPC Core repo is used to listen to
322 events that are being sent and received in the form of DMaaP Messages
323 through a DMaaP Server Instance (which is usually defined as a RESTful
324 API Layer over the Apache Kafka Framework). The properties for this
325 feature need to be defined to point to the right DMaaP set of events to
326 make sure that we are sending and receiving the proper messages on
329 Currently, there are two ways to change properties for APPC Features:
331 - **Permanent Change**: In appc.properties, change property values as
332 needed and commit changes in your current git repo where your APPC
333 Deployment code repo is at. Then, run your Jenkins job that deploys
334 the APPC Docker Image (make sure the Jenkins Job configuration points
335 to the branch where you just commited the properties change) to make
336 sure that APPC Docker Image contains latest changes of
337 appc.properties from the beginning (of course, the Host VM where the
338 docker containers will be deployed at needs to update images with
339 "docker-compose pull" to pick up the changes you just committed and
341 - **Temporary Change (for quick testing/debugging)**: In the APPC
342 Docker Container, find the appc.properties file in
343 /opt/onap/appc/properties/appc.properties and make changes as
344 needed. Then, restart the APPC Docker Container by running "docker
345 stop " then "docker start ") (NOTE: This approach will lose all
346 changes done in appc.properties if the docker container is destroyed
352 - For more information on a current list of available properties for
353 APPC Features, please go to README.md located in the installation
354 directory path of the APPC Deployment Code.
355 - More documentation can be found on the ONAP Wiki's `APPC
356 Documentation Page <https://wiki.onap.org/display/DW/Controllers>`__
357 and in ONAP's `Read the
358 docs <http://onap.readthedocs.io/en/latest/release/index.html#projects>`__