ONAP APPC is delivered either as as a Kubernetes based Cloud Native
deployment or as an OpenStack deployment with **4 Docker Containers**,
which are deployed using Docker Images already containing the APPC
-Framework Suite. NOTE: Containers are hosted on Ubuntu 16.04 LTS OS.
+Framework Suite.
Deployment Mode for APPC
========================
same Virtual Machine. **Docker Compose** is Docker's deployment tool
that allows to configure and deploy multiple containers at once.
-Compiling and Building APPC
-===========================
-
-APPC (structured as a Maven project) uses the Maven tool to help
-compile, build, and deploy APPC Artifacts (usually made up of Java
-packages) into a Maven Repository. In order to compile and build APPC, a
-``mvn clean install`` is executed, which checks for any errors and Java
-exceptions during compilation process.
-
Deploying APPC
==============
-In order to deploy APPC, a Docker-ready machine needs to be available in
-order to deploy the APPC Docker Containers. The following will help
-explain the requirements in order to run Docker to deploy these
-containers.
+Appc runs on a series of Docker containers. In production, these Docker
+containers are run as part of a Kubernetes cluster using Helm charts,
+but the Docker containers can be brought up without using Kubernetes
+(using docker-compose), for the purposes of testing.
APPC Docker Containers
----------------------
-ONAP APPC docker images are currently stored on the Rackspace Nexus
-Docker Registry (Maven Repository). The deployment code can be found in
-the Maven Project that builds and deploys the Docker Images to be
-deployed in the Nexus Repository (current approach is by using Jenkins).
-These Docker Images are composed of the APPC Artifacts
-(org.onap.appc.\*) compiled and packaged in the "appc" git
-repository.
+Pre-built ONAP APPC docker images are stored on the LF Nexus 3 server
+(nexus3.onap.org). Snapshot docker images contain snapshot versions of
+appc components. They are updated daily. These can be found in the
+snapshots repository on Nexus 3. The release docker images contain only
+released versions of appc components, and once a release docker image is
+created, it will not change. These can be found in the releases repository
+of Nexus 3.
The following Docker images are the actual deployment images used for
running APPC:
Active & Available Inventory (A&AI) Listener). Some of these
inherited SDN-C features/artifacts are necessary dependencies to
build and compile APPC features/artifacts.
+- **APPC CDT Container**: This docker container hosts the CDT front-end
+ gui using nodejs. The artifacts that are contained in this docker container
+ come from the appc/cdt repository.
- **Maria DB Container (Version 10.1.11)**: This is the database for APPC.
It’s made by the original developers of MySQL and guaranteed to stay
open source.
Virtual Functions. NOTE: This container is deployed using a Docker
Image that is managed and supported by the SDN-C component.
-Starting APPC
-=============
+Running APPC Containers
+=======================
-Ther following steps are needed to deploy and start ONAP APPC:
+The following steps are needed to deploy and start ONAP APPC:
-Requirement to Pre-Define properties before compiling APPC:
------------------------------------------------------------
+Preparing your Docker environment
+---------------------------------
-- The following maven properties are not defined by default, since they
- change based on where the platform is being deployed:
+- The VM where APPC will be started needs to have Docker Engine and
+ Docker-Compose installed (instructions on how to set Docker Engine
+ can be found
+ `here <https://docs.docker.com/engine/installation/>`__).
+
+- The Nexus repository certificate must be added to the
+ /usr/local/share/ca-certificates/ path
+
+- You must login to the Nexus repository using this command:
+
+ .. code:: bash
+
+ docker login nexus3.onap.org:10001
+
+Downloading the Docker Compose File
+----------------------------------
- - ${openecomp.nexus.url}: URL of the Nexus Repository where APPC
- Code is at.
- - ${openecomp.nexus.port}: Port number of the Nexus Repository where
- APPC Code is at.
- - ${openecomp.nexus.user}: Username ID of the Nexus Repository where
- APPC Code is at.
- - ${openecomp.nexus.password}: Password of the Nexus Repository
- where APPC Code is at.
+The docker-compose file is needed to setup and start the docker containers.
+This file, "docker-compose.yml", is located in the "docker-compose"
+directory of the appc/deployment repository.
-Using Jenkins Jobs to set up APPC Package
------------------------------------------
+You can clone this repository to your docker host:
-- A Jenkins instance for ONAP is required, in which Jenkins Jobs for
- both the APPC core code and deployment code are maintained.
+.. code:: bash
-- Jenkins Job for APPC Core git project: The Jenkins Job for the APPC
- git repository (Core Component) is in charge of compiling and
- uploading/deploying successfully compiled maven APPC artifacts into a
- Nexus/Maven Repository.
+ git clone "https://gerrit.onap.org/r/appc/deployment"
-- Jenkins Job for APPC Deployment git project: The Jenkins Job is used
- to run the APPC Deployment code which ultimately builds and deploy
- the APPC Docker Image. Once the Jenkins job runs successfully, the
- newly compiled images are uploaded to the Nexus Repository. The APPC
- Docker image contains all the SDN-C and APPC artifacts needed to
- deploy a successful APPC Component.
+Downloading the APPC Docker Images
+----------------------------------
- - With this job, all required and newly compiled and uploaded (to
- Nexus Repository) APPC features from the Jenkins job are pulled
- into the images and installed in an automated fashion.
+Several images need to be dowloaded from nexus for the full appc install:
+appc-image, appc-cdt-image, ccsdk-dgbuilder-image, and ccsdk-ansible-server-image.
-- As explained in the "APPC Docker Containers" section, the
- configuration and set up of the other two docker containers are not
- maintained by APPC. MySQL Docker Image is maintained by the Open
- Source MySQL Community and the Node Red / DGBuilder Docker Image is
- maintained by SDN-C.
+The command to pull an image is:
-Using Docker to start APPC Package
-----------------------------------
+.. code:: bash
-- The VM where APPC will be started needs to have Docker Engine and
- Docker-Compose installed (instructions on how to set Docker Engine
- can be found
- `here <https://docs.docker.com/engine/installation/>`__). The stable
- version of Docker Engine where APPC has been tested to work is v1.12.
- An important requirement in order to access the Docker Image
- Repository on Nexus Repository (where docker images are currently
- stored) need to include the Nexus repository certificate imported in
- the host VM. This is needed for Docker to be able to access the
- Docker Images required (NOTE: MySQL Docker Image is obtained from the
- public Docker Hub).
-
-- NOTE ON "docker-compose" COMMANDS: The only work if there is a
- provided docker-compose YAML script in the cmd path
-
-- In order to deploy containers, the following steps need to be taken
- in your host VM (Assuming instructions on how to set up Docker Engine
- have already been done):
+ docker pull nexus3.onap.org:10001/onap/<image name>:<image version>
+
+ You can find the versions of the images that you want to download in Nexus,
+ then download them with the above command.
+
+Re-Tagging the Docker Images
+----------------------------
+
+The docker images that you downloaded from nexus will need to be re-tagged to match
+the image names that the docker-compose file is looking for. If you open the
+docker-compose.yml file, you'll see the image names, for example "onap/appc-image:latest".
+
+First, check the list of images you have downloaded:
.. code:: bash
- # Install Docker-Compose
- apt-get install python-pip
- pip install docker-compose
+ docker images
- # 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):
- docker login <DOCKER_REGISTRY_REPO> # prompts for user credentials as a way to authenticate
+Find the version of the image you want to tag in the output and note the image id. Run this command to tag
+that image. In this example, we are tagging a version of the "appc-image".
- # Pull latest version of Docker Images (separately)
- docker pull <APPC_DOCKER_IMAGE_URL>
- docker pull mysql/mysql-server:5.6 # Default Open-Source MySQL Docker Image
- docker pull <SDNC_DOCKER_IMAGE_URL>
+.. code:: bash
- # Pull latest version of Docker Images
- docker-compose pull
+ docker tag <image-id> onap/appc-image:latest
- # Deploy Containers
- docker-compose up # add -d argument to start process as a daemon (background process)
+Repeat this process for the other images in the docker-compose file that you want to bring up.
-Using Docker to stop APPC Package
----------------------------------
+Starting the Docker Containers
+------------------------------
+
+In order to run docker-compose commands, you need to be in the same directory that your
+docker-compose.yml is located in.
+
+In order to create and start the appc Docker containers, run this command:
-- The following steps are required to stop the APPC package:
+.. code:: bash
+
+ docker-compose up -d
+
+You can see the status of all Docker containers on your host with this:
.. code:: bash
- # Stop and Destroy Docker Containers (with docker-compose YAML script)
- docker-compose down
+ docker ps -a
- # Stop Docker Containers (without docker-compose YAML script)
- docker stop <APPC_DOCKER_CONTAINER>
- docker stop <MYSQL_DOCKER_CONTAINER>
- docker stop <DGBUILDER_DOCKER_CONTAINER>
+You can check the progress of the appc container start-up by viewing the Docker logs:
- # Destroy Docker Containers (without docker-compose YAML script)
- docker rm <APPC_DOCKER_CONTAINER>
- docker rm <MYSQL_DOCKER_CONTAINER>
- docker rm <DGBUILDER_DOCKER_CONTAINER>
+.. code:: bash
-- NOTE: To get a feel of how the deployment is actually performed, it
- is best to review the Docker Strategy of APPC and look at the actual
- Jenkins Jobs.
+ docker-compose logs
-Other Useful Docker Commands
-----------------------------
+When you see "Total Appc install took:" in the log, the appc install has finished.
+
+Stopping the Docker Containers
+------------------------------
-- The commands below are useful to test or troubleshoot in case a
- change in the gitlab code breaks a clean APPC deployment:
+A Docker container can be stopped with this command:
.. code:: bash
- # Check current docker-compose logs generated during 'docker-compose up' process:
- docker-compose logs # add -f to display logs in real time
+ docker stop <container name or id>
+
+The container can be deleted with this command:
+
+.. code:: bash
+
+ docker rm -v <container name or id>
+
+(make sure you use the -v parameter or the volume will not be removed)
+
+
+Other Useful Docker Management Commands
+---------------------------------------
+
+.. code:: bash
# Check out docker container's current details
docker inspect <DOCKER_CONTAINER>
# Verbose output during docker-compose commands
docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG>
+
+ #Stop all running docker containers
+ docker ps | while read a b c d e f g; do docker stop $a; done
+
+ #Remove all docker containers (but not the images you have downloaded)
+ docker ps -a | while read a b c d e f g; do docker rm -v $a; done
- # Check previous docker volumes
- docker volume ls
-
- # Delete previous docker volume(s)
- docker volume rm <DOCKER_VOL_ID_1> <DOCKER_VOL_ID_2> ... <DOCKER_VOL_ID_N>
ONAP Heat Template
------------------
Validating APPC Installation
============================
-First of all, APPC Features come in the form of Karaf Features (an
-ODL-OpenDaylight package) which can be composed of one or more OSGI
-bundles. These features get installed in the ODL framework in order to
-be used and installed in the APPC Docker Container (NOTE: SDN-C Core
-Features also get installed since APPC docker image uses the SDN-C Core
-docker image as a base image).
+The Appc application runs as a series of OSGI features and bundles in Opendaylight on the
+Appc docker container. You can confirm that Appc installed by making sure these features
+show up in the Opendaylight console.
Accessing docker containers
---------------------------
-The following command is used to log in / access the docker containers:
+The following command is used to log in / access the Appc Docker container and start a shell session:
.. code:: bash
- docker exec -it <DOCKER_CONTAINER> bash
+ docker exec -it appc_controller_container bash
Checking if APPC Features are installed successfully
----------------------------------------------------
-The following commands are used to check if the APPC (and SDN-C) Bundles
+The following commands are used to check if the APPC Bundles
and Features have been installed correctly in ODL (make sure to enter
-the APPC Docker Container shell session):
+the APPC Docker Container shell session first):
.. code:: bash
# All commands are done inside the appc docker container
# Enter the ODL Karaf Console
- cd /opt/opendaylight/current/bin
- ./client -u karaf
+ /opt/opendaylight/current/bin/client
# Check if features have been installed or not (the ones with an 'X' in the "Installed" column have been successfully installed)
feature:list | grep appc # filter appc features only
- feature:list | grep sdnc # filter sdn-c features only
# Check if bundles have been loaded successfully (the ones with 'Active' in the "State" column have been successfully loaded)
bundle:list | grep appc # filter appc bundles only
- bundle:list | grep sdnc # grep sdn-c bundles only
# Check reason why bundle failed to load
- bundle:diag | grep <BUNDLE_NAME>
+ bundle:diag <bundle id>
Accessing the API Explorer
--------------------------
`RESTCONF <http://sdntutorials.com/what-is-restconf/>`__ protocol to
make such calls.
-Currently, the APIs that have a Directed Graph (DG) mapped to it are the
-ones that can be tested which are the SDN-C APIs and APPC
-"appc-provider" APIs (LCM APIs will be available to test in later
-releases).
-
In order to access this GUI, you need to go to the following website
which will prompt for ODL user credentials in order to authenticate
(more details on generic API Explorer
`here <https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf_API_Explorer>`__):
-- http://localhost:8282/apidoc/explorer/index.html (change localhost to
- your VM's public IP).
+- http://localhost:8282/apidoc/explorer/index.html (localhost can be replaced with the ip of your
+ Docker host, if it is not on localhost).
APPC Configuration Model
========================
make sure that we are sending and receiving the proper messages on
DMaaP.
-Currently, there are two ways to change properties for APPC Features:
-
-- **Permanent Change**: In appc.properties, change property values as
- needed and commit changes in your current git repo where your APPC
- Deployment code repo is at. Then, run your Jenkins job that deploys
- the APPC Docker Image (make sure the Jenkins Job configuration points
- to the branch where you just commited the properties change) to make
- sure that APPC Docker Image contains latest changes of
- appc.properties from the beginning (of course, the Host VM where the
- docker containers will be deployed at needs to update images with
- "docker-compose pull" to pick up the changes you just committed and
- compiled).
-- **Temporary Change (for quick testing/debugging)**: In the APPC
- Docker Container, find the appc.properties file in
- /opt/onap/appc/properties/appc.properties and make changes as
- needed. Then, restart the APPC Docker Container by running "docker
- stop " then "docker start ") (NOTE: This approach will lose all
- changes done in appc.properties if the docker container is destroyed
- instead of stopped).
+Temporary changes to the appc.properties file can be made by entering the Appc
+Docker container and modifying the /opt/onap/appc/properties/appc.properties file.
+Then, from outside the Docker container, you should stop and then restart the Appc
+Docker container with these commands:
+
+.. code:: bash
+
+ docker stop appc_controller_container
+
+ docker stop appc_controller_container
+
Additional Notes
================
Code Review / appc / deployment.git / commitdiff