Documentation updates

Minor corrections and update of the remote debugging guide.

Change-Id: I0d08aaf4f02f5575f1a68b65ebc16aafad8a0270

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
+  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
+  for Octavia, then the vendor should bend to Octavia's needs, not the other
-way around.
+  way around.
 
 Octavia is a load balancer for large operators
 ----------------------------------------------

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

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
+Both PyCharm Professional edition and Visual Studio Code offer remote debugging
-installed.
+features that can be used for debugging Octavia components.
 
-If you're using PyCharm, you can find it in
+.. note:: Before running a new Octavia process you should
-*/path/to/pycharm/debug-eggs/pycharm-debug.egg* (Python 2) and
+    make sure that processes of that component are no longer running.
-*/path/to/pycharm/debug-eggs/pycharm-debug-py3k.egg* (Python 3). Copy that file
+    You can use ``ps aux`` in order to verify that.
-into your OpenStack host and install the library in your Python path:
 
-::
+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 ->
+Then, create a new *Run/Debug Configuration* by selecting
-Edit Configurations -> Python Remote Debug*. The local host name refers to the
+*Run -> Edit Configurations...* in the menu bar.
-local machine you're running your IDE from and it must be one reachable by your
+Add a new configuration and make sure
-OpenStack environment. The port can be any available port (e.g. 5678). If the
+*Module name* is selected instead of *Script path*. Enter the module name of
-code on the OpenStack and PyCharm hosts is on different paths (likely), define
+the Octavia component you want to debug, for instance
-a path mapping in the remote debug configuration.
+``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
+Using a Python debug server
-will begin listening on the specified host and port.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+want to debug. For example, to debug the Octavia API service::
-worker. For example, to debug the Octavia Worker 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

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
 -----------------------------------------------