From d556c622b15a48e1ba76c529952da511237b5d00 Mon Sep 17 00:00:00 2001 From: Tom Weininger Date: Tue, 8 Mar 2022 11:32:45 +0100 Subject: [PATCH] Documentation updates Minor corrections and update of the remote debugging guide. Change-Id: I0d08aaf4f02f5575f1a68b65ebc16aafad8a0270 --- CONSTITUTION.rst | 7 +- HACKING.rst | 2 + .../contributor/guides/remote-debugger.rst | 147 +++++++++++++++--- doc/source/reference/introduction.rst | 2 +- 4 files changed, 130 insertions(+), 28 deletions(-) diff --git a/CONSTITUTION.rst b/CONSTITUTION.rst index 1ac03f3a60..7a349481fb 100644 --- a/CONSTITUTION.rst +++ b/CONSTITUTION.rst @@ -28,11 +28,12 @@ Note that this does not mean we are against having vendors develop products which can replace some of the components within Octavia. (For example, the Octavia VM images might be replaced by a vendor's proprietary VM image.) Rather, it means that: + * The reference implementation should always be open source and unencumbered. * We are typically not interested in making design compromises in order to work -with a vendor's proprietary product. If a vendor wants to develop a component -for Octavia, then the vendor should bend to Octavia's needs, not the other -way around. + with a vendor's proprietary product. If a vendor wants to develop a component + for Octavia, then the vendor should bend to Octavia's needs, not the other + way around. Octavia is a load balancer for large operators ---------------------------------------------- diff --git a/HACKING.rst b/HACKING.rst index fa4b72c16a..bb18b28f1e 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -61,6 +61,7 @@ either additional knowledge about the state of other components in the Octavia system, advanced logic behind decisions, or otherwise a high degree of intelligence should be done by centralized components (ex. controllers) within the Octavia system. Examples of this might include: + * Generating haproxy configuration files * Managing the lifecycle of Octavia amphorae * Moving a loadbalancer instance from one Octavia amphora to another. @@ -68,6 +69,7 @@ the Octavia system. Examples of this might include: On the other hand, tasks done extremely often, or which entail a significant load on the system should be pushed as far out to the most horizontally scalable components as possible. Examples of this might include: + * Serving actual client requests to end-users (ie. running haproxy) * Monitoring pool members for failure and sending notifications about this * Processing log files diff --git a/doc/source/contributor/guides/remote-debugger.rst b/doc/source/contributor/guides/remote-debugger.rst index 4db07e0f64..d742f5bb16 100644 --- a/doc/source/contributor/guides/remote-debugger.rst +++ b/doc/source/contributor/guides/remote-debugger.rst @@ -27,45 +27,124 @@ Prerequisites Setup ===== -Ensure your OpenStack and IDE environments have the PyDev or ptvsd library -installed. +Both PyCharm Professional edition and Visual Studio Code offer remote debugging +features that can be used for debugging Octavia components. -If you're using PyCharm, you can find it in -*/path/to/pycharm/debug-eggs/pycharm-debug.egg* (Python 2) and -*/path/to/pycharm/debug-eggs/pycharm-debug-py3k.egg* (Python 3). Copy that file -into your OpenStack host and install the library in your Python path: +.. note:: Before running a new Octavia process you should + make sure that processes of that component are no longer running. + You can use ``ps aux`` in order to verify that. -:: +PyCharm +------- - $ sudo easy_install pycharm-debug.egg +.. note:: Remote debugging is a *PyCharm Professional* feature. -If using Visual Studio Code, simply install ptvsd in both environments: +PyCharm offers two ways of debugging remotely [1]_. In general, the +"through a remote interpreter" approach is more convenient and should +be preferred. +On the other hand, the "Python debug server" approach is the only +one that works for debugging the API component (because of uWSGI). +Therefore, this guide will explain both approaches. -:: +Using a remote interpreter +~~~~~~~~~~~~~~~~~~~~~~~~~~ - $ pip install ptvsd +First, configure a remote interpreter for the VM as documented in [2]_. +Adding a deployment configuration with correct path mappings allows +PyCharm to upload local changes to the remote host automatically. -Create a remote debugging configuration in your IDE. In PyCharm, go to *Run -> -Edit Configurations -> Python Remote Debug*. The local host name refers to the -local machine you're running your IDE from and it must be one reachable by your -OpenStack environment. The port can be any available port (e.g. 5678). If the -code on the OpenStack and PyCharm hosts is on different paths (likely), define -a path mapping in the remote debug configuration. +Then, create a new *Run/Debug Configuration* by selecting +*Run -> Edit Configurations...* in the menu bar. +Add a new configuration and make sure +*Module name* is selected instead of *Script path*. Enter the module name of +the Octavia component you want to debug, for instance +``octavia.cmd.octavia_worker``. Additionally, add +``--config-file /etc/octavia/octavia.conf`` to *Parameters*. +Then check whether the right remote Python interpreter +is selected. After you confirm the settings by clicking *OK* you should be +able to run/debug the Octavia component with that new run configuration. -Invoke the debug configuration (*Run -> Debug... -> (config name)*). PyCharm -will begin listening on the specified host and port. +Using a Python debug server +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As mentioned above the "remote interpreter" approach does not work with +*Octavia-API* because that process is managed by uWSGI. Here the +Python debug server approach [3]_ needs to be used. You will need to +install the ``pydevd-pycharm`` via ``pip`` as shown when creating the run/debug +configuration. However, it is not necessary to modify the Python code +in any way because Octavia code is already set up for it to work. Export *DEBUGGER_TYPE*, *DEBUGGER_HOST* and *DEBUGGER_PORT* (host and port of the system running the IDE, respectively), and start the Octavia service you -want to debug. It is recommended to run only one uWSGI process/controller -worker. For example, to debug the Octavia Worker service: - -:: +want to debug. For example, to debug the Octavia API service:: $ export DEBUGGER_TYPE=pydev $ export DEBUGGER_HOST=192.168.121.1 $ export DEBUGGER_PORT=5678 - $ /usr/bin/octavia-worker --config-file /etc/octavia/octavia.conf + $ uwsgi --ini /etc/octavia/octavia-uwsgi.ini + +.. note:: You must run the Octavia/uWSGI command directly. Starting it + via ``systemctl`` will not work with the debug server. + +Visual Studio Code +------------------ + +While PyCharm synchronizes local changes with +the remote host, Code will work on the remote environment directly +through a SSH tunnel. That means that you don't even need to have +source code on your local machine in order to debug code on the remote. + +Detail information about remote debugging over SSH can be found +in the official Visual Studio Code documentation [4]_. +This guide will focus on the essential steps only. + +Using the remote development extension pack +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: This approach will not work with the Octavia API component + because that component is managed by uWSGI. + +After installing the *Visual Studio Code Remote Development Extension Pack* +[5]_ you need to open the *Remote Explorer* view and connect to the +SSH target. This will open a new window and on the bottom left of that window +you should see *SSH:* followed by the SSH host name. In the *Explorer* +view you can then choose to either clone a repository or open an +existing folder on the remote. For instance when working with +devstack you might want to open */opt/stack* or */opt/stack/octavia*. + +Next, you should configure the *launch.json*, which contains the run +configurations. Use the following template and adjust it to your needs:: + + { + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "Octavia Worker", + "type": "python", + "request": "launch", + "module": "octavia.cmd.octavia_worker", + "args": ["--config-file", "/etc/octavia/octavia.conf"], + "justMyCode": true + } + ] + } + +Make sure that the correct Python interpreter is selected in the status bar. +In a devstack environment the global Python interpreter */usr/bin/python3* +should be the correct one. Now you can start debugging by pressing *F5*. + +.. note:: When running this the first time Visual Studio Code might ask you + to install the Python debugger extension on the remote, which you must + do. Simply follow the steps shown in the IDE. + +Using ptvsd +~~~~~~~~~~~ + +.. warning:: ptvsd has been deprecated and replaced by debugpy. However, debugpy doesn't seem + work with uWSGI processes. The information in this section might be outdated. Another example is debugging the Octavia API service with the ptvsd debugger: @@ -80,3 +159,23 @@ The service will connect to your IDE, at which point remote debugging is active. Resume the program on the debugger to continue with the initialization of the service. At this point, the service should be operational and you can start debugging. + +Troubleshooting +=============== + +Remote process does not connect with local PyCharm debug server +--------------------------------------------------------------- + +#. Check if the debug server is still running +#. Check if the values of the exported *DEBUGGER_* variables above are correct. +#. Check if the remote machine can reach the port of the debug server:: + + $ nc -zvw10 $DEBUGGER_HOST $DEBUGGER_PORT + + If it cannot connect, the connection may be blocked by a firewall. + +.. [1] https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html +.. [2] https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html#remote-interpreter +.. [3] https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html#remote-debug-config +.. [4] https://code.visualstudio.com/docs/remote/ssh +.. [5] https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack diff --git a/doc/source/reference/introduction.rst b/doc/source/reference/introduction.rst index 031820a458..636d8727ea 100644 --- a/doc/source/reference/introduction.rst +++ b/doc/source/reference/introduction.rst @@ -30,7 +30,7 @@ Octavia accomplishes its delivery of load balancing services by managing a fleet of virtual machines, containers, or bare metal servers—collectively known as *amphorae*\— which it spins up on demand. This on-demand, horizontal scaling feature differentiates Octavia from other load balancing solutions, thereby -making Octavia truly suited "for the cloud." +making Octavia truly suited "for the cloud". Where Octavia fits into the OpenStack ecosystem -----------------------------------------------