.. _Managing Virtual Machines:

Managing Virtual Machines
-------------------------

.. _vinfra service compute server create:

vinfra service compute server create
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a new compute server:

:: 

   usage: vinfra service compute server create [--description <description>] 
                                               [--metadata <metadata>] 
                                               [--user-data <user-data>]
                                               [--key-name <key-name>]  
                                               [--config-drive] [--count <count>] 
                                               [--ha-enabled {true,false}]
                                               --network <id=id[,key=value,...]>
                                               --volume <source=source[,key=value,...]> 
                                               --flavor <flavor> <server-name>

``--description <description>``
   Server description

``--metadata <metadata>``
   Server metadata

``--user-data <user-data>``
   User data file

``--key-name <key-name>``
   Key pair to inject

``--config-drive``
   Use an ephemeral drive

``--count <count>``
   If count is specified and greater than 1, the ``name`` argument is treated as a naming pattern.

``--ha-enabled {true,false}``
   Enable or disable HA for the compute server

``--network <id=id[,key=value,...]>``
   Create a compute server with a specified network. Specify this option multiple times to create multiple networks.

   - ``id``: attach network interface to a specified network (ID or name)
   - comma-separated ``key=value`` pairs with keys (optional):

     - ``mac``: MAC address for network interface
     - ``fixed-ip``: fixed IP address for network interface
     - ``spoofing-protection``: enable or disable spoofing protection for network interface (``on`` or ``off``)

``--volume <source=source[,key=value,...]>``
   Create a compute server with a specified volume. Specify this option multiple times to create multiple volumes.

   - ``source``: source type (``volume``, ``image``, ``snapshot``, or ``blank``)
   - comma-separated ``key=value`` pairs with keys (optional):

     - ``id``: resource ID or name for the specified source type (required for source types ``volume``, ``image``, and ``snapshot``)
     - ``size``: block device size, in gigabytes (required for source types ``image`` and ``blank``)
     - ``boot-index``: block device boot index (required for multiple volumes with source type ``volume``)
     - ``bus``: block device controller type (``scsi``)
     - ``type``: block device type (``disk`` or ``cdrom``)
     - ``rm``: remove block device on compute server termination (``yes`` or ``no``)
     - ``storage-policy``: block device storage policy

``--flavor <flavor>``
   Flavor ID or name

``<server-name>``
   A new name for the compute server

Example:

::

   # vinfra service compute server create myvm \
   --network id=private,fixed-ip=192.168.128.100 \
   --volume source=image,id=cirros,size=1 --flavor tiny
   +--------------+--------------------------------------+
   | Field        | Value                                |
   +--------------+--------------------------------------+
   | config_drive |                                      |
   | created      | 2019-05-29T11:24:04Z                 |
   | description  |                                      |
   | flavor       | disk: 0                              |
   |              | ephemeral: 0                         |
   |              | extra_specs: {}                      |
   |              | original_name: tiny                  |
   |              | ram: 512                             |
   |              | swap: 0                              |
   |              | vcpus: 1                             |
   | ha_enabled   | True                                 |
   | host         |                                      |
   | id           | 8cd29296-8bee-4efb-828d-0e522d816c6e |
   | key_name     |                                      |
   | metadata     | {}                                   |
   | name         | myvm                                 |
   | networks     | []                                   |
   | power_state  | NOSTATE                              |
   | project_id   | b4267de6fd0c442da99542cd20f5932c     |
   | status       | BUILD                                |
   | task_state   | scheduling                           |
   | updated      | 2019-05-29T11:24:21Z                 |
   | user_data    |                                      |
   | volumes      | []                                   |
   +--------------+--------------------------------------+

This command creates a virtual machine ``myvm`` based on the default Cirros image and the flavor ``tiny``, connects it to the network ``private`` with the fixed IP address 192.168.128.100, and enables HA for it.

.. _vinfra service compute server list:

