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 - Keep your changes save: Possibility to mount local module to the container; all the changes will be saved automatically to your local filesystem.
  34
  35 ## Install OSM
  36
  37 Download the installer:
  38
  39 ```bash
  40 wget http://osm-download.etsi.org/ftp/osm-10.0-ten/install_osm.sh
  41 chmod +x install_osm.sh
  42 ```
  43
  44 Install OSM from master (tag=testing-daily):
  45
  46 ```bash
  47 ./install_osm.sh -R testing-daily -r testing --charmed
  48 ```
  49
  50 Install OSM from a specific tag:
  51
  52 ```bash
  53 ./install_osm.sh -R testing-daily -r testing --charmed --tag <X.Y.Z>
  54 ```
  55
  56 ## Debugging
  57
  58 Once the Charmed OSM installation has finished, you can select which applications you want to run with the debug mode.
  59
  60 ```bash
  61 # LCM
  62 juju config lcm debug_mode=True  debug_pubkey="`cat ~/.ssh/id_rsa.pub`"
  63 # MON
  64 juju config mon debug_mode=True  debug_pubkey="`cat ~/.ssh/id_rsa.pub`"
  65 # NBI
  66 juju config nbi debug_mode=True  debug_pubkey="`cat ~/.ssh/id_rsa.pub`"
  67 # RO
  68 juju config ro debug_mode=True  debug_pubkey="`cat ~/.ssh/id_rsa.pub`"
  69 # POL
  70 juju config pol debug_mode=True  debug_pubkey="`cat ~/.ssh/id_rsa.pub`"
  71 ```
  72
  73 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.
  74
  75 ### Mounting local modules
  76
  77 The Charmed OSM Debugging mode allows you to mount local modules to the desired charms. The following commands show which modules can be mounted in each charm.
  78
  79 ```bash
  80 LCM_LOCAL_PATH="/path/to/LCM"
  81 N2VC_LOCAL_PATH="/path/to/N2VC"
  82 NBI_LOCAL_PATH="/path/to/NBI"
  83 RO_LOCAL_PATH="/path/to/RO"
  84 MON_LOCAL_PATH="/path/to/MON"
  85 POL_LOCAL_PATH="/path/to/POL"
  86 COMMON_LOCAL_PATH="/path/to/common"
  87
  88 # LCM
  89 juju config lcm debug_lcm_local_path=$LCM_LOCAL_PATH
  90 juju config lcm debug_n2vc_local_path=$N2VC_LOCAL_PATH
  91 juju config lcm debug_common_local_path=$COMMON_LOCAL_PATH
  92 # MON
  93 juju config mon debug_mon_local_path=$MON_LOCAL_PATH
  94 juju config mon debug_n2vc_local_path=$N2VC_LOCAL_PATH
  95 juju config mon debug_common_local_path=$COMMON_LOCAL_PATH
  96 # NBI
  97 juju config nbi debug_nbi_local_path=$LCM_LOCAL_PATH
  98 juju config nbi debug_common_local_path=$COMMON_LOCAL_PATH
  99 # RO
 100 juju config ro debug_ro_local_path=$RO_LOCAL_PATH
 101 juju config ro debug_common_local_path=$COMMON_LOCAL_PATH
 102 # POL
 103 juju config pol debug_pol_local_path=$POL_LOCAL_PATH
 104 juju config pol debug_common_local_path=$COMMON_LOCAL_PATH
 105 ```
 106
 107 ### Generate SSH config file
 108
 109 Preparing the pods includes setting up the `~/.ssh/config` so the VSCode can easily discover which ssh hosts are available
 110
 111 Just execute:
 112
 113 ```bash
 114 ./generate_ssh_config.sh
 115 ```
 116
 117 > 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: `./generate_ssh_config.sh /path/to/key.pub`.
 118
 119 ### Connect to Pods
 120
 121 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.
 122
 123 You should be able to see the following hosts in the Remote Explorer:
 124
 125 - lcm
 126 - mon
 127 - nbi
 128 - ro
 129 - pol
 130
 131 Right click on the host, and "Connect to host in a New Window".
 132
 133 ### Add workspace
 134
 135 The `./generate_ssh_config.sh` script adds a workspace to the `/root` folder of each pod, with the following name: `debug.code-workspace`.
 136
 137 In the window of the connected host, go to `File/Open Workspace from File...`. Then select the `debug.code-workspace` file.
 138
 139 ### Run and Debug
 140
 141 Open the `Terminal` tab, and the Python extension will be automatically downloaded. It will be installed in the remote pod.
 142
 143 Go to the `Explorer (ctrl + shift + E)` to see the module folders in the charm. You can add breakpoints and start debugging.
 144
 145 Go to the `Run and Debug (ctrl + shift + D)` and press `F5` to start the main entrypoint of the charm.
 146
 147 Happy debugging!