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 **3 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.openecomp.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 - **MySQL DB Container (Version 5.6)**: This is the database for APPC.
84 It is currently using MySQL Community Version (Open-Source version).
85 - **Node Red / DGBuilder**: This container has the visual tool used to
86 assemble DGs in order to put together flows or services used to serve
87 Virtual Functions. NOTE: This container is deployed using a Docker
88 Image that is managed and supported by the SDN-C component.
93 Ther following steps are needed to deploy and start ONAP APPC:
95 Requirement to Pre-Define properties before compiling APPC:
96 -----------------------------------------------------------
98 - The following maven properties are not defined by default, since they
99 change based on where the platform is being deployed:
101 - ${openecomp.nexus.url}: URL of the Nexus Repository where APPC
103 - ${openecomp.nexus.port}: Port number of the Nexus Repository where
105 - ${openecomp.nexus.user}: Username ID of the Nexus Repository where
107 - ${openecomp.nexus.password}: Password of the Nexus Repository
108 where APPC Code is at.
110 Using Jenkins Jobs to set up APPC Package
111 -----------------------------------------
113 - A Jenkins instance for ONAP is required, in which Jenkins Jobs for
114 both the APPC core code and deployment code are maintained.
116 - Jenkins Job for APPC Core git project: The Jenkins Job for the APPC
117 git repository (Core Component) is in charge of compiling and
118 uploading/deploying successfully compiled maven APPC artifacts into a
119 Nexus/Maven Repository.
121 - Jenkins Job for APPC Deployment git project: The Jenkins Job is used
122 to run the APPC Deployment code which ultimately builds and deploy
123 the APPC Docker Image. Once the Jenkins job runs successfully, the
124 newly compiled images are uploaded to the Nexus Repository. The APPC
125 Docker image contains all the SDN-C and APPC artifacts needed to
126 deploy a successful APPC Component.
128 - With this job, all required and newly compiled and uploaded (to
129 Nexus Repository) APPC features from the Jenkins job are pulled
130 into the images and installed in an automated fashion.
132 - As explained in the "APPC Docker Containers" section, the
133 configuration and set up of the other two docker containers are not
134 maintained by APPC. MySQL Docker Image is maintained by the Open
135 Source MySQL Community and the Node Red / DGBuilder Docker Image is
138 Using Docker to start APPC Package
139 ----------------------------------
141 - The VM where APPC will be started needs to have Docker Engine and
142 Docker-Compose installed (instructions on how to set Docker Engine
144 `here <https://docs.docker.com/engine/installation/>`__). The stable
145 version of Docker Engine where APPC has been tested to work is v1.12.
146 An important requirement in order to access the Docker Image
147 Repository on Nexus Repository (where docker images are currently
148 stored) need to include the Nexus repository certificate imported in
149 the host VM. This is needed for Docker to be able to access the
150 Docker Images required (NOTE: MySQL Docker Image is obtained from the
153 - NOTE ON "docker-compose" COMMANDS: The only work if there is a
154 provided docker-compose YAML script in the cmd path
156 - In order to deploy containers, the following steps need to be taken
157 in your host VM (Assuming instructions on how to set up Docker Engine
158 have already been done):
162 # Install Docker-Compose
163 apt-get install python-pip
164 pip install docker-compose
166 # 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):
167 docker login <DOCKER_REGISTRY_REPO> # prompts for user credentials as a way to authenticate
169 # Pull latest version of Docker Images (separately)
170 docker pull <APPC_DOCKER_IMAGE_URL>
171 docker pull mysql/mysql-server:5.6 # Default Open-Source MySQL Docker Image
172 docker pull <SDNC_DOCKER_IMAGE_URL>
174 # Pull latest version of Docker Images
178 docker-compose up # add -d argument to start process as a daemon (background process)
180 Using Docker to stop APPC Package
181 ---------------------------------
183 - The following steps are required to stop the APPC package:
187 # Stop and Destroy Docker Containers (with docker-compose YAML script)
190 # Stop Docker Containers (without docker-compose YAML script)
191 docker stop <APPC_DOCKER_CONTAINER>
192 docker stop <MYSQL_DOCKER_CONTAINER>
193 docker stop <DGBUILDER_DOCKER_CONTAINER>
195 # Destroy Docker Containers (without docker-compose YAML script)
196 docker rm <APPC_DOCKER_CONTAINER>
197 docker rm <MYSQL_DOCKER_CONTAINER>
198 docker rm <DGBUILDER_DOCKER_CONTAINER>
200 - NOTE: To get a feel of how the deployment is actually performed, it
201 is best to review the Docker Strategy of APPC and look at the actual
204 Other Useful Docker Commands
205 ----------------------------
207 - The commands below are useful to test or troubleshoot in case a
208 change in the gitlab code breaks a clean APPC deployment:
212 # Check current docker-compose logs generated during 'docker-compose up' process:
213 docker-compose logs # add -f to display logs in real time
215 # Check out docker container's current details
216 docker inspect <DOCKER_CONTAINER>
218 # Verbose output during docker-compose commands
219 docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
221 # Check previous docker volumes
224 # Delete previous docker volume(s)
225 docker volume rm <DOCKER_VOL_ID_1> <DOCKER_VOL_ID_2> ... <DOCKER_VOL_ID_N>
230 A Heat template that can be used on RackSpace to spin up the APPC Host
231 VM as well as the other ONAP Components is available in gitlab. This
232 template would orchestrate the deployment of all ONAP components, which
233 will trigger docker instantiation techniques to start up the containers
234 (either standard docker or docker-compose - depending on how the
235 component's containers get spun up).
237 Validating APPC Installation
238 ============================
240 First of all, APPC Features come in the form of Karaf Features (an
241 ODL-OpenDaylight package) which can be composed of one or more OSGI
242 bundles. These features get installed in the ODL framework in order to
243 be used and installed in the APPC Docker Container (NOTE: SDN-C Core
244 Features also get installed since APPC docker image uses the SDN-C Core
245 docker image as a base image).
247 Accessing docker containers
248 ---------------------------
250 The following command is used to log in / access the docker containers:
254 docker exec -it <DOCKER_CONTAINER> bash
256 Checking if APPC Features are installed successfully
257 ----------------------------------------------------
259 The following commands are used to check if the APPC (and SDN-C) Bundles
260 and Features have been installed correctly in ODL (make sure to enter
261 the APPC Docker Container shell session):
265 # All commands are done inside the appc docker container
267 # Enter the ODL Karaf Console
268 cd /opt/opendaylight/current/bin
271 # Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
272 feature:list | grep appc # filter appc features only
273 feature:list | grep sdnc # filter sdn-c features only
275 # Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
276 bundle:list | grep appc # filter appc bundles only
277 bundle:list | grep sdnc # grep sdn-c bundles only
279 # Check reason why bundle failed to load
280 bundle:diag | grep <BUNDLE_NAME>
282 Accessing the API Explorer
283 --------------------------
285 The API Explorer is a GUI provided by OpenDaylight Open Source
286 Framework. This GUI is very useful to send API calls from APIs that are
287 either developed by APPC or SDN-C frameworks. In order to make these
288 REST calls, some APIs use the
289 `RESTCONF <http://sdntutorials.com/what-is-restconf/>`__ protocol to
292 Currently, the APIs that have a Directed Graph (DG) mapped to it are the
293 ones that can be tested which are the SDN-C APIs and APPC
294 "appc-provider" APIs (LCM APIs will be available to test in later
297 In order to access this GUI, you need to go to the following website
298 which will prompt for ODL user credentials in order to authenticate
299 (more details on generic API Explorer
300 `here <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer>`__):
302 - http://localhost:8282/apidoc/explorer/index.html (change localhost to
303 your VM's public IP).
305 APPC Configuration Model
306 ========================
308 APPC Configuration model involves using "default.properties" files
309 (which are usually located in each of the APPC Features -
310 ..//src//resources/org/openecomp/appc/default.properties) for APPC
311 Feature that have default (or null) property values inside the core APPC
312 code. These default (or null) properties should be overwritten in the
313 properties file called "appc.properties" located in the APPC Deployment
314 code (../installation/src/main/appc-properties/appc.properties).
316 Each APPC component depends on the property values that are defined for
317 them in order to function properly. For example, the APPC Feature
318 "appc-rest-adapter" located in the APPC Core repo is used to listen to
319 events that are being sent and received in the form of DMaaP Messages
320 through a DMaaP Server Instance (which is usually defined as a RESTful
321 API Layer over the Apache Kafka Framework). The properties for this
322 feature need to be defined to point to the right DMaaP set of events to
323 make sure that we are sending and receiving the proper messages on
326 Currently, there are two ways to change properties for APPC Features:
328 - **Permanent Change**: In appc.properties, change property values as
329 needed and commit changes in your current git repo where your APPC
330 Deployment code repo is at. Then, run your Jenkins job that deploys
331 the APPC Docker Image (make sure the Jenkins Job configuration points
332 to the branch where you just commited the properties change) to make
333 sure that APPC Docker Image contains latest changes of
334 appc.properties from the beginning (of course, the Host VM where the
335 docker containers will be deployed at needs to update images with
336 "docker-compose pull" to pick up the changes you just committed and
338 - **Temporary Change (for quick testing/debugging)**: In the APPC
339 Docker Container, find the appc.properties file in
340 /opt/openecomp/appc/properties/appc.properties and make changes as
341 needed. Then, restart the APPC Docker Container by running "docker
342 stop " then "docker start ") (NOTE: This approach will lose all
343 changes done in appc.properties if the docker container is destroyed
349 - For more information on a current list of available properties for
350 APPC Features, please go to README.md located in the installation
351 directory path of the APPC Deployment Code.
352 - More documentation can be found on the ONAP Wiki's `APPC
353 Documentation Page <https://wiki.onap.org/display/DW/Controllers>`__
354 and in ONAP's `Read the
355 docs <http://onap.readthedocs.io/en/latest/release/index.html#projects>`__