vinfra service compute server list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

List compute servers:

:: 

   usage: vinfra service compute server list

Example:

::

   # vinfra service compute server list
   +--------------------------------------+------+--------+------------------------+
   | id                                   | name | status | host                   |
   +--------------------------------------+------+--------+------------------------+
   | 8cd29296-8bee-4efb-828d-0e522d816c6e | myvm | ACTIVE | node001.vstoragedomain |
   +--------------------------------------+------+--------+------------------------+

This command lists all virtual machines in the compute cluster.

.. _vinfra service compute server show:

vinfra service compute server show
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Display compute server details:

:: 

   usage: vinfra service compute server show <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server show myvm
   +---------------+--------------------------------------------+
   | Field         | Value                                      |
   +---------------+--------------------------------------------+
   | config_drive  |                                            |
   | created       | 2019-05-29T11:24:04Z                       |
   | description   |                                            |
   | flavor        | disk: 0                                    |
   |               | ephemeral: 0                               |
   |               | extra_specs: {}                            |
   |               | original_name: tiny                        |
   |               | ram: 512                                   |
   |               | swap: 0                                    |
   |               | vcpus: 1                                   |
   | ha_enabled    | True                                       |
   | host          | node001.vstoragedomain                     |
   | id            | 8cd29296-8bee-4efb-828d-0e522d816c6e       |
   | key_name      |                                            |
   | metadata      | {}                                         |
   | name          | myvm                                       |
   | networks      | - id: 79b3da71-c6a2-49e8-97f8-9431a065bed7 |
   |               |   ipam_enabled: true                       |
   |               |   ips:                                     |
   |               |   - 192.168.128.100                        |
   |               |   mac_addr: fa:16:3e:d8:42:f6              |
   |               |   name: private                            |
   |               |   spoofing_protection: true                |
   | orig_hostname | node001                                    |
   | power_state   | RUNNING                                    |
   | project_id    | b4267de6fd0c442da99542cd20f5932c           |
   | status        | ACTIVE                                     |
   | task_state    |                                            |
   | updated       | 2019-05-29T11:24:21Z                       |
   | user_data     |                                            |
   | volumes       | - delete_on_termination: false             |
   |               |   id: edd3df0a-95f5-4892-9053-2793a3976f94 |
   +---------------+--------------------------------------------+

This command shows the details of the virtual machine ``myvm``.

.. _vinfra service compute server stat:

vinfra service compute server stat
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Display compute server statistics:

:: 

   usage: vinfra service compute server stat <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server stat myvm
   +----------+----------------------------------+
   | Field    | Value                            |
   +----------+----------------------------------+
   | datetime | 2019-05-29T11:39:46.429000+00:00 |
   | metrics  | block_capacity: 1073741824       |
   |          | block_usage: 268435456           |
   |          | cpu_usage: 0                     |
   |          | mem_usage: 149876736             |
   +----------+----------------------------------+

This command shows the statistics for the virtual machine ``myvm``.

.. _vinfra service compute server set:

vinfra service compute server set
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Modify compute server parameters:

::

   usage: vinfra service compute server set [--name <name>] [--description <description>]
                                            [--ha-enabled {true,false}] <server>

``--name <name>``
   A new name for the compute server

``--description <description>``
   A new description for the compute server

