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 either as as a Kubernetes based Cloud Native
34 deployment or as an OpenStack deployment with **4 Docker Containers**,
35 which are deployed using Docker Images already containing the APPC
36 Framework Suite. NOTE: Containers are hosted on Ubuntu 16.04 LTS OS.
38 Deployment Mode for APPC
39 ========================
41 The docker containers described above are set up to be deployed on the
42 same Virtual Machine. **Docker Compose** is Docker's deployment tool
43 that allows to configure and deploy multiple containers at once.
45 Compiling and Building APPC
46 ===========================
48 APPC (structured as a Maven project) uses the Maven tool to help
49 compile, build, and deploy APPC Artifacts (usually made up of Java
50 packages) into a Maven Repository. In order to compile and build APPC, a
51 ``mvn clean install`` is executed, which checks for any errors and Java
52 exceptions during compilation process.
57 In order to deploy APPC, a Docker-ready machine needs to be available in
58 order to deploy the APPC Docker Containers. The following will help
59 explain the requirements in order to run Docker to deploy these
62 APPC Docker Containers
63 ----------------------
65 ONAP APPC docker images are currently stored on the Rackspace Nexus
66 Docker Registry (Maven Repository). The deployment code can be found in
67 the Maven Project that builds and deploys the Docker Images to be
68 deployed in the Nexus Repository (current approach is by using Jenkins).
69 These Docker Images are composed of the APPC Artifacts
70 (org.onap.appc.\*) compiled and packaged in the "appc" git
73 The following Docker images are the actual deployment images used for
76 - **APPC Container**: This Docker container carries the APPC Core
77 Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and
78 APPC specific features). This image is built on top of the SDN-C
79 Docker Image, which contains core features (such as dblib as the
80 Database Connector, SLI - the Service Logic Interpreter, and the
81 Active & Available Inventory (A&AI) Listener). Some of these
82 inherited SDN-C features/artifacts are necessary dependencies to
83 build and compile APPC features/artifacts.
84 - **Maria DB Container (Version 10.1.11)**: This is the database for APPC.
85 It’s made by the original developers of MySQL and guaranteed to stay
87 - **Ansible Server Container**: This ansible server is for VNF owner
88 to write playbook using APPC to send LCM API command.
89 - **Node Red / DGBuilder**: This container has the visual tool used to
90 assemble DGs in order to put together flows or services used to serve
91 Virtual Functions. NOTE: This container is deployed using a Docker
92 Image that is managed and supported by the SDN-C component.
97 Ther following steps are needed to deploy and start ONAP APPC:
99 Requirement to Pre-Define properties before compiling APPC:
100 -----------------------------------------------------------
102 - The following maven properties are not defined by default, since they
103 change based on where the platform is being deployed:
105 - ${openecomp.nexus.url}: URL of the Nexus Repository where APPC
107 - ${openecomp.nexus.port}: Port number of the Nexus Repository where
109 - ${openecomp.nexus.user}: Username ID of the Nexus Repository where
111 - ${openecomp.nexus.password}: Password of the Nexus Repository
112 where APPC Code is at.
114 Using Jenkins Jobs to set up APPC Package
115 -----------------------------------------
117 - A Jenkins instance for ONAP is required, in which Jenkins Jobs for
118 both the APPC core code and deployment code are maintained.
120 - Jenkins Job for APPC Core git project: The Jenkins Job for the APPC
121 git repository (Core Component) is in charge of compiling and
122 uploading/deploying successfully compiled maven APPC artifacts into a
123 Nexus/Maven Repository.
125 - Jenkins Job for APPC Deployment git project: The Jenkins Job is used
126 to run the APPC Deployment code which ultimately builds and deploy
127 the APPC Docker Image. Once the Jenkins job runs successfully, the
128 newly compiled images are uploaded to the Nexus Repository. The APPC
129 Docker image contains all the SDN-C and APPC artifacts needed to
130 deploy a successful APPC Component.
132 - With this job, all required and newly compiled and uploaded (to
133 Nexus Repository) APPC features from the Jenkins job are pulled
134 into the images and installed in an automated fashion.
136 - As explained in the "APPC Docker Containers" section, the
137 configuration and set up of the other two docker containers are not
138 maintained by APPC. MySQL Docker Image is maintained by the Open
139 Source MySQL Community and the Node Red / DGBuilder Docker Image is
142 Using Docker to start APPC Package
143 ----------------------------------
145 - The VM where APPC will be started needs to have Docker Engine and
146 Docker-Compose installed (instructions on how to set Docker Engine
148 `here <https://docs.docker.com/engine/installation/>`__). The stable
149 version of Docker Engine where APPC has been tested to work is v1.12.
150 An important requirement in order to access the Docker Image
151 Repository on Nexus Repository (where docker images are currently
152 stored) need to include the Nexus repository certificate imported in
153 the host VM. This is needed for Docker to be able to access the
154 Docker Images required (NOTE: MySQL Docker Image is obtained from the
157 - NOTE ON "docker-compose" COMMANDS: The only work if there is a
158 provided docker-compose YAML script in the cmd path
160 - In order to deploy containers, the following steps need to be taken
161 in your host VM (Assuming instructions on how to set up Docker Engine
162 have already been done):
166 # Install Docker-Compose
167 apt-get install python-pip
168 pip install docker-compose
170 # 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):
171 docker login <DOCKER_REGISTRY_REPO> # prompts for user credentials as a way to authenticate
173 # Pull latest version of Docker Images (separately)
174 docker pull <APPC_DOCKER_IMAGE_URL>
175 docker pull mysql/mysql-server:5.6 # Default Open-Source MySQL Docker Image
176 docker pull <SDNC_DOCKER_IMAGE_URL>
178 # Pull latest version of Docker Images
182 docker-compose up # add -d argument to start process as a daemon (background process)
184 Using Docker to stop APPC Package
185 ---------------------------------
187 - The following steps are required to stop the APPC package:
191 # Stop and Destroy Docker Containers (with docker-compose YAML script)
194 # Stop Docker Containers (without docker-compose YAML script)
195 docker stop <APPC_DOCKER_CONTAINER>
196 docker stop <MYSQL_DOCKER_CONTAINER>
197 docker stop <DGBUILDER_DOCKER_CONTAINER>
199 # Destroy Docker Containers (without docker-compose YAML script)
200 docker rm <APPC_DOCKER_CONTAINER>
201 docker rm <MYSQL_DOCKER_CONTAINER>
202 docker rm <DGBUILDER_DOCKER_CONTAINER>
204 - NOTE: To get a feel of how the deployment is actually performed, it
205 is best to review the Docker Strategy of APPC and look at the actual
208 Other Useful Docker Commands
209 ----------------------------
211 - The commands below are useful to test or troubleshoot in case a
212 change in the gitlab code breaks a clean APPC deployment:
216 # Check current docker-compose logs generated during 'docker-compose up' process:
217 docker-compose logs # add -f to display logs in real time
219 # Check out docker container's current details
220 docker inspect <DOCKER_CONTAINER>
222 # Verbose output during docker-compose commands
223 docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
225 # Check previous docker volumes
228 # Delete previous docker volume(s)
229 docker volume rm <DOCKER_VOL_ID_1> <DOCKER_VOL_ID_2> ... <DOCKER_VOL_ID_N>
234 A Heat template that can be used on RackSpace to spin up the APPC Host
235 VM as well as the other ONAP Components is available in gitlab. This
236 template would orchestrate the deployment of all ONAP components, which
237 will trigger docker instantiation techniques to start up the containers
238 (either standard docker or docker-compose - depending on how the
239 component's containers get spun up).
241 Validating APPC Installation
242 ============================
244 First of all, APPC Features come in the form of Karaf Features (an
245 ODL-OpenDaylight package) which can be composed of one or more OSGI
246 bundles. These features get installed in the ODL framework in order to
247 be used and installed in the APPC Docker Container (NOTE: SDN-C Core
248 Features also get installed since APPC docker image uses the SDN-C Core
249 docker image as a base image).
251 Accessing docker containers
252 ---------------------------
254 The following command is used to log in / access the docker containers:
258 docker exec -it <DOCKER_CONTAINER> bash
260 Checking if APPC Features are installed successfully
261 ----------------------------------------------------
263 The following commands are used to check if the APPC (and SDN-C) Bundles
264 and Features have been installed correctly in ODL (make sure to enter
265 the APPC Docker Container shell session):
269 # All commands are done inside the appc docker container
271 # Enter the ODL Karaf Console
272 cd /opt/opendaylight/current/bin
275 # Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
276 feature:list | grep appc # filter appc features only
277 feature:list | grep sdnc # filter sdn-c features only
279 # Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
280 bundle:list | grep appc # filter appc bundles only
281 bundle:list | grep sdnc # grep sdn-c bundles only
283 # Check reason why bundle failed to load
284 bundle:diag | grep <BUNDLE_NAME>
286 Accessing the API Explorer
287 --------------------------
289 The API Explorer is a GUI provided by OpenDaylight Open Source
290 Framework. This GUI is very useful to send API calls from APIs that are
291 either developed by APPC or SDN-C frameworks. In order to make these
292 REST calls, some APIs use the
293 `RESTCONF <http://sdntutorials.com/what-is-restconf/>`__ protocol to
296 Currently, the APIs that have a Directed Graph (DG) mapped to it are the
297 ones that can be tested which are the SDN-C APIs and APPC
298 "appc-provider" APIs (LCM APIs will be available to test in later
301 In order to access this GUI, you need to go to the following website
302 which will prompt for ODL user credentials in order to authenticate
303 (more details on generic API Explorer
304 `here <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer>`__):
306 - http://localhost:8282/apidoc/explorer/index.html (change localhost to
307 your VM's public IP).
309 APPC Configuration Model
310 ========================
312 APPC Configuration model involves using "default.properties" files
313 (which are usually located in each of the APPC Features -
314 ..//src//resources/org/onap/appc/default.properties) for APPC
315 Feature that have default (or null) property values inside the core APPC
316 code. These default (or null) properties should be overwritten in the
317 properties file called "appc.properties" located in the APPC Deployment
318 code (../installation/src/main/appc-properties/appc.properties).
320 Each APPC component depends on the property values that are defined for
321 them in order to function properly. For example, the APPC Feature
322 "appc-rest-adapter" located in the APPC Core repo is used to listen to
323 events that are being sent and received in the form of DMaaP Messages
324 through a DMaaP Server Instance (which is usually defined as a RESTful
325 API Layer over the Apache Kafka Framework). The properties for this
326 feature need to be defined to point to the right DMaaP set of events to
327 make sure that we are sending and receiving the proper messages on
330 Currently, there are two ways to change properties for APPC Features:
332 - **Permanent Change**: In appc.properties, change property values as
333 needed and commit changes in your current git repo where your APPC
334 Deployment code repo is at. Then, run your Jenkins job that deploys
335 the APPC Docker Image (make sure the Jenkins Job configuration points
336 to the branch where you just commited the properties change) to make
337 sure that APPC Docker Image contains latest changes of
338 appc.properties from the beginning (of course, the Host VM where the
339 docker containers will be deployed at needs to update images with
340 "docker-compose pull" to pick up the changes you just committed and
342 - **Temporary Change (for quick testing/debugging)**: In the APPC
343 Docker Container, find the appc.properties file in
344 /opt/onap/appc/properties/appc.properties and make changes as
345 needed. Then, restart the APPC Docker Container by running "docker
346 stop " then "docker start ") (NOTE: This approach will lose all
347 changes done in appc.properties if the docker container is destroyed
353 - For more information on a current list of available properties for
354 APPC Features, please go to README.md located in the installation
355 directory path of the APPC Deployment Code.
356 - More documentation can be found on the ONAP Wiki's `APPC
357 Documentation Page <https://wiki.onap.org/display/DW/Controllers>`__
358 and in ONAP's `Read the
359 docs <http://onap.readthedocs.io/en/latest/release/index.html#projects>`__