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
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.
48 Appc runs on a series of Docker containers. In production, these Docker
49 containers are run as part of a Kubernetes cluster using Helm charts,
50 but the Docker containers can be brought up without using Kubernetes
51 (using docker-compose), for the purposes of testing.
53 APPC Docker Containers
54 ----------------------
56 Pre-built ONAP APPC docker images are stored on the LF Nexus 3 server
57 (nexus3.onap.org). Snapshot docker images contain snapshot versions of
58 appc components. They are updated daily. These can be found in the
59 snapshots repository on Nexus 3. The release docker images contain only
60 released versions of appc components, and once a release docker image is
61 created, it will not change. These can be found in the releases repository
64 The following Docker images are the actual deployment images used for
67 - **APPC Container**: This Docker container carries the APPC Core
68 Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and
69 APPC specific features). This image is built on top of the SDN-C
70 Docker Image, which contains core features (such as dblib as the
71 Database Connector, SLI - the Service Logic Interpreter, and the
72 Active & Available Inventory (A&AI) Listener). Some of these
73 inherited SDN-C features/artifacts are necessary dependencies to
74 build and compile APPC features/artifacts.
75 - **APPC CDT Container**: This docker container hosts the CDT front-end
76 gui using nodejs. The artifacts that are contained in this docker container
77 come from the appc/cdt repository.
78 - **Maria DB Container (Version 10.1.11)**: This is the database for APPC.
79 It’s made by the original developers of MySQL and guaranteed to stay
81 - **Ansible Server Container**: This ansible server is for VNF owner
82 to write playbook using APPC to send LCM API command.
83 - **Node Red / DGBuilder**: This container has the visual tool used to
84 assemble DGs in order to put together flows or services used to serve
85 Virtual Functions. NOTE: This container is deployed using a Docker
86 Image that is managed and supported by the SDN-C component.
88 Running APPC Containers
89 =======================
91 The following steps are needed to deploy and start ONAP APPC:
93 Preparing your Docker environment
94 ---------------------------------
96 - The VM where APPC will be started needs to have Docker Engine and
97 Docker-Compose installed (instructions on how to set Docker Engine
99 `here <https://docs.docker.com/engine/installation/>`__).
101 - The Nexus repository certificate must be added to the
102 /usr/local/share/ca-certificates/ path
104 - You must login to the Nexus repository using this command:
108 docker login nexus3.onap.org:10001
110 Downloading the Docker Compose File
111 ----------------------------------
113 The docker-compose file is needed to setup and start the docker containers.
114 This file, "docker-compose.yml", is located in the "docker-compose"
115 directory of the appc/deployment repository.
117 You can clone this repository to your docker host:
121 git clone "https://gerrit.onap.org/r/appc/deployment"
123 Downloading the APPC Docker Images
124 ----------------------------------
126 Several images need to be dowloaded from nexus for the full appc install:
127 appc-image, appc-cdt-image, ccsdk-dgbuilder-image, and ccsdk-ansible-server-image.
129 The command to pull an image is:
133 docker pull nexus3.onap.org:10001/onap/<image name>:<image version>
135 You can find the versions of the images that you want to download in Nexus,
136 then download them with the above command.
138 Re-Tagging the Docker Images
139 ----------------------------
141 The docker images that you downloaded from nexus will need to be re-tagged to match
142 the image names that the docker-compose file is looking for. If you open the
143 docker-compose.yml file, you'll see the image names, for example "onap/appc-image:latest".
145 First, check the list of images you have downloaded:
151 Find the version of the image you want to tag in the output and note the image id. Run this command to tag
152 that image. In this example, we are tagging a version of the "appc-image".
156 docker tag <image-id> onap/appc-image:latest
158 Repeat this process for the other images in the docker-compose file that you want to bring up.
160 Starting the Docker Containers
161 ------------------------------
163 In order to run docker-compose commands, you need to be in the same directory that your
164 docker-compose.yml is located in.
166 In order to create and start the appc Docker containers, run this command:
172 You can see the status of all Docker containers on your host with this:
178 You can check the progress of the appc container start-up by viewing the Docker logs:
184 When you see "Total Appc install took:" in the log, the appc install has finished.
186 Stopping the Docker Containers
187 ------------------------------
189 A Docker container can be stopped with this command:
193 docker stop <container name or id>
195 The container can be deleted with this command:
199 docker rm -v <container name or id>
201 (make sure you use the -v parameter or the volume will not be removed)
204 Other Useful Docker Management Commands
205 ---------------------------------------
209 # Check out docker container's current details
210 docker inspect <DOCKER_CONTAINER>
212 # Verbose output during docker-compose commands
213 docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
215 #Stop all running docker containers
216 docker ps | while read a b c d e f g; do docker stop $a; done
218 #Remove all docker containers (but not the images you have downloaded)
219 docker ps -a | while read a b c d e f g; do docker rm -v $a; done
225 A Heat template that can be used on RackSpace to spin up the APPC Host
226 VM as well as the other ONAP Components is available in gitlab. This
227 template would orchestrate the deployment of all ONAP components, which
228 will trigger docker instantiation techniques to start up the containers
229 (either standard docker or docker-compose - depending on how the
230 component's containers get spun up).
232 Validating APPC Installation
233 ============================
235 The Appc application runs as a series of OSGI features and bundles in Opendaylight on the
236 Appc docker container. You can confirm that Appc installed by making sure these features
237 show up in the Opendaylight console.
239 Accessing docker containers
240 ---------------------------
242 The following command is used to log in / access the Appc Docker container and start a shell session:
246 docker exec -it appc_controller_container bash
248 Checking if APPC Features are installed successfully
249 ----------------------------------------------------
251 The following commands are used to check if the APPC Bundles
252 and Features have been installed correctly in ODL (make sure to enter
253 the APPC Docker Container shell session first):
257 # All commands are done inside the appc docker container
259 # Enter the ODL Karaf Console
260 /opt/opendaylight/current/bin/client
262 # Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
263 feature:list | grep appc # filter appc features only
265 # Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
266 bundle:list | grep appc # filter appc bundles only
268 # Check reason why bundle failed to load
269 bundle:diag <bundle id>
271 Accessing the API Explorer
272 --------------------------
274 The API Explorer is a GUI provided by OpenDaylight Open Source
275 Framework. This GUI is very useful to send API calls from APIs that are
276 either developed by APPC or SDN-C frameworks. In order to make these
277 REST calls, some APIs use the
278 `RESTCONF <http://sdntutorials.com/what-is-restconf/>`__ protocol to
281 In order to access this GUI, you need to go to the following website
282 which will prompt for ODL user credentials in order to authenticate
283 (more details on generic API Explorer
284 `here <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer>`__):
286 - http://localhost:8282/apidoc/explorer/index.html (localhost can be replaced with the ip of your
287 Docker host, if it is not on localhost).
289 APPC Configuration Model
290 ========================
292 APPC Configuration model involves using "default.properties" files
293 (which are usually located in each of the APPC Features -
294 ..//src//resources/org/onap/appc/default.properties) for APPC
295 Feature that have default (or null) property values inside the core APPC
296 code. These default (or null) properties should be overwritten in the
297 properties file called "appc.properties" located in the APPC Deployment
298 code (../installation/src/main/appc-properties/appc.properties).
300 Each APPC component depends on the property values that are defined for
301 them in order to function properly. For example, the APPC Feature
302 "appc-rest-adapter" located in the APPC Core repo is used to listen to
303 events that are being sent and received in the form of DMaaP Messages
304 through a DMaaP Server Instance (which is usually defined as a RESTful
305 API Layer over the Apache Kafka Framework). The properties for this
306 feature need to be defined to point to the right DMaaP set of events to
307 make sure that we are sending and receiving the proper messages on
310 Temporary changes to the appc.properties file can be made by entering the Appc
311 Docker container and modifying the /opt/onap/appc/properties/appc.properties file.
312 Then, from outside the Docker container, you should stop and then restart the Appc
313 Docker container with these commands:
317 docker stop appc_controller_container
319 docker stop appc_controller_container
325 - For more information on a current list of available properties for
326 APPC Features, please go to README.md located in the installation
327 directory path of the APPC Deployment Code.
328 - More documentation can be found on the ONAP Wiki's `APPC
329 Documentation Page <https://wiki.onap.org/display/DW/Controllers>`__
330 and in ONAP's `Read the
331 docs <http://onap.readthedocs.io/en/latest/release/index.html#projects>`__