``--ha-enabled {true,false}``
   Enable or disable HA for the compute server

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server set myvm --description "My new VM" --ha-enabled false
   +---------------+--------------------------------------------+
   | Field         | Value                                      |
   +---------------+--------------------------------------------+
   | config_drive  |                                            |
   | created       | 2019-05-29T11:24:04Z                       |
   | description   | My new VM                                  |
   | flavor        | disk: 0                                    |
   |               | ephemeral: 0                               |
   |               | extra_specs: {}                            |
   |               | original_name: tiny                        |
   |               | ram: 512                                   |
   |               | swap: 0                                    |
   |               | vcpus: 1                                   |
   | ha_enabled    | False                                      |
   | host          | node001.vstoragedomain                     |
   | id            | 8cd29296-8bee-4efb-828d-0e522d816c6e       |
   | key_name      |                                            |
   | metadata      | {}                                         |
   | name          | myvm                                       |
   | networks      | - id: 79b3da71-c6a2-49e8-97f8-9431a065bed7 |
   |               |   ipam_enabled: true                       |
   |               |   ips:                                     |
   |               |   - 192.168.128.100                        |
   |               |   mac_addr: fa:16:3e:d8:42:f6              |
   |               |   name: private                            |
   |               |   spoofing_protection: true                |
   | orig_hostname | node001                                    |
   | power_state   | RUNNING                                    |
   | project_id    | b4267de6fd0c442da99542cd20f5932c           |
   | status        | ACTIVE                                     |
   | task_state    |                                            |
   | updated       | 2019-05-29T11:24:21Z                       |
   | user_data     |                                            |
   | volumes       | - delete_on_termination: false             |
   |               |   id: edd3df0a-95f5-4892-9053-2793a3976f94 |
   +---------------+--------------------------------------------+

This command adds a description to the virtual machine ``myvm`` and disables HA for it.

.. _vinfra service compute server iface attach:

vinfra service compute server iface attach
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Attach a network to a compute server:

:: 

   usage: vinfra service compute server iface attach [--mac <mac>] [--ip <ip-address>]
                                                     [--spoofing-protection {on,off}]
                                                     --server <server> --network <network>

``--mac <mac>``
   MAC address

``--ip <ip-address>``
   IP address

``--spoofing-protection {on|off}``
   Enable spoofing protection for the network interface

``--server <server>``
   Compute server ID or name

``--network <network>``
   Network ID or name

Example:

::

   # vinfra service compute server iface attach --network myprivnet --server myvm
   +---------------+--------------------------------------+
   | Field         | Value                                |
   +---------------+--------------------------------------+
   | fixed_ip      | 192.168.129.8                        |
   | id            | 690ed3f2-2301-40e2-879a-126db2ecb57b |
   | mac_address   | fa:16:3e:54:59:08                    |
   | network_id    | 0710372e-2bdf-4dfe-b413-eb763da37e68 |
   | spoofing<...> | False                                |
   +---------------+--------------------------------------+

This command attaches the private network ``myprivnet`` to the virtual machine ``myvm``.

.. _vinfra service compute server iface list:

vinfra service compute server iface list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

List compute server networks:

:: 

   usage: vinfra service compute server iface list --server <server>

``--server <server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server iface list --server myvm
   +----------------+----------------+-------------------+-----------------+
   | id             | network_id     | mac_address       | fixed_ip        |
   +----------------+----------------+-------------------+-----------------+
   | 690ed3f2-<...> | 0710372e-<...> | fa:16:3e:54:59:08 | 192.168.129.8   |
   | a5b13bf3-<...> | 1bf2c9da-<...> | fa:16:3e:b9:33:bb | 192.168.128.100 |
   +----------------+----------------+-------------------+-----------------+

This command lists the virtual networks that the virtual machine ``myvm`` is attached to. It also shows VM's IP address in each network.

.. _vinfra service compute server iface detach:

vinfra service compute server iface detach
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Detach a network interface from a compute server:

:: 

   usage: vinfra service compute server iface detach --server <server> <interface>

``--server <server>``
   Compute server ID or name

``<interface>``
   Network interface ID

Example:

::

   # vinfra service compute server iface detach 471e37fd-13ae-4b8f-b70c-90ac02cc4386 \
   --server 6c80b07f-da46-4a8a-89a4-eecb8faceb27
   Operation successful

This command detaches the network interface with the ID ``471e37fd-13ae-4b8f-b70c-90ac02cc4386`` from the VM with the ID ``6c80b07f-da46-4a8a-89a4-eecb8faceb27``.

