Ubuntu Manpage: virt-v2v-output-openstack - Using virt-v2v to convert guests to OpenStack

Provided by: libguestfs-tools_1.40.2-7ubuntu5_amd64

NAME

       virt-v2v-output-openstack - Using virt-v2v to convert guests to OpenStack

SYNOPSIS

        virt-v2v [-i* options] -o openstack
                               -oo server-id=SERVER
                               [-oo guest-id=GUEST]
                               [-oo verify-server-certificate=false]
                               [-oo os-username=admin] [-oo os-*=*]

        virt-v2v [-i* options] -o glance

DESCRIPTION

       This page documents how to use virt-v2v(1) to convert guests to run on OpenStack.  There are two output
       modes you can select, but only -o openstack should be used normally.

       -o openstack -oo server-id=SERVER [...]
           Full description: "OUTPUT TO OPENSTACK"

           This is the modern method for uploading to OpenStack via the REST API.  Guests can be directly
           converted into Cinder volumes.

       -o glance
           Full description: "OUTPUT TO GLANCE"

           This is the old method for uploading to Glance.  Unfortunately Glance is not well suited to storing
           converted guests (since virt-v2v deals with "pets" not templated "cattle"), so this method is not
           recommended unless you really know what you are doing.

OUTPUT TO OPENSTACK

       To output to OpenStack, use the -o openstack option.

   OpenStack: Setting up a conversion appliance
       When virt-v2v is converting to OpenStack, it is unusual in that virt-v2v must be running inside a virtual
       machine running on top of the OpenStack overcloud.  This virtual machine is called the "conversion
       appliance".  Note this virtual machine is unrelated to the guest which is being converted.

       The reason for this is because to create Cinder volumes that will contain the guest data (for the
       converted guest) we must attach those Cinder volumes to an OpenStack virtual machine.

       The "openstack" command must be installed in the appliance.  We use it for communicating with OpenStack.

       When virt-v2v is running in the conversion appliance, you must supply the name or UUID of the conversion
       appliance to virt-v2v, eg:

        $ openstack server list
        +--------------------------------------+-----------+--------+
        | ID                                   | Name      | Status |
        +--------------------------------------+-----------+--------+
        | bbb0147a-44b9-4d19-9a9d-10ca9a984744 | test1     | ACTIVE |
        +--------------------------------------+-----------+--------+

        # virt-v2v [...] \
              -o openstack -oo server-id=bbb0147a-44b9-4d19-9a9d-10ca9a984744

       or:

        # virt-v2v [...] -o openstack -oo server-id=test1

       You can run many parallel conversions inside a single conversion appliance if you want, subject to having
       enough resources available.  However OpenStack itself imposes a limit that you should be aware of:
       OpenStack cannot attach more than around 25 disks [the exact number varies with configuration] to a
       single appliance, and that limits the number of guests which can be converted in parallel, because each
       guest's disk must be attached to the appliance while being copied.

   OpenStack: Authentication
       Converting to OpenStack requires access to the tenant (non-admin) API endpoints.  You will need to either
       set up your "$OS_*" environment variables or use output options on the virt-v2v command line to
       authenticate with OpenStack.

       Normally there is a file called something like "stackrc", "overcloudrc" etc which you can simply "source"
       to set everything up.

       For example:

        export OS_USERNAME=admin

       or:

        virt-v2v [...] -o openstack -oo os-username=admin

       are equivalent, and have the same effect as using --os-username on the command line of OpenStack tools.

   OpenStack: Running as root
       Because virt-v2v must access Cinder volumes which are presented as /dev devices to the conversion
       appliance, virt-v2v must usually run as root in -o openstack mode.

       If you use "sudo" to start virt-v2v and you are using environment variables for authentication, remember
       to use the "sudo -E" option to preserve the environment.

   OpenStack: Guest ID
        virt-v2v [...] -o openstack -oo guest-id=123-456-7890

       You may optionally specify -oo guest-id=... on the command line.  The ID (which can be any string) is
       saved on each Cinder volume in the "virt_v2v_guest_id" volume property.

       This can be used to find disks associated with a guest, or to associate which disks are related to which
       guests when converting many guests.

   OpenStack: Ignore server certificate
       Using -oo verify-server-certificate=false you can tell the openstack client to ignore the server
       certificate when connecting to the OpenStack API endpoints.  This has the same effect as passing the
       --insecure option to the "openstack" command.

   OpenStack: Converting a guest
       The final command to convert the guest, running as root, will be:

        # virt-v2v [-i options ...] \
              -o openstack -oo server-id=NAME|UUID [-oo guest-id=ID]

       If you include authentication options on the command line then:

        # virt-v2v [-i options ...] \
              -o openstack -oo server-id=NAME|UUID -oo os-username=admin [etc]

   OpenStack: Booting the guest
       Guests are converted as Cinder volume(s) (one volume per disk in the original guest).  To boot them use
       the "openstack server create --volume" option:

        $ openstack volume list
        +--------------------------------------+---------------+-----------+
        | ID                                   | Name          | Status    |
        +--------------------------------------+---------------+-----------+
        | c4d06d15-22ef-462e-9eff-ab54ab285a1f | fedora-27-sda | available |
        +--------------------------------------+---------------+-----------+
        $ openstack server create \
              --flavor x1.small \
              --volume c4d06d15-22ef-462e-9eff-ab54ab285a1f \
              myguest
        $ openstack console url show myguest

   OpenStack: Other conversion options
       To specify the Cinder volume type, use -os.  If not specified then no Cinder volume type is used.

       The following options are not supported with OpenStack: -oa, -of.

OUTPUT TO GLANCE

Note this is a legacy option. In most cases you should use "OUTPUT TO OPENSTACK" instead.

To output to OpenStack Glance, use the -o glance option.

This runs the glance(1) CLI program which must be installed on the virt-v2v conversion host. For
authentication to work, you will need to set "OS_*" environment variables. In most cases you can do this
by sourcing a file called something like keystonerc_admin.

Virt-v2v adds metadata for the guest to Glance, describing such things as the guest operating system and
what drivers it requires. The command "glance image-show" will display the metadata as "Property" fields
such as "os_type" and "hw_disk_bus".

Glance and sparseness
Glance image upload doesn't appear to correctly handle sparseness. For this reason, using qcow2 will be
faster and use less space on the Glance server. Use the virt-v2v -of qcow2 option.

Glance and multiple disks
If the guest has a single disk, then the name of the disk in Glance will be the name of the guest. You
can control this using the -on option.

Glance doesn't have a concept of associating multiple disks with a single guest, and Nova doesn't allow
you to boot a guest from multiple Glance disks either. If the guest has multiple disks, then the first
(assumed to be the system disk) will have the name of the guest, and the second and subsequent data disks
will be called "guestname-disk2", "guestname-disk3" etc. It may be best to leave the system disk in
Glance, and import the data disks to Cinder.

AUTHOR

       Richard W.M. Jones

COPYRIGHT

       Copyright (C) 2009-2019 Red Hat Inc.

LICENSE

       This program is free software; you can redistribute it and/or modify it under the terms of the GNU
       General Public License as published by the Free Software Foundation; either version 2 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
       License for more details.

       You should have received a copy of the GNU General Public License along with this program; if not, write
       to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

BUGS

       To get a list of bugs against libguestfs, use this link:
       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

       To report a new bug against libguestfs, use this link:
       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

       When reporting a bug, please supply:

       •   The version of libguestfs.

       •   Where you got libguestfs (eg. which Linux distro, compiled from source, etc)

       •   Describe the bug accurately and give a way to reproduce it.

       •   Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report.