Documentation updates
Minor corrections and update of the remote debugging guide. Change-Id: I0d08aaf4f02f5575f1a68b65ebc16aafad8a0270
This commit is contained in:
Tom Weininger
parent
c5561a3ecb
commit
d556c622b1
@ -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
|
||||
----------------------------------------------
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
-----------------------------------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user