github.com/cloud-foundations/dominator@v0.0.0-20221004181915-6e4fee580046/cmd/hyper-control/README.md (about)

     1  # hyper-control
     2  A utility to manage SmallStack Hypervisors.
     3  
     4  The *hyper-control* utility manages [Hypervisors](../hypervisor/README.md). It
     5  is typically run on a desktop or bastion machine. Please read the
     6  [SmallStack design document](https://bit.ly/SmallStack) to understand the
     7  architecture.
     8  
     9  ## Usage
    10  *hyper-control* supports several sub-commands. There are many command-line flags
    11  which provide parameters for these sub-commands. The most commonly used
    12  parameters are `-fleetManagerHostname` or `-hypervisorHostname` which specify
    13  either the Fleet Manager or a specific *Hypervisor* to communicate with. At
    14  startup, *hyper-control* will read parameters from the
    15  `~/.config/hyper-control/flags.default` and
    16  `~/.config/hyper-control/flags.extra` files. These are simple `name=value`
    17  pairs. The basic usage pattern is:
    18  
    19  ```
    20  hyper-control [flags...] command [args...]
    21  ```
    22  
    23  Built-in help is available with the command:
    24  
    25  ```
    26  hyper-control -h
    27  ```
    28  
    29  Some of the sub-commands available are:
    30  
    31  - **add-address**: manually add a MAC address and IP address pair to a specific
    32                     *Hypervisor*. If the IP address is not specified an external
    33                     DHCP server is required to provides leases to VMs. This
    34                     is only required if a *Fleet Manager* is not available
    35  - **add-subnet**: manually add a subnet to a specific *Hypervisor*. This is only
    36                    required if a *Fleet Manager* is not available
    37  - **change-tags**: change the tags for a specific *Hypervisor*
    38  - **get-machine-info**: get information for a specific *Hypervisor*
    39  - **get-updates**: get and show a continuous stream of updates from a
    40                     *Hypervisor* or *Fleet Manager*. This is primarily for
    41                     debugging
    42  - **installer-shell**: start a remote shell (via SRPC) to the installer running
    43                         on a machine
    44  - **make-installer-iso**: make a bootable installation ISO (CD-ROM) image for a
    45                            machine
    46  - **move-ip-address**: move a (free) IP address to a specific *Hypervisor*
    47  - **netboot-host**: temporarily enable PXE-based network booting and installing
    48                      for a machine
    49  - **netboot-machine**: temporarily enable PXE-based network booting for a
    50                         machine
    51  - **netboot-vm**: create a temporary VM and install with PXE booting. This is
    52                    for debugging physical machine installation
    53  - **power-off**: shut down and power off the specified *Hypervisor*. All VMs
    54                   must be stopped beforehand
    55  - **power-on**: power on the specified *Hypervisor*. This uses remote IPMI or
    56                  Wake On LAN, where available.
    57  - **register-external-leases**: register external DHCP leases with a specific
    58                                  *Hyervisor*. These are lost after a *Hypervisor*
    59                                  restart
    60  - **reinstall**: reinstall the local machine. This erases all data
    61  - **remove-excess-addresses**: remove free addresses for a specific *Hypervisor*
    62                                 above the specified limit
    63  - **remove-ip-address**: remove a (free) IP address from a specific *Hypervisor*
    64  - **remove-mac-address**: remove a (free) MAC address from a specific
    65                            *Hypervisor*
    66  - **rollout-image**: safely roll out specified image to all *Hypervisors* in a
    67                       location
    68  - **write-netboot-files**: write the configuration files for installing a
    69                             machine. This is primarily for debugging
    70  
    71  ## Security
    72  The *Hypervisor* restricts RPC access using TLS client authentication.
    73  *hyper-control* will load certificate and key files from the
    74  `~/.ssl` directory. *hyper-control* will present these certificates to
    75  the *Hypervisor* (or *Fleet Manager*). If one of the certificates is signed by a
    76  certificate authority that the *Hypervisor* trusts, the *Hypervisor* will grant
    77  access.
    78  
    79  ## Installing Hypervisors
    80  The *hyper-control* tool may be used to install *Hypervisors* (OS+Hypervisor) on
    81  physical machines. This requires that information about machines and subnets is
    82  recorded in the topology (usually in Git), which is obtained from the
    83  [Fleet Manager](../fleet-manager/README.md). *Hypervisors* may be installed by
    84  PXE booting an installer, booting from a custom ISO image or installing over a
    85  running system. Please read the
    86  [Machine Birthing design document](../../design-docs/MachineBirthing/README.md)
    87  which describes the principles of installing physical machines.
    88  
    89  ### Network (PXE) Installation
    90  This is the most common method of installing. If there is at least one working
    91  Hypervisor on the same subnet, you can PXE (network) boot. The *hyper-control*
    92  tool is used to automatically select a *Hypervisor* to configure as a PXE server
    93  (it creates a temporary DHCP lease and will serve configuration files via TFTP).
    94  
    95  The following options must be provided:
    96  - `fleetManagerHostname`
    97  - `imageServerHostname`
    98  - `installerImageStream`
    99  
   100  You may want to increase the `-netbootTimeout` option if the machine takes a
   101  long time to boot. Run the following command:
   102  
   103  ```
   104  hyper-control netboot-host $target_host
   105  ```
   106  
   107  Then, initiate a PXE boot for the target machine. It should boot the installer
   108  image, configure and install the machine and then reboot into the new OS. In
   109  principle, multiple machines can be installed in parallel, one machine for each
   110  time the above command is run.
   111  
   112  ### Installing from an ISO (CD-ROM) image
   113  If there is no working *Hypervisor* on the subnet and if there is no DHCP relay
   114  configured to forward DHCP requests to a *Hypervisor* on another subnet, then
   115  another option is to install the machine using a custom ISO (CD-ROM) image. The
   116  ISO image can be written to a CD-ROM, a USB memory drive or served by a NFS/SMB
   117  server (this requires that the machine BIOS supports booting from remote media).
   118  
   119  As above, the same required options must be provided. The following command will
   120  generate a custom ISO image for the target machine. Note that the networking
   121  configuration for the machine is baked into the ISO, so the ISO is only good for
   122  one machine.
   123  
   124  ```
   125  hyper-control make-installer-iso $target_host $destdir
   126  ```
   127  
   128  This will create a custom ISO for this machine in the specified directory, with
   129  both hostname and IP address file entries.
   130  
   131  ### Self installing a Hypervisor
   132  If there is a Linux OS already installed and running on a machine, you can use
   133  the *hyper-control* utility to install a new OS+Hypervisor. This uses the
   134  `kexec` utility to boot directly into the new kernel, skipping the BIOS. This is
   135  a good way of wiping and getting a fresh install.
   136  
   137  As above, the same required options must be provided. Run this command:
   138  
   139  ```
   140  hyper-control reinstall
   141  ```
   142  
   143  This method is much faster, since it skips rebooting via the BIOS the first.
   144  Remember: it wipes all data on the machine!
   145  
   146  ## Upgrading Hypervisors
   147  Upgrading *Hypervisors* is done using the *hyper-control* tool. This sets the
   148  `RequiredImage` tag on *Hypervisors* in the specified location. The rollout is
   149  controlled, starting slow and gaining speed as *Hypervisors* complete upgrades
   150  and remain healthy. The upgrade may include a new kernel, in which case the
   151  machine will be rebooted as part of the upgrade, thus taking several minutes for
   152  the per-machine upgrade+health check cycle to complete (compared to less than
   153  one minute for most upgrades). The actual upgrades are performed by the
   154  [dominator](../dominator/README.md) which reads the tags to determine the image
   155  to push to the machine. Once the rollout is complete, the new tags are saved by
   156  committing to the Git repository containing the topology.
   157  
   158  The following options must be provided:
   159  - `fleetManagerHostname`
   160  - `imageServerHostname`
   161  - `location`
   162  - `topologyDir`
   163  
   164  To rollout a new *Hypervisor* image to all the *Hypervisors* in the specified
   165  location, run a command like this:
   166  
   167  ```
   168  hyper-control rollout-image $image_name
   169  ```