From 61045ca3584a8e948eebd4218763c36db44c2e0b Mon Sep 17 00:00:00 2001 From: Patrick Brady Date: Sun, 19 Apr 2020 23:31:42 -0700 Subject: [PATCH] Docs: Update to deployment guidelines Updating the deployment guidelines document so that it matches the current deployment process. Change-Id: I9e8edb38046c6e5f9e9e9a342c6edd962a4047bd Signed-off-by: Patrick Brady Issue-ID: APPC-1863 --- .../APPC Deployment Guidelines.rst | 290 ++++++++++----------- 1 file changed, 131 insertions(+), 159 deletions(-) diff --git a/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst b/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst index d9d9cbe..ed30dd1 100644 --- a/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst +++ b/docs/APPC Deployment Guidelines/APPC Deployment Guidelines.rst @@ -33,7 +33,7 @@ as well as enabling automation and a dynamic configuration approach. 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 ======================== @@ -42,33 +42,24 @@ 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 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: @@ -81,6 +72,9 @@ 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. @@ -91,142 +85,139 @@ running APPC: 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 `__). + +- 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 `__). 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/: + + 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 # 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 - docker pull mysql/mysql-server:5.6 # Default Open-Source MySQL Docker Image - docker pull +.. code:: bash - # Pull latest version of Docker Images - docker-compose pull + docker tag 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 - docker stop - docker stop +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 - docker rm - docker rm +.. 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 + +The container can be deleted with this command: + +.. code:: bash + + docker rm -v + +(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 # Verbose output during docker-compose commands docker-compose --verbose + + #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 ... ONAP Heat Template ------------------ @@ -241,47 +232,41 @@ 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). +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 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:diag Accessing the API Explorer -------------------------- @@ -293,18 +278,13 @@ REST calls, some APIs use the `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 `__): -- 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 ======================== @@ -327,25 +307,17 @@ 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/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 ================ -- 2.16.6