.. _vinfra service compute server volume attach:

vinfra service compute server volume attach
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Attach a volume to a compute server:

:: 

   usage: vinfra service compute server volume attach --server <server> <volume>

``--server <server>``
   Compute server ID or name

``<volume>``
   Volume ID or name

Example:

::

   # vinfra service compute server volume attach e4cb5363-1fb2-41f5-b24b-18f98a388cba \
   --server 871fef54-519b-4111-b18d-d2039e2410a8
   +--------+--------------------------------------+
   | Field  | Value                                |
   +--------+--------------------------------------+
   | device | /dev/vdb                             |
   | id     | e4cb5363-1fb2-41f5-b24b-18f98a388cba |
   +--------+--------------------------------------+

This command attaches the available volume with the ID ``e4cb5363-1fb2-41f5-b24b-18f98a388cba`` to the VM with the ID ``871fef54-519b-4111-b18d-d2039e2410a8``.

.. _vinfra service compute server volume list:

vinfra service compute server volume list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

List compute server volumes:

:: 

   usage: vinfra service compute server volume list --server <server>

``--server <server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server volume list --server myvm
   +--------------------------------------+----------+
   | id                                   | device   |
   +--------------------------------------+----------+
   | e4cb5363-1fb2-41f5-b24b-18f98a388cba | /dev/vdb |
   | b325cc6e-8de1-4b6c-9807-5a497e3da7e3 | /dev/vda |
   +--------------------------------------+----------+   

This command lists the volumes attached to the virtual machine ``myvm``.

.. _vinfra service compute server volume show:

vinfra service compute server volume show
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Show details of a compute server volume:

:: 

   usage: vinfra service compute server volume show --server <server>  <volume>

``--server <server>``
   Compute server ID or name

``<volume>``
   Volume ID or name

Example:

::

   # vinfra service compute server volume show --server myvm \
   e4cb5363-1fb2-41f5-b24b-18f98a388cba
   +--------+--------------------------------------+
   | Field  | Value                                |
   +--------+--------------------------------------+
   | device | /dev/vdb                             |
   | id     | e4cb5363-1fb2-41f5-b24b-18f98a388cba |
   +--------+--------------------------------------+

This command shows the details for the volume with the ID ``e4cb5363-1fb2-41f5-b24b-18f98a388cba`` attached to the virtual machine ``myvm``.

.. _vinfra service compute server volume detach:

vinfra service compute server volume detach
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Detach a volume from a compute server:

:: 

   usage: vinfra service compute server volume detach --server <server> <volume>

``--server <server>``
   Compute server ID or name

``<volume>``
   Volume ID or name

Example:

::

   # vinfra service compute server volume detach e4cb5363-1fb2-41f5-b24b-18f98a388cba \
   --server 871fef54-519b-4111-b18d-d2039e2410a8
   Operation successful

This command detaches the volume with the ID ``e4cb5363-1fb2-41f5-b24b-18f98a388cba`` from the VM with the ID ``871fef54-519b-4111-b18d-d2039e2410a8``.

.. _vinfra service compute server log:

vinfra service compute server log
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Display compute server log:

:: 

   usage: vinfra service compute server log <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server log myvm > myvm.log

This command prints the log of the virtual machine ``myvm`` to the file ``myvm.log``.

.. _vinfra service compute server migrate:

vinfra service compute server migrate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Migrate a compute server to another host:

:: 

   usage: vinfra service compute server migrate [--cold] [--node <node>] <server>

``--cold``
   Perform cold migration. If not set, the migration type is determined automatically.

``--node <node>``
   Destination node ID or hostname

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server migrate 6c80b07f-da46-4a8a-89a4-eecb8faceb27 \
   --node e6255aed-d6e7-41b2-ba90-86164c1cd9a6
   Operation successful

