diff --git a/02-developer-how-to.md b/02-developer-how-to.md index 673088a6e3d84863c2019ff4c820f1fad2340abf..baada27a0621def1eaec4fb498ecce2918c6af83 100644 --- a/02-developer-how-to.md +++ b/02-developer-how-to.md @@ -1,10 +1,15 @@ # How to configure your environment to develop with OSM -The aim of this chapter is to provide a guide for developers to set up their environment, in order to ease the development with the different OSM modules. +The aim of this chapter is to provide a guide for developers to set up their environment, in order to ease the development with the different OSM modules in the local environment to ease debugging (rather than using a Docker container). + +Alternatively, a modified code can be tested by building a new Docker image with the code under test and apply it to the Docker container. These links explain how to do it: + +- For Docker Swarm: +- For Kubernetes: ## Introduction -Modules run in separate docker containers (except juju controller that uses a lxd container). Current installation uses Docker Swarm by default, but Kubernetes is also available as an option of the installer (with the switch `-c k8s`). The modules are: +Modules run in separate Docker containers (except juju controller that uses a lxd container). Current installation uses Docker Swarm by default, but Kubernetes is also available as an option of the installer (with the switch `-c k8s`). The modules are: - **kafka**: Provides a Kafka bus used for OSM communication. This module relies on *zookeeper*. - **zookeeper**: Used by *kafka*. @@ -19,7 +24,7 @@ Modules run in separate docker containers (except juju controller that uses a lx - **pol**: Policy Manager for OSM. - **prometheus**: for monitoring . -In addition LCM and NBI, shares a common file system where packages are stored. For Docker Swarm it uses a shared docker volume called *osm_package*. For Kubernetes it uses the host mount path */var/lib/osm/osm/osm_osm_packages/_data*. +In addition LCM and NBI, shares a common file system where packages are stored. For Docker Swarm it uses a shared Docker volume called *osm_package*. For Kubernetes it uses the host mount path */var/lib/osm/osm/osm_osm_packages/_data*. This picture shows the modules with the port that they export, their relationships with the name of env variables that control them. For clarity not all the dependencies are depicted, as kafka, mysql, ... @@ -58,7 +63,7 @@ For debugging it is convenient running the target module directly at host mainta ### 1 Shutdown the container you want to debug -First thing, you need to stop the module you want to debug. As OSM uses a docker service do not manually stop the container because it will be automatically relaunched again. Scale it to 0 for stopping and to 1 for running again. +First thing, you need to stop the module you want to debug. As OSM uses a Docker service do not manually stop the container because it will be automatically relaunched again. Scale it to 0 for stopping and to 1 for running again. ```bash # For Docker Swarm: @@ -104,15 +109,17 @@ You need to feed the IP addresses of the modules it is going to communicate to. In case the module under development is running in the same server where the rest of the modules are located, use "127.0.0.1" (localhost) as the IP address of those modules. For instance, in the following example we have added mongo, mysql, ro and kafka to the line containing "127.0.0.1": ```text -127.0.0.1 localhost kafka keystone nbi mongo mysql ro +127.0.0.1 localhost kafka kafka-0.kafka.osm.svc.cluster.local keystone nbi mongo mysql ro ``` In case the module under development is running in a different server from the rest of modules, you will need to provide the IP address of that server. For instance, in the following example we have added a new line with the name resolution for mongo ro and kafka to IP address "a.b.c.d": ```text -a.b.c.d kafka keystone nbi mongo mysql ro +a.b.c.d kafka kafka-0.kafka.osm.svc.cluster.local keystone nbi mongo mysql ro ``` +Note: the host 'kafka-0.kafka.osm.svc.cluster.local' is needed only for kubernetes. Check this is the proper name with command `kubectl -n osm exec -ti statefulset/kafka cat /etc/hosts` + ### 6 Install needed packages Is it possible that you will need to install some additional packages in your server. If needed use the commands `python3 -m pip install` or `apt-get install` for that. @@ -131,7 +138,7 @@ python3 -m pip install -e N2VC --user # needed for LCM python3 -m pip install IM --user -U # needed for NBI and RO. Option -e does not work ``` -### 7 Expose needed ports of docker services +### 7 Expose needed ports of Docker services #### Expose services for Docker Swarm @@ -147,7 +154,7 @@ docker service update osm_ro --publish-add 9090:9090 docker service list ``` -Alternatively you can modify the docker osm stack by editing file `/etc/osm/docker/docker-compose.yaml`, adding/uncommenting the exposed ports; and restart the stack: +Alternatively you can modify the Docker osm stack by editing file `/etc/osm/docker/docker-compose.yaml`, adding/uncommenting the exposed ports; and restart the stack: ```bash sudo vi /etc/osm/docker/docker-compose.yaml @@ -164,7 +171,7 @@ docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm #### Expose services for Kubernetes -Download file 'debug_k8s_services.yaml' from . Optionally remove sections not needed and apply it. +Download file 'debug_k8s_services.yaml' from . Optionally remove sections not needed and apply it with: ```bash kubectl -n osm apply -f debug_k8s_services.yaml @@ -189,7 +196,7 @@ docker service update osm_light-ui --force --env-add "OSM_SERVER=172.17.0.1" # Get the needed address at your setup by 'ip a | grep docker0' ``` -- ... Or edit file `/etc/osm/docker/docker-compose.yaml`, and set at `light-ui` section the required IP address from docker to the VM: +- ... Or edit file `/etc/osm/docker/docker-compose.yaml`, and set at `light-ui` section the required IP address from Docker to the VM: ```text OSM_SERVER: <172.17.0.1> # nbi @@ -212,7 +219,7 @@ kubectl -n osm patch deployment light-ui --patch '{"spec": {"template": {"spec": Clone and install needed IM and NBI packages. ```bash -# Install Information Model IM +# Install Information Model IM git clone https://osm.etsi.org/gerrit/osm/IM python3 -m pip install IM --user @@ -230,15 +237,15 @@ Environment variables: - `OSMNBI_DATABASE_COMMONKEY`: must be the same value used by NBI. Get it with `cat /etc/osm/docker/nbi.env` or `kubectl -n osm exec -ti deployment/nbi env`. - `OSMNBI_AUTHENTICATION_SERVICE_PASSWORD`: obtain in the same way as before -- `OSMNBI_STORAGE_PATH`: Path of the docker volume for file storage. Both LCM and NBI must share the same path. You can either: +- `OSMNBI_STORAGE_PATH`: Path of the Docker volume for file storage. Both LCM and NBI must share the same path. You can either: - Create a folder and debug both NBI and LCM at the same time (needed if you develop in a different server than OSM); or - - Use the docker volume. + - Use the Docker volume. - For Docker Swarm discover local path (mount point) with `docker volume inspect osm_osm_packages` and grant write permissions to pycharm on it with (path can be different at your environment) `sudo chmod o+rx /var/lib/docker /var/lib/docker/volumes; sudo chmod -R o+w /var/lib/docker/volumes/osm_osm_packages/_data`. - For Kubernetes use path: '/var/lib/osm/osm/osm_osm_packages/_data'. Exec `sudo chmod -R o+w /var/lib/osm/osm/osm_osm_packages/_data` - `OSMNBI_DATABASE_HOST`: Mongo IP in case host `mongo` is not at `/etc/hosts` file - `OSMNBI_STATIC_DIR`: `/osm_nbi/html_public` -Finally remove running docker service. +Finally remove running Docker service. For Docker Swarm exec `docker service scale osm_nbi=0`; scale to 1 to undo. For Kubernetes: ```bash @@ -250,7 +257,7 @@ kubectl -n osm delete service/nbi ## LCM -Ensure services for **mongo** and **kafka** expose their ports. See [Developer_HowTo - Expose needed ports of docker services](02-developer-how-to.md#7-expose-needed-ports-of-docker-services) +Ensure services for **mongo** and **kafka** expose their ports. See [Developer_HowTo - Expose needed ports of Docker services](02-developer-how-to.md#7-expose-needed-ports-of-docker-services) Install needed OSM packages if you intend to modify develop them: @@ -282,10 +289,10 @@ Environment variables: Values are stored at `/etc/osm/docker/lcm.env` but here it is explained how to obtain these values. -- `OSMLCM_DATABASE_COMMONKEY`: must be the same value used by NBI. Get it with `cat /etc/osm/docker/nbi.env` or `kubectl -n osm exec -ti deployment/nbi env`. -- `OSMLCM_STORAGE_PATH`: Path of the docker volume for file storage. Both LCM and NBI must share the same path. You can either: +- `OSMLCM_DATABASE_COMMONKEY`: must be the same value used by NBI. Get it with `cat /etc/osm/docker/lcm.env` or `kubectl -n osm exec -ti deployment/lcm env`. +- `OSMLCM_STORAGE_PATH`: Path of the Docker volume for file storage. Both LCM and NBI must share the same path. You can either: - Create a folder and debug both NBI and LCM at the same time (needed if you develop in a different server than OSM); or - - Use the docker volume. + - Use the Docker volume. - For Docker Swarm discover local path (mount point) with `docker volume inspect osm_osm_packages` and grant write permissions to pycharm on it with (path can be different at your environment) `sudo chmod o+rx /var/lib/docker /var/lib/docker/volumes; sudo chmod -R o+w /var/lib/docker/volumes/osm_osm_packages/_data`. - For Kubernetes use path: '/var/lib/osm/osm/osm_osm_packages/_data'. Exec `sudo chmod -R o+w /var/lib/osm/osm/osm_osm_packages/_data` - `OSMLCM_DATABASE_HOST`: Mongo IP in case 'mongo' host it is not at `/etc/hosts` file. See [Developer_HowTo#5 Configure it to interact with other modules](02-developer-how-to.md#5-configure-it-to-interact-with-other-modules) @@ -306,20 +313,20 @@ Values are stored at `/etc/osm/docker/lcm.env` but here it is explained how to o - `ssh -L 0.0.0.0:17070::17070 root@` - `OSMLCM_GLOBAL_LOGLEVEL`: DEBUG -Finally remove running docker service. +Finally remove running Docker service. -- For Docker Swarm exec `docker service scale osm_lcm=0`, and scale to 1 to undo. -- For Kubernetes run `kubectl -n osm scale deployment lcm --replicas=0`, and scale to 1 to undo +- For Docker Swarm exec `docker service scale osm_lcm=0`. To undo just scale it to 1. +- For Kubernetes run `kubectl -n osm scale deployment lcm --replicas=0`. to undo just scale it to 1. ## RO Ensure services for **mysql** exposes its port. See [Developer_HowTo - Expose needed ports of docker services](02-developer-how-to.md#7-expose-needed-ports-of-docker-services) -Additionally you may want that docker `lcm` uses your local copy of RO. +Additionally you may want that Docker `lcm` uses your local copy of RO. -For Docker Swarmit can be done by one of: +For Docker Swarm, it can be done by one of: -- Modify docker service +- Modify Docker service ```bash docker service update osm_lcm --env-add OSMLCM_RO_HOST=172.17.0.1 @@ -327,7 +334,7 @@ For Docker Swarmit can be done by one of: ip a | grep docker0 ``` -- Edit file `/etc/osm/docker/docker-compose.yaml`, and set at `lcm` section the required IP address from docker to the VM (Restart stack afterwards): +- Edit file `/etc/osm/docker/docker-compose.yaml`, and set at `lcm` section the required IP address from Docker to the VM (Restart stack afterwards): ```yaml OSMLCM_RO_HOST: 172.17.0.1 # ro @@ -400,7 +407,7 @@ Environment variables: - `RO_DB_HOST`, `RO_DB_OVIM_HOST`: `mysql` or `` depending if running on the same server or not. - `RO_LOG_LEVEL`: `DEBUG` -Finally remove running docker service. +Finally remove running Docker service. For Docker Swarm, exec `docker service scale osm_ro=0`, and scale to 1 to undo.