libvirt: A few miscellaneous items related to "native TLS"

- Add a one-line summary of the config attribute
    `live_migration_with_native_tls` and a note about its version
    requirements.  Thus allowing the diligent operators, who carefully
    read the documentation, to make more informed choices.

  - Remove the superfluous "_migrateToURI3" suffix in the unit test.  In
    Nova commit 4b3e8772, we ripped out support for the older
    migrateToURI{2} APIs and just stuck to migrateToURI3().  So no need
    to spell out which migration API variant we are using.

  - Add a TODO item in the libvirt driver to deprecate and remove
    support for VIR_MIGRATE_TUNNELLED (and related config attribute)
    once the MIN_{LIBVIRT,QEMU}_VERSION supports "native TLS" by
    default.

Blueprint: support-qemu-native-tls-for-live-migration

Change-Id: Ic1419e443cecf94eb4f2c48894abb1a0eb9b73cb
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>

nova/conf/libvirt.py

@@ -462,6 +462,7 @@ image service. If not set, defaults to same type as source image.
     cfg.BoolOpt('live_migration_with_native_tls',
                 default=False,
                 help="""
+Use QEMU-native TLS encryption when live migrating.
 
 This option will allow both migration stream (guest RAM plus device
 state) *and* disk stream to be transported over native TLS, i.e. TLS
@@ -478,9 +479,11 @@ Notes:
   "block migration"), ``live_migration_with_native_tls`` is the
   preferred config attribute instead of ``live_migration_tunnelled``.
 
-* The ``live_migration_tunnelled`` will be deprecated in the long-term,
+* The ``live_migration_tunnelled`` will be deprecated in the long-term
   for two main reasons: (a) it incurs a huge performance penalty; and
-  it's not compatible with block migration.
+  (b) it is not compatible with block migration.  Therefore, if your
+  compute nodes have at least libvirt 4.4.0 and QEMU 2.11.0, it is
+  strongly recommended to use ``live_migration_with_native_tls``.
 
 * The ``live_migration_tunnelled`` and
   ``live_migration_with_native_tls`` should not be used at the same

nova/tests/unit/virt/libvirt/test_driver.py

@@ -10460,7 +10460,7 @@ class LibvirtConnTestCase(test.NoDBTestCase,
     @mock.patch('nova.virt.libvirt.migration.get_updated_guest_xml',
                 return_value='')
     @mock.patch('nova.virt.libvirt.guest.Guest.get_xml_desc', return_value='')
-    def test_block_live_migration_native_tls_migrateToURI3(
+    def test_block_live_migration_native_tls(
             self, mock_old_xml, mock_new_xml,
             mock_migrateToURI3, mock_min_version):
         self.flags(live_migration_with_native_tls=True, group='libvirt')

nova/virt/libvirt/driver.py

@@ -655,6 +655,20 @@ class LibvirtDriver(driver.ComputeDriver):
 
         return (live_migration_flags, block_migration_flags)
 
+    # TODO(kchamart) Once the MIN_LIBVIRT_VERSION and MIN_QEMU_VERSION
+    # reach 4.4.0 and 2.11.0, which provide "native TLS" support by
+    # default, deprecate and remove the support for "tunnelled live
+    # migration" (and related config attribute), because:
+    #
+    #  (a) it cannot handle live migration of disks in a non-shared
+    #      storage setup (a.k.a. "block migration");
+    #
+    #  (b) has a huge performance overhead and latency, because it burns
+    #      more CPU and memory bandwidth due to increased number of data
+    #      copies on both source and destination hosts.
+    #
+    # Both the above limitations are addressed by the QEMU-native TLS
+    # support (`live_migration_with_native_tls`).
     def _handle_live_migration_tunnelled(self, migration_flags):
         if CONF.libvirt.live_migration_tunnelled:
             migration_flags |= libvirt.VIR_MIGRATE_TUNNELLED