github.com/Cloud-Foundations/Dominator@v0.3.4/cmd/vm-control/README.md (about)

     1  # vm-control
     2  A utility to manage Virtual Machines (VMs).
     3  
     4  The *vm-control* utility creates and manages VMs by communicating with a
     5  *[Hypervisor](../hypervisor/README.md)*. It is typically run on a desktop, bastion or build machine.
     6  
     7  ## Usage
     8  *vm-control* supports several sub-commands. There are many command-line flags
     9  which provide parameters for these sub-commands. The most commonly used
    10  parameters are `-fleetManagerHostname` or `-hypervisorHostname` which specify
    11  either the *[Fleet Manager](../fleet-manager/README.md)* or a specific *[Hypervisor](../hypervisor/README.md)* to communicate with.
    12  The basic usage pattern is:
    13  
    14  ```
    15  vm-control [flags...] command [args...]
    16  ```
    17  
    18  Built-in help is available with the command:
    19  
    20  ```
    21  vm-control -h
    22  ```
    23  
    24  Some of the sub-commands available are:
    25  
    26  - **add-vm-volumes**: add volumes to a VM
    27  - **become-primary-vm-owner**: become the primary owner of a VM
    28  - **change-vm-console-type**: change the console type for a VM
    29  - **change-vm-cpus**: change the number of CPUs for a VM
    30  - **change-vm-destroy-protection**: enable/disable destroy protect for a VM
    31  - **change-vm-memory**: change the memory for a VM
    32  - **change-vm-owner-users**: change the extra owners for a VM
    33  - **change-vm-tags**: change the tags for a VM
    34  - **change-vm-vcpus**: change the number of vCPUs for a VM
    35  - **change-vm-volume-size**: change the size of a specified volume on a VM
    36  - **connect-to-vm-console**: connect to the Virtual Network Console for the
    37                               specified VM
    38  - **connect-to-vm-serial-port**: connect to the specified VM serial port
    39  - **copy-vm**: make a copy of a VM. The new VM will have a different IP address
    40  - **create-vm**: create a VM
    41  - **debug-vm-image**: (re)start a VM with a temporary debug image. The old root
    42                        volume will become the first secondary volume. Debugging
    43                        ends when the VM is stopped or (re)started
    44  - **delete-vm-volume**: delete a specified volume from a VM
    45  - **destroy-vm**: destroy a VM (all ephemeral data and metadata are lost)
    46  - **discard-vm-old-image**: discard the previous root image for a VM
    47  - **discard-vm-old-user-data**: discard the previous user data for a VM
    48  - **discard-vm-snapshot**: discard the previous snapshot for a VM
    49  - **export-local-vm**: export a local VM to an importing tool. This is primarily
    50                         for debugging
    51  - **export-virsh-vm**: export VM to a local virsh VM. The specified FQDN will
    52                         be used to specify the new virsh domain name. The VM
    53                         must first be stopped. The exported virsh VM is started
    54  - **get-hypervisors**: get details of healthy Hypervisors in the specified
    55                         location
    56  - **get-vm-info**: get and show the information for a VM
    57  - **get-vm-user-data**: get (copy) the user data for a VM
    58  - **get-vm-volume**: get (copy) a specified VM volume
    59  - **import-local-vm**: import a local raw VM. This is primarily for debugging
    60  - **import-virsh-vm**: import a local virsh VM. The specified domain name must
    61                         be a FQDN, which is used to obtain the IP address of the
    62                         imported VM. The virsh VM must first be shut down. The
    63                         imported VM is started
    64  - **list-hypervisors**: list healthy Hypervisors in the specified location
    65  - **list-locations**: list locations within the specified top location
    66  - **list-vms**: list the IP addresses for all VMs
    67  - **migrate-vm**: migrate a VM to another Hypervisor
    68  - **patch-vm-image**: patch the root image for a VM. Files listed in the image
    69                        filter are not changed. The old root image is saved. The
    70                        VM must not be running
    71  - **probe-vm-port**: probe (from its *Hypervisor*) a TCP port for a VM
    72  - **reboot-vm**: reboot a VM
    73  - **replace-vm-credentials**: replace the credentials made available to a VM via
    74                                the Metadata service
    75  - **replace-vm-image**: replace the root image for a VM. The old root image is
    76                          saved. The VM must not be running
    77  - **replace-vm-user-data**: replace the user data for a VM. The old user data is
    78                          saved
    79  - **restore-vm**: restore all VM data (volumes) and metadata from a storage
    80                    source. If the target *Hypervisor* has the original IP
    81                    available it will be re-allocated for the new (restored) VM,
    82                    otherwise a new IP address will be allocated
    83  - **restore-vm-from-snapshot**: restore VM volumes from the previous snapshot,
    84                                  discarding current volumes
    85  - **restore-vm-image**: restore the previously saved root image for a VM. The VM
    86                          must not be running
    87  - **restore-vm-user-data**: restore the previously saved user data for a VM
    88  - **reorder-vm-volumes**: re-order the volumes for a VM
    89  - **set-vm-migrating**: change the VM state to migrating. For debugging only
    90  - **snapshot-vm**: create a snapshot of the VM volumes, discarding previous one
    91  - **save-vm**: save (backup) all VM data (volumes) and metadata to a storage
    92                 destination
    93  - **scan-vm-root**: scan the root file-system of stopped VM and write to
    94                      scanFilename
    95  - **start-vm**: start a stopped VM
    96  - **stop-vm**: stop a running VM. All data and metadata are preserved
    97  - **trace-vm-metadata**: trace the requests a VM makes to the metadata service
    98  - **unset-vm-migrating**: change the VM state to stopped. For debugging only
    99  
   100  ## Security
   101  The *Hypervisor* restricts RPC access using TLS client authentication.
   102  *vm-control* will load certificate and key files from the
   103  `~/.ssl` directory. *vm-control* will present these certificates to
   104  the *Hypervisor*. If one of the certificates is signed by a certificate
   105  authority that the *Hypervisor* trusts, the *Hypervisor* will grant access.
   106  Most operations only require a certificate that proves *identity*.
   107  The *[Keymaster](https://github.com/Symantec/keymaster)* is a good choice for issuing these certificates.
   108  
   109  ## Importing virsh (libvirt) VMs
   110  A libvirt VM may be imported into the *Hypervisor*. Once the VM is *committed*
   111  it is removed from the libvirt database and is fully "owned" by the
   112  *Hypervisor*. Importing a VM requires root access on the *Hypervisor* (the
   113  *vm-control* tool will use the `sudo` command if needed).
   114  
   115  There are a few simple steps that should be followed to import a VM. In the
   116  example below, the MAC address of the VM to be imported is `52:54:de:ad:be:ef`
   117  and the hostname (DNS entry) is `jump.prod.company.com`. The IP address of the
   118  VM may also be used. In either case, the hostname or IP address provided must
   119  match the libvirt *domain name*. If the VM has multiple network interfaces, the
   120  MAC and IP address/FQDN for each interface must be provided in pairs.
   121  - log into the VM and determine its MAC address
   122  - run `vm-control import-virsh-vm 52:54:de:ad:be:ef jump.prod.company.com`
   123  - enter `shutdown` at the prompt
   124  - wait for the VM to start and log in and check that it is functioning properly
   125  - respond to the `commit/defer/abandon` prompt:
   126    - `commit`: the VM is removed from the libvirt database
   127    - `defer`: the VM is left running on the *Hypervisor*. It may later be
   128               committed (and the `virsh undefine` command should be used to
   129               remove it from the libvirt database) or destroyed. This is not
   130               recommended
   131    - `abandon`: the VM is deleted from the *Hypervisor* and will need to be
   132                 manually started with the `virsh` command
   133  
   134  ## Exporting VMs to virsh (libvirt)
   135  A local VM on the *Hypervisor* may be exported to a libvirt VM. Once the libvirt
   136  VM is *committed* the original VM is removed from the database and is fully
   137  "owned" by libvirt. Exporting a VM requires root access on the *Hypervisor* (the
   138  *vm-control* tool will use the `sudo` command if needed).
   139  
   140  There are a few simple steps that should be followed to export a VM. In the
   141  example below, the hostname (DNS entry) of the VM to be exported is
   142  `jump.prod.company.com`. The IP address of the VM may also be used. In either
   143  case, the hostname or IP address provided will become the new libvirt *domain
   144  name*.
   145  - set up a DHCP server
   146  - add the IP and MAC addresses of the VM being exported to the DHCP server
   147    configuration. Alternatively, you can log into the VM prior to exporting it
   148    and reconfigure it to use a static network configuration
   149  - if a *[Fleet Manager](../fleet-manager/README.md)* is being used, the IP address must be added to the
   150    `ReservedIPs` list in the topology, so as to prevent re-use of the IP address
   151    when creating new VMs
   152  - run `vm-control export-virsh-vm jump.prod.company.com`
   153  - you will be prompted if a DHCP server entry has been configured
   154  - wait for the VM to start and log in and check that it is functioning properly
   155  - respond to the `commit/defer/abandon` prompt:
   156    - `commit`: the VM is removed from the *Hypervisor* database
   157    - `defer`: the new libvirt VM is left running. It may later be committed (and
   158               the `vm-control destroy-vm` command should be used to
   159               remove it from the *Hypervisor* database). Deferring is not
   160               recommended
   161    - `abandon`: the new libvirt VM is deleted from the libvirt database and the
   162                 original VM will be started
   163  
   164  ## VM Placement Command
   165  An optional local command to be used when making VM placement decisions (when
   166  creating, copying, migrating or restoring VMs) may be specified using the
   167  `-placementCommand` option when `-placement=command`.
   168  The *placement command* may read from the standard input a JSON payload
   169  describing the `Hypervisors` available (based on other location and tag matching
   170  options) and the `VmInfo` describing the VM that will be placed. The name of
   171  the selected *Hypervisor* must be written to the standard output.
   172  
   173  The schema of the data presented to the standard input is:
   174  ```
   175  struct {
   176      Hypervisors []fm_proto.Hypervisor `json:",omitempty"`
   177      VmInfo      hyper_proto.VmInfo
   178  }
   179  ```
   180  
   181  See [fm_proto](../../proto/fleetmanager/messages.go) and [hyper_proto](../../proto/hypervisor/messages.go) for sub-schema definitions.