This command starts migration of the VM with the ID ``6c80b07f-da46-4a8a-89a4-eecb8faceb27`` to the compute node with the ID ``e6255aed-d6e7-41b2-ba90-86164c1cd9a6``.

.. _vinfra service compute server resize:

vinfra service compute server resize
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Resize a compute server:

:: 

   usage: vinfra service compute server resize --flavor <flavor> <server>

``--flavor <flavor>``
   Apply flavor with ID or name

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server resize myvm --flavor small
   Operation successful

This command changes the flavor of the virtual machine ``myvm`` to ``small``.

.. _vinfra service compute server start:

vinfra service compute server start
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Start a compute server:

:: 

   usage: vinfra service compute server start <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server start myvm
   Operation successful

This command starts the virtual machine ``myvm``.

.. _vinfra service compute server pause:

vinfra service compute server pause
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pause a compute server:

:: 

   usage: vinfra service compute server pause <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server pause myvm

This command pauses the running virtual machine ``myvm``.

.. _vinfra service compute server unpause:

vinfra service compute server unpause
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unpause a compute server:

:: 

   usage: vinfra service compute server unpause <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server unpause myvm

This command unpauses the paused virtual machine ``myvm``.

.. _vinfra service compute server suspend:

vinfra service compute server suspend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Suspend a compute server:

:: 

   usage: vinfra service compute server suspend <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server suspend myvm
   Operation successful

This command suspends the running virtual machine ``myvm``.

.. _vinfra service compute server resume:

vinfra service compute server resume
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Resume a compute server:

:: 

   usage: vinfra service compute server resume <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server resume myvm
   Operation successful

This command resumes the suspended virtual machine ``myvm``.

.. _vinfra service compute server reboot:

vinfra service compute server reboot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Reboot a compute server:

:: 

   usage: vinfra service compute server reboot [--hard] <server>

``--hard``
   Perform hard reboot

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server reboot myvm
   Operation successful

This command reboots the virtual machine ``myvm``.

.. _vinfra service compute server reset-state:

vinfra service compute server reset-state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Reset compute server state:

:: 

   usage: vinfra service compute server reset-state [--state-error] <server>

``--state-error``
   Reset server to 'ERROR' state

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server reset-state myvm
   Operation successful

This command resets the transitional state of the virtual machine ``myvm`` to the previous one.

.. _vinfra service compute server stop:

vinfra service compute server stop
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Shut down a compute server:

:: 

   usage: vinfra service compute server stop [--hard] <server>

``--hard``
   Power off a compute server

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server stop myvm
   Operation successful

This command stops the virtual machine ``myvm``.

.. _vinfra service compute server shelve:

vinfra service compute server shelve
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Shelve a compute server:

::

   usage: vinfra service compute server shelve <server>

``<server>``
   Compute server ID or name.

Example:

::

   # vinfra service compute server shelve myvm

This command unbinds the virtual machine ``myvm`` from the node it is hosted on and releases its reserved resources such as CPU and RAM.

.. _vinfra service compute server unshelve:

vinfra service compute server unshelve
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unshelve a compute server:

::

   usage: vinfra service compute server unshelve <server>

``<server>``
   Compute server ID or name.

Example:

::

   # vinfra service compute server unshelve myvm

This command spawns the virtual machine ``myvm`` on a node with enough resources to host it.

.. _vinfra service compute server evacuate:

vinfra service compute server evacuate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Evacuate a stopped compute server from a failed host:

:: 

   usage: vinfra service compute server evacuate <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server evacuate myvm
   Operation successful

This command evacuates the stopped VM ``myvm`` from its node to another, healthy compute node.

.. _vinfra service compute server delete:

vinfra service compute server delete
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Delete a compute server:

:: 

   usage: vinfra service compute server delete <server>

``<server>``
   Compute server ID or name

Example:

::

   # vinfra service compute server delete myvm
   Operation successful

This command deletes the virtual machine ``myvm``.