tools/debug/charmed/README.md

   1 <!--
   2  Copyright 2020 Canonical Ltd.
   3
   4  Licensed under the Apache License, Version 2.0 (the "License");
   5  you may not use this file except in compliance with the License.
   6  You may obtain a copy of the License at
   7
   8      http://www.apache.org/licenses/LICENSE-2.0
   9
  10  Unless required by applicable law or agreed to in writing, software
  11  distributed under the License is distributed on an "AS IS" BASIS,
  12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  See the License for the specific language governing permissions and
  14  limitations under the License.
  15
  16  For those usages not covered by the Apache License, Version 2.0 please
  17  contact: legal@canonical.com
  18
  19  To get in touch with the maintainers, please contact:
  20  osm-charmers@lists.launchpad.net
  21 -->
  22
  23 # Debugging Charmed OSM
  24
  25 This document aims to provide the OSM community an easy way of testing and debugging OSM.
  26
  27 Benefits:
  28
  29 - Use upstream published images for debugging: No need to build local images anymore.
  30 - Easily configure modules for debugging_mode: `juju config <module> debug_mode=True debug_pubkey="ssh-rsa ..."`.
  31 - Debug in K8s: All pods (the debugged ones and the rest) will be running always in K8s.
  32 - Seemless setup: VSCode will connect through SSH to the pods.
  33
  34 ## Install OSM
  35
  36 Download the installer:
  37
  38 ```bash
  39 wget http://osm-download.etsi.org/ftp/osm-10.0-ten/install_osm.sh
  40 chmod +x install_osm.sh
  41 ```
  42
  43 Install OSM from master (tag=testing-daily):
  44
  45 ```bash
  46 ./install_osm.sh -R testing-daily -r testing --charmed
  47 ```
  48
  49 Install OSM from a specific tag:
  50
  51 ```bash
  52 ./install_osm.sh -R testing-daily -r testing --charmed --tag <X.Y.Z>
  53 ```
  54
  55 ## Debugging
  56
  57 Once the Charmed OSM installation has finished, you can select which applications you want to run with the debug mode.
  58
  59 - lcm: `juju config lcm debug_mode=True  debug_pubkey="ssh-rsa ..."`
  60 - mon: `juju config mon debug_mode=True debug_pubkey="ssh-rsa ..."`
  61 - nbi: `juju config nbi debug_mode=True debug_pubkey="ssh-rsa ..."`
  62 - ro: `juju config ro debug_mode=True debug_pubkey="ssh-rsa ..."`
  63 - pol: `juju config pol debug_mode=True debug_pubkey="ssh-rsa ..."`
  64
  65 Enabling the debug_mode will put a `sleep infinity` as the entrypoint of the container. That way, we can later connect to the pod through SSH in VSCode, and run the entrypoint of the application from the debugger.
  66
  67 ### Prepare pods
  68
  69 Preparing the pods includes setting up the ~/.ssh/config so the VSCode can easily discover which ssh hosts are available
  70
  71 Just execute:
  72
  73 ```bash
  74 ./prepare_pods.sh
  75 ```
  76
  77 > NOTE: The public key that will be used will be `$HOME/.ssh/id_rsa.pub`. If you want to use a different one, add the absolute path to it as a first argument: `./prepare_pods.sh /path/to/key.pub`.
  78
  79 ### Connect to Pods
  80
  81 In VScode, navigate to [Remote Explorer](https://code.visualstudio.com/docs/remote/ssh#_remember-hosts-and-advanced-settings), and select the pod to which you want to connect.
  82
  83 You should be able to see the following hosts in the Remote Explorer:
  84
  85 - lcm
  86 - mon
  87 - nbi
  88 - ro
  89 - pol
  90
  91 Right click on the host, and "Connect to host in a New Window".
  92
  93 ### Add workspace
  94
  95 The `./prepare_pods.sh` script adds a workspace to the `/root` folder of each pod, with the following name: `<module>.code-workspace`.
  96
  97 In the window of the connected host, go to `File/Open Workspace...`. Then select the `<module>.code-workspace` file.
  98
  99 ### Run and Debug
 100
 101 Go to extensions and install the Python extension. It will be installed in the remote pod.
 102
 103 Now we need to add a [debug configuration](https://code.visualstudio.com/docs/editor/debugging). For that, go to the Run and Debug tab, and click on `create a launch.json file`.
 104
 105 Now you will be asked to select a folder in your workspace. Select the folder of the main component:
 106
 107 - LCM: select osm_lcm
 108 - MON: select osm_mon
 109 - NBI: select osm_nbi
 110 - RO: select osm_ng_ro
 111 - POL: select osm_policy_module
 112
 113 Then select `Python` as the environment. And finally, select `Module` and enter the module of the component you are going to test (LCM example: osm_lcm.lcm)