diff options
author | Hector Anapan <ha076r@att.com> | 2017-09-27 06:29:20 -0400 |
---|---|---|
committer | Patrick Brady <pb071s@att.com> | 2017-09-28 16:21:50 +0000 |
commit | 62f41bfdbadc5c95127dde47ee357f3c828ead9a (patch) | |
tree | c8dba548fc2b9f0e0ffe1d5bddc219f5c88f2bb0 /docs/APPC Deployment Guidelines | |
parent | fa2d3bfe48df6619c2960159d2b1e90d73f41798 (diff) |
Add APPC Deployment Documentation
This will take care of adding the following RST documentation files:
- The README in the appc git repo so that it is also available in HTML form
- The documentation found on wiki to build and test APPC in a local environment.
Change-Id: Iea7153bd077b60c7ae40da423e1a154de97ce390
Signed-off-by: Hector Anapan <ha076r@att.com>
Issue-Id: APPC-247
Diffstat (limited to 'docs/APPC Deployment Guidelines')
-rw-r--r-- | docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst b/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst new file mode 100644 index 0000000..ffbbc1e --- /dev/null +++ b/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst @@ -0,0 +1,338 @@ +========================== +APPC Deployment Guidelines +========================== + +Introduction +============ + +The Application Controller (APPC) is one of the components in the ONAP +Platform. Its main function is to perform functions to control the +lifecycle of Virtual Functions (VNFs) as well as the components that +make up these functions. Therefore, this allows the cloud to be +abstracted from Virtual Functions in order to enable repeatable actions, +as well as enabling automation and a dynamic configuration approach. + +ONAP APPC is delivered with **3 Docker Containers**, which are deployed +using Docker Images already containing the APPC Framework Suite. NOTE: +All three containers are hosted on Ubuntu 14.04 LTS OS. + +Deployment Mode for APPC +======================== + +The docker containers described above are set up to be deployed on the +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 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.openecomp.appc.\*) compiled and packaged in the "appc" git +repository. + +The following Docker images are the actual deployment images used for +running APPC: + +- **APPC Container**: This Docker container carries the APPC Core + Framework (OpenDaylight, Karaf, OSGI Bundles, ODL Functions/APIs, and + APPC specific features). This image is built on top of the SDN-C + Docker Image, which contains core features (such as dblib as the + Database Connector, SLI - the Service Logic Interpreter, and the + Active & Available Inventory (A&AI) Listener). Some of these + inherited SDN-C features/artifacts are necessary dependencies to + build and compile APPC features/artifacts. +- **MySQL DB Container (Version 5.6)**: This is the database for APPC. + It is currently using MySQL Community Version (Open-Source version). +- **Node Red / DGBuilder**: This container has the visual tool used to + assemble DGs in order to put together flows or services used to serve + Virtual Functions. NOTE: This container is deployed using a Docker + Image that is managed and supported by the SDN-C component. + +Starting APPC +============= + +Ther following steps are needed to deploy and start ONAP APPC: + +Requirement to Pre-Define properties before compiling APPC: +----------------------------------------------------------- + +- The following maven properties are not defined by default, since they + change based on where the platform is being deployed: + + - ${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. + +Using Jenkins Jobs to set up APPC Package +----------------------------------------- + +- A Jenkins instance for ONAP is required, in which Jenkins Jobs for + both the APPC core code and deployment code are maintained. + +- 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. + +- 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. + + - 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. + +- 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. + +Using Docker to start APPC Package +---------------------------------- + +- 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): + +.. code:: bash + + # Install Docker-Compose + apt-get install python-pip + pip install docker-compose + + # 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 + + # 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> + + # Pull latest version of Docker Images + docker-compose pull + + # Deploy Containers + docker-compose up # add -d argument to start process as a daemon (background process) + +Using Docker to stop APPC Package +--------------------------------- + +- The following steps are required to stop the APPC package: + +.. code:: bash + + # Stop and Destroy Docker Containers (with docker-compose YAML script) + docker-compose down + + # Stop Docker Containers (without docker-compose YAML script) + docker stop <APPC_DOCKER_CONTAINER> + docker stop <MYSQL_DOCKER_CONTAINER> + docker stop <DGBUILDER_DOCKER_CONTAINER> + + # Destroy Docker Containers (without docker-compose YAML script) + docker rm <APPC_DOCKER_CONTAINER> + docker rm <MYSQL_DOCKER_CONTAINER> + docker rm <DGBUILDER_DOCKER_CONTAINER> + +- 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. + +Other Useful Docker Commands +---------------------------- + +- The commands below are useful to test or troubleshoot in case a + change in the gitlab code breaks a clean APPC deployment: + +.. code:: bash + + # Check current docker-compose logs generated during 'docker-compose up' process: + docker-compose logs # add -f to display logs in real time + + # Check out docker container's current details + docker inspect <DOCKER_CONTAINER> + + # Verbose output during docker-compose commands + docker-compose --verbose <DOCKER_COMPOSE_CMD_ARG> + + # 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 +------------------ + +A Heat template that can be used on RackSpace to spin up the APPC Host +VM as well as the other ONAP Components is available in gitlab. This +template would orchestrate the deployment of all ONAP components, which +will trigger docker instantiation techniques to start up the containers +(either standard docker or docker-compose - depending on how the +component's containers get spun up). + +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). + +Accessing docker containers +--------------------------- + +The following command is used to log in / access the docker containers: + +.. code:: bash + + docker exec -it <DOCKER_CONTAINER> bash + +Checking if APPC Features are installed successfully +---------------------------------------------------- + +The following commands are used to check if the APPC (and SDN-C) Bundles +and Features have been installed correctly in ODL (make sure to enter +the APPC Docker Container shell session): + +.. code:: bash + + # All commands are done inside the appc docker container + + # Enter the ODL Karaf Console + cd /opt/opendaylight/current/bin + ./client -u karaf + + # 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> + +Accessing the API Explorer +-------------------------- + +The API Explorer is a GUI provided by OpenDaylight Open Source +Framework. This GUI is very useful to send API calls from APIs that are +either developed by APPC or SDN-C frameworks. In order to make these +REST calls, some APIs use the +`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). + +APPC Configuration Model +======================== + +APPC Configuration model involves using "default.properties" files +(which are usually located in each of the APPC Features - +..//src//resources/org/openecomp/appc/default.properties) for APPC +Feature that have default (or null) property values inside the core APPC +code. These default (or null) properties should be overwritten in the +properties file called "appc.properties" located in the APPC Deployment +code (../installation/src/main/appc-properties/appc.properties). + +Each APPC component depends on the property values that are defined for +them in order to function properly. For example, the APPC Feature +"appc-rest-adapter" located in the APPC Core repo is used to listen to +events that are being sent and received in the form of DMaaP Messages +through a DMaaP Server Instance (which is usually defined as a RESTful +API Layer over the Apache Kafka Framework). The properties for this +feature need to be defined to point to the right DMaaP set of events to +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/openecomp/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). + +Additional Notes +================ + +- For more information on a current list of available properties for + APPC Features, please go to README.md located in the installation + directory path of the APPC Deployment Code. +- More documentation can be found on the ONAP Wiki's `APPC + Documentation Page <https://wiki.onap.org/display/DW/Controllers>`__ + and in ONAP's `Read the + docs <http://onap.readthedocs.io/en/latest/release/index.html#projects>`__ + documentation site. |