docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst

   1 .. ============LICENSE_START==========================================
   2 .. ===================================================================
   3 .. Copyright © 2017-2020 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
  18 ==========================
  19 APPC Deployment Guidelines
  20 ==========================
  21
  22 Introduction
  23 ============
  24
  25 The Application Controller (APPC) is one of the components in the ONAP
  26 Platform. Its main function is to perform functions to control the
  27 lifecycle of Virtual Functions (VNFs) as well as the components that
  28 make up these functions. Therefore, this allows the cloud to be
  29 abstracted from Virtual Functions in order to enable repeatable actions,
  30 as well as enabling automation and a dynamic configuration approach.
  31
  32 ONAP APPC is delivered either as as a Kubernetes based Cloud Native
  33 deployment or as an OpenStack deployment with **4 Docker Containers**,
  34 which are deployed using Docker Images already containing the APPC
  35 Framework Suite.
  36
  37 Deployment Mode for APPC
  38 ========================
  39
  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.
  43
  44 Deploying APPC
  45 ==============
  46
  47 Appc runs on a series of Docker containers. In production, these Docker
  48 containers are run as part of a Kubernetes cluster using Helm charts,
  49 but the Docker containers can be brought up without using Kubernetes
  50 (using docker-compose), for the purposes of testing.
  51
  52 APPC Docker Containers
  53 ----------------------
  54
  55 Pre-built ONAP APPC docker images are stored on the LF Nexus 3 server
  56 (nexus3.onap.org). Snapshot docker images contain snapshot versions of
  57 appc components. They are updated daily. These can be found in the
  58 snapshots repository on Nexus 3. The release docker images contain only
  59 released versions of appc components, and once a release docker image is
  60 created, it will not change. These can be found in the releases repository
  61 of Nexus 3.
  62
  63 The following Docker images are the actual deployment images used for
  64 running APPC:
  65
  66 -  **APPC Container**: This Docker container carries the APPC Core
  67    Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and
  68    APPC specific features). This image is built on top of the SDN-C
  69    Docker Image, which contains core features (such as dblib as the
  70    Database Connector, SLI - the Service Logic Interpreter, and the
  71    Active & Available Inventory (A&AI) Listener). Some of these
  72    inherited SDN-C features/artifacts are necessary dependencies to
  73    build and compile APPC features/artifacts.
  74 -  **APPC CDT Container**: This docker container hosts the CDT front-end
  75    gui using nodejs. The artifacts that are contained in this docker container
  76    come from the appc/cdt repository.
  77 -  **Maria DB Container (Version 10.1.11)**: This is the database for APPC.
  78    It’s made by the original developers of MySQL and guaranteed to stay
  79    open source.
  80 -  **Ansible Server Container**: This ansible server is for VNF owner
  81    to write playbook using APPC to send LCM API command.
  82 -  **Node Red / DGBuilder**: This container has the visual tool used to
  83    assemble DGs in order to put together flows or services used to serve
  84    Virtual Functions. NOTE: This container is deployed using a Docker
  85    Image that is managed and supported by the SDN-C component.
  86
  87 Running APPC Containers
  88 =======================
  89
  90 The following steps are needed to deploy and start ONAP APPC:
  91
  92 Preparing your Docker environment
  93 ---------------------------------
  94
  95 -  The VM where APPC will be started needs to have Docker Engine and
  96    Docker-Compose installed (instructions on how to set Docker Engine
  97    can be found
  98    `here <https://docs.docker.com/engine/installation/>`__).
  99
 100 -  The Nexus repository certificate must be added to the
 101    /usr/local/share/ca-certificates/ path
 102
 103 -  You must login to the Nexus repository using this command:
 104
 105    .. code:: bash
 106
 107        docker login nexus3.onap.org:10001
 108
 109 Downloading the Docker Compose File
 110 ----------------------------------
 111
 112 The docker-compose file is needed to setup and start the docker containers.
 113 This file, "docker-compose.yml", is located in the "docker-compose"
 114 directory of the appc/deployment repository.
 115
 116 You can clone this repository to your docker host:
 117
 118 .. code:: bash
 119
 120     git clone "https://gerrit.onap.org/r/appc/deployment"
 121
 122 Downloading the APPC Docker Images
 123 ----------------------------------
 124
 125 Several images need to be dowloaded from nexus for the full appc install:
 126 appc-image, appc-cdt-image, ccsdk-dgbuilder-image, and ccsdk-ansible-server-image.
 127
 128 The command to pull an image is:
 129
 130 .. code:: bash
 131
 132     docker pull nexus3.onap.org:10001/onap/<image name>:<image version>
 133
 134     You can find the versions of the images that you want to download in Nexus,
 135     then download them with the above command.
 136
 137 Re-Tagging the Docker Images
 138 ----------------------------
 139
 140 The docker images that you downloaded from nexus will need to be re-tagged to match
 141 the image names that the docker-compose file is looking for. If you open the
 142 docker-compose.yml file, you'll see the image names, for example "onap/appc-image:latest".
 143
 144 First, check the list of images you have downloaded:
 145
 146 .. code:: bash
 147
 148     docker images
 149
 150 Find the version of the image you want to tag in the output and note the image id. Run this command to tag
 151 that image. In this example, we are tagging a version of the "appc-image".
 152
 153 .. code:: bash
 154
 155     docker tag <image-id> onap/appc-image:latest
 156
 157 Repeat this process for the other images in the docker-compose file that you want to bring up.
 158
 159 Starting the Docker Containers
 160 ------------------------------
 161
 162 In order to run docker-compose commands, you need to be in the same directory that your
 163 docker-compose.yml is located in.
 164
 165 In order to create and start the appc Docker containers, run this command:
 166
 167 .. code:: bash
 168
 169     docker-compose up -d
 170
 171 You can see the status of all Docker containers on your host with this:
 172
 173 .. code:: bash
 174
 175     docker ps -a
 176
 177 You can check the progress of the appc container start-up by viewing the Docker logs:
 178
 179 .. code:: bash
 180
 181     docker-compose logs
 182
 183 When you see "Total Appc install took:" in the log, the appc install has finished.
 184
 185 Stopping the Docker Containers
 186 ------------------------------
 187
 188 A Docker container can be stopped with this command:
 189
 190 .. code:: bash
 191
 192     docker stop <container name or id>
 193
 194 The container can be deleted with this command:
 195
 196 .. code:: bash
 197
 198     docker rm -v <container name or id>
 199
 200 (make sure you use the -v parameter or the volume will not be removed)
 201
 202
 203 Other Useful Docker Management Commands
 204 ---------------------------------------
 205
 206 .. code:: bash
 207
 208     # Check out docker container's current details
 209     docker inspect <DOCKER_CONTAINER>
 210
 211     # Verbose output during docker-compose commands
 212     docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
 213
 214     #Stop all running docker containers
 215     docker ps | while read a b c d e f g; do docker stop $a; done
 216
 217     #Remove all docker containers (but not the images you have downloaded)
 218     docker ps -a | while read a b c d e f g; do docker rm -v $a; done
 219
 220
 221 ONAP Heat Template
 222 ------------------
 223
 224 A Heat template that can be used on RackSpace to spin up the APPC Host
 225 VM as well as the other ONAP Components is available in gitlab. This
 226 template would orchestrate the deployment of all ONAP components, which
 227 will trigger docker instantiation techniques to start up the containers
 228 (either standard docker or docker-compose - depending on how the
 229 component's containers get spun up).
 230
 231 Validating APPC Installation
 232 ============================
 233
 234 The Appc application runs as a series of OSGI features and bundles in Opendaylight on the
 235 Appc docker container. You can confirm that Appc installed by making sure these features
 236 show up in the Opendaylight console.
 237
 238 Accessing docker containers
 239 ---------------------------
 240
 241 The following command is used to log in / access the Appc Docker container and start a shell session:
 242
 243 .. code:: bash
 244
 245     docker exec -it appc_controller_container bash
 246
 247 Checking if APPC Features are installed successfully
 248 ----------------------------------------------------
 249
 250 The following commands are used to check if the APPC Bundles
 251 and Features have been installed correctly in ODL (make sure to enter
 252 the APPC Docker Container shell session first):
 253
 254 .. code:: bash
 255
 256     # All commands are done inside the appc docker container
 257
 258     # Enter the ODL Karaf Console
 259     /opt/opendaylight/current/bin/client
 260
 261     # Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
 262     feature:list | grep appc # filter appc features only
 263
 264     # Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
 265     bundle:list | grep appc # filter appc bundles only
 266
 267     # Check reason why bundle failed to load
 268     bundle:diag <bundle id>
 269
 270 Accessing the API Explorer
 271 --------------------------
 272
 273 The API Explorer is a GUI provided by OpenDaylight Open Source
 274 Framework. This GUI is very useful to send API calls from APIs that are
 275 either developed by APPC or SDN-C frameworks. In order to make these
 276 REST calls, some APIs use the
 277 `RESTCONF <http://sdntutorials.com/what-is-restconf/>`__ protocol to
 278 make such calls.
 279
 280 In order to access this GUI, you need to go to the following website
 281 which will prompt for ODL user credentials in order to authenticate
 282 (more details on generic API Explorer
 283 `here <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer>`__):
 284
 285 -  http://localhost:8282/apidoc/explorer/index.html (localhost can be replaced with the ip of your
 286    Docker host, if it is not on localhost).
 287
 288 APPC Configuration Model
 289 ========================
 290
 291 APPC Configuration model involves using "default.properties" files
 292 (which are usually located in each of the APPC Features -
 293 ..//src//resources/org/onap/appc/default.properties) for APPC
 294 Feature that have default (or null) property values inside the core APPC
 295 code. These default (or null) properties should be overwritten in the
 296 properties file called "appc.properties" located in the APPC Deployment
 297 code (../installation/src/main/appc-properties/appc.properties).
 298
 299 Each APPC component depends on the property values that are defined for
 300 them in order to function properly. For example, the APPC Feature
 301 "appc-rest-adapter" located in the APPC Core repo is used to listen to
 302 events that are being sent and received in the form of DMaaP Messages
 303 through a DMaaP Server Instance (which is usually defined as a RESTful
 304 API Layer over the Apache Kafka Framework). The properties for this
 305 feature need to be defined to point to the right DMaaP set of events to
 306 make sure that we are sending and receiving the proper messages on
 307 DMaaP.
 308
 309 Temporary changes to the appc.properties file can be made by entering the Appc
 310 Docker container and modifying the /opt/onap/appc/properties/appc.properties file.
 311 Then, from outside the Docker container, you should stop and then restart the Appc
 312 Docker container with these commands:
 313
 314 .. code:: bash
 315
 316     docker stop appc_controller_container
 317
 318     docker stop appc_controller_container
 319
 320
 321 Additional Notes
 322 ================
 323
 324 -  For more information on a current list of available properties for
 325    APPC Features, please go to README.md located in the installation
 326    directory path of the APPC Deployment Code.
 327 -  More documentation can be found on the ONAP Wiki's `APPC
 328    Documentation Page <https://wiki.onap.org/display/DW/Controllers>`__
 329    and in ONAP's `Read the
 330    docs <http://onap.readthedocs.io/en/latest/release/index.html#projects>`__
 331    documentation site.