docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst

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