qm-cloud-init.adoc

   1 [[qm_cloud_init]]
   2 Cloud-Init Support
   3 ------------------
   4 ifdef::wiki[]
   5 :pve-toplevel:
   6 endif::wiki[]
   7
   8 http://cloudinit.readthedocs.io[Cloud-Init] is the defacto
   9 multi-distribution package that handles early initialization of a
  10 virtual machine instance. Using Cloud-Init, configuration of network
  11 devices and ssh keys on the hypervisor side is possible. When the VM
  12 starts for the first time, the Cloud-Init software inside the VM will
  13 apply those settings.
  14
  15 Many Linux distributions provide ready-to-use Cloud-Init images, mostly
  16 designed for 'OpenStack'. These images will also work with {pve}. While
  17 it may seem convenient to get such ready-to-use images, we usually
  18 recommended to prepare the images by yourself. The advantage is that you
  19 will know exactly what you have installed, and this helps you later to
  20 easily customize the image for your needs.
  21
  22 Once you have created such a Cloud-Init image we recommend to convert it
  23 into a VM template. From a VM template you can quickly create linked
  24 clones, so this is a fast method to roll out new VM instances. You just
  25 need to configure the network (and maybe the ssh keys) before you start
  26 the new VM.
  27
  28 We recommend using SSH key-based authentication to login to the VMs
  29 provisioned by Cloud-Init. It is also possible to set a password, but
  30 this is not as safe as using SSH key-based authentication because {pve}
  31 needs to store an encrypted version of that password inside the
  32 Cloud-Init data.
  33
  34 {pve} generates an ISO image to pass the Cloud-Init data to the VM. For
  35 that purpose all Cloud-Init VMs need to have an assigned CDROM drive.
  36 Also many Cloud-Init images assume to have a serial console, so it is
  37 recommended to add a serial console and use it as display for those VMs.
  38
  39
  40 Preparing Cloud-Init Templates
  41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  42
  43 The first step is to prepare your VM. Basically you can use any VM.
  44 Simply install the Cloud-Init packages inside the VM that you want to
  45 prepare. On Debian/Ubuntu based systems this is as simple as:
  46
  47 ----
  48 apt-get install cloud-init
  49 ----
  50
  51 Already many distributions provide ready-to-use Cloud-Init images (provided
  52 as `.qcow2` files), so alternatively you can simply download and
  53 import such images. For the following example, we will use the cloud
  54 image provided by Ubuntu at https://cloud-images.ubuntu.com.
  55
  56 ----
  57 # download the image
  58 wget https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img
  59
  60 # create a new VM
  61 qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0
  62
  63 # import the downloaded disk to local-lvm storage
  64 qm importdisk 9000 bionic-server-cloudimg-amd64.img local-lvm
  65
  66 # finally attach the new disk to the VM as scsi drive
  67 qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-1
  68 ----
  69
  70 NOTE: Ubuntu Cloud-Init images require the `virtio-scsi-pci`
  71 controller type for SCSI drives.
  72
  73 .Add Cloud-Init CDROM drive
  74
  75 [thumbnail="screenshot/gui-cloudinit-hardware.png"]
  76
  77 The next step is to configure a CDROM drive which will be used to pass
  78 the Cloud-Init data to the VM.
  79
  80 ----
  81 qm set 9000 --ide2 local-lvm:cloudinit
  82 ----
  83
  84 To be able to boot directly from the Cloud-Init image, set the
  85 `bootdisk` parameter to `scsi0`, and restrict BIOS to boot from disk
  86 only. This will speed up booting, because VM BIOS skips the testing for
  87 a bootable CDROM.
  88
  89 ----
  90 qm set 9000 --boot c --bootdisk scsi0
  91 ----
  92
  93 Also configure a serial console and use it as a display. Many Cloud-Init
  94 images rely on this, as it is an requirement for OpenStack images.
  95
  96 ----
  97 qm set 9000 --serial0 socket --vga serial0
  98 ----
  99
 100 In a last step, it is helpful to convert the VM into a template. From
 101 this template you can then quickly create linked clones.
 102 The deployment from VM templates is much faster than creating a full
 103 clone (copy).
 104 ----
 105 qm template 9000
 106 ----
 107
 108
 109 Deploying Cloud-Init Templates
 110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 111
 112 [thumbnail="screenshot/gui-cloudinit-config.png"]
 113
 114 You can easily deploy such a template by cloning:
 115
 116 ----
 117 qm clone 9000 123 --name ubuntu2
 118 ----
 119
 120 Then configure the SSH public key used for authentication, and configure
 121 the IP setup:
 122
 123 ----
 124 qm set 123 --sshkey ~/.ssh/id_rsa.pub
 125 qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1
 126 ----
 127
 128 You can also configure all the Cloud-Init options using a single command
 129 only. We have simply splitted the above example to separate the
 130 commands for reducing the line length. Also make sure to adopt the IP
 131 setup for your specific environment.
 132
 133
 134 Custom Cloud-Init Configuration
 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 136
 137 The Cloud-Init integration also allows custom config files to be used instead
 138 of the automatically generated configs. This is done via the `cicustom`
 139 option on the command line:
 140
 141 ----
 142 qm set 9000 --cicustom "user=<volume>,network=<volume>,meta=<volume>"
 143 ----
 144
 145 The custom config files have to be on a storage that supports snippets and have
 146 to be available on all nodes the VM is going to be migrated to. Otherwise the
 147 VM won't be able to start.
 148 For example:
 149
 150 ----
 151 qm set 9000 --cicustom "user=local:snippets/userconfig.yaml"
 152 ----
 153
 154 There are three kinds of configs for Cloud-Init. The first one is the `user`
 155 config as seen in the example above. The second is the `network` config and
 156 the third the `meta` config. They can all be specified together or mixed
 157 and matched however needed.
 158 The automatically generated config will be used for any that don't have a
 159 custom config file specified.
 160
 161 The generated config can be dumped to serve as a base for custom configs:
 162
 163 ----
 164 qm cloudinit dump 9000 user
 165 ----
 166
 167 The same command exists for `network` and `meta`.
 168
 169
 170 Cloud-Init specific Options
 171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 172
 173 include::qm-cloud-init-opts.adoc[]
 174
 175
 176 ifdef::wiki[]
 177
 178 See Also
 179 ~~~~~~~~
 180
 181 * link:/wiki/Qemu/KVM_Virtual_Machines[Qemu/KVM Virtual Machines]
 182
 183 endif::wiki[]