docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst

   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
   8 ..
   9 ..  https://creativecommons.org/licenses/by/4.0/
  10 ..
  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.
  18
  19 ==========================
  20 APPC Deployment Guidelines
  21 ==========================
  22
  23 Introduction
  24 ============
  25
  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.
  32
  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.
  37
  38 Deployment Mode for APPC
  39 ========================
  40
  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.
  44
  45 Deploying APPC
  46 ==============
  47
  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.
  52
  53 APPC Docker Containers
  54 ----------------------
  55
  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
  62 of Nexus 3.
  63
  64 The following Docker images are the actual deployment images used for
  65 running APPC:
  66
  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
  80    open source.
  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.
  87
  88 Running APPC Containers
  89 =======================
  90
  91 The following steps are needed to deploy and start ONAP APPC:
  92
  93 Preparing your Docker environment
  94 ---------------------------------
  95
  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
  98    can be found
  99    `here <https://docs.docker.com/engine/installation/>`__).
 100
 101 -  The Nexus repository certificate must be added to the
 102    /usr/local/share/ca-certificates/ path
 103
 104 -  You must login to the Nexus repository using this command:
 105
 106    .. code:: bash
 107
 108        docker login nexus3.onap.org:10001
 109
 110 Downloading the Docker Compose File
 111 ----------------------------------
 112
 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.
 116
 117 You can clone this repository to your docker host:
 118
 119 .. code:: bash
 120
 121     git clone "https://gerrit.onap.org/r/appc/deployment"
 122
 123 Downloading the APPC Docker Images
 124 ----------------------------------
 125
 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.
 128
 129 The command to pull an image is:
 130
 131 .. code:: bash
 132
 133     docker pull nexus3.onap.org:10001/onap/<image name>:<image version>
 134
 135     You can find the versions of the images that you want to download in Nexus,
 136     then download them with the above command.
 137
 138 Re-Tagging the Docker Images
 139 ----------------------------
 140
 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".
 144
 145 First, check the list of images you have downloaded:
 146
 147 .. code:: bash
 148
 149     docker images
 150
 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".
 153
 154 .. code:: bash
 155
 156     docker tag <image-id> onap/appc-image:latest
 157
 158 Repeat this process for the other images in the docker-compose file that you want to bring up.
 159
 160 Starting the Docker Containers
 161 ------------------------------
 162
 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.
 165
 166 In order to create and start the appc Docker containers, run this command:
 167
 168 .. code:: bash
 169
 170     docker-compose up -d
 171
 172 You can see the status of all Docker containers on your host with this:
 173
 174 .. code:: bash
 175
 176     docker ps -a
 177
 178 You can check the progress of the appc container start-up by viewing the Docker logs:
 179
 180 .. code:: bash
 181
 182     docker-compose logs
 183
 184 When you see "Total Appc install took:" in the log, the appc install has finished.
 185
 186 Stopping the Docker Containers
 187 ------------------------------
 188
 189 A Docker container can be stopped with this command:
 190
 191 .. code:: bash
 192
 193     docker stop <container name or id>
 194
 195 The container can be deleted with this command:
 196
 197 .. code:: bash
 198
 199     docker rm -v <container name or id>
 200
 201 (make sure you use the -v parameter or the volume will not be removed)
 202
 203
 204 Other Useful Docker Management Commands
 205 ---------------------------------------
 206
 207 .. code:: bash
 208
 209     # Check out docker container's current details
 210     docker inspect <DOCKER_CONTAINER>
 211
 212     # Verbose output during docker-compose commands
 213     docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
 214
 215     #Stop all running docker containers
 216     docker ps | while read a b c d e f g; do docker stop $a; done
 217
 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
 220
 221
 222 ONAP Heat Template
 223 ------------------
 224
 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).
 231
 232 Validating APPC Installation
 233 ============================
 234
 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.
 238
 239 Accessing docker containers
 240 ---------------------------
 241
 242 The following command is used to log in / access the Appc Docker container and start a shell session:
 243
 244 .. code:: bash
 245
 246     docker exec -it appc_controller_container bash
 247
 248 Checking if APPC Features are installed successfully
 249 ----------------------------------------------------
 250
 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):
 254
 255 .. code:: bash
 256
 257     # All commands are done inside the appc docker container
 258
 259     # Enter the ODL Karaf Console
 260     /opt/opendaylight/current/bin/client
 261
 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
 264
 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
 267
 268     # Check reason why bundle failed to load
 269     bundle:diag <bundle id>
 270
 271 Accessing the API Explorer
 272 --------------------------
 273
 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
 279 make such calls.
 280
 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>`__):
 285
 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).
 288
 289 APPC Configuration Model
 290 ========================
 291
 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).
 299
 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
 308 DMaaP.
 309
 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:
 314
 315 .. code:: bash
 316
 317     docker stop appc_controller_container
 318
 319     docker stop appc_controller_container
 320
 321
 322 Additional Notes
 323 ================
 324
 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>`__
 332    documentation site.