qm-cloud-init.adoc

   1 [[qm_cloud_init]]
   2 Cloud-Init Support
   3 ------------------
   4 ifdef::wiki[]
   5 :pve-toplevel:
   6 endif::wiki[]
   7
   8 https://cloudinit.readthedocs.io[Cloud-Init] is the de facto
   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 CD-ROM drive.
  36 Usually, a serial console should be added and used as a display. Many Cloud-Init
  37 images rely on this, it is a requirement for OpenStack. However, other images
  38 might have problems with this configuration. Switch back to the default display
  39 configuration if using a serial console doesn't work.
  40
  41
  42 Preparing Cloud-Init Templates
  43 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  44
  45 The first step is to prepare your VM. Basically you can use any VM.
  46 Simply install the Cloud-Init packages *inside the VM* that you want to
  47 prepare. On Debian/Ubuntu based systems this is as simple as:
  48
  49 ----
  50 apt-get install cloud-init
  51 ----
  52
  53 WARNING: This command is *not* intended to be executed on the {pve} host, but
  54 only inside the VM.
  55
  56 Already many distributions provide ready-to-use Cloud-Init images (provided
  57 as `.qcow2` files), so alternatively you can simply download and
  58 import such images. For the following example, we will use the cloud
  59 image provided by Ubuntu at https://cloud-images.ubuntu.com.
  60
  61 ----
  62 # download the image
  63 wget https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img
  64
  65 # create a new VM with VirtIO SCSI controller
  66 qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci
  67
  68 # import the downloaded disk to the local-lvm storage, attaching it as a SCSI drive
  69 qm set 9000 --scsi0 local-lvm:0,import-from=/path/to/bionic-server-cloudimg-amd64.img
  70 ----
  71
  72 NOTE: Ubuntu Cloud-Init images require the `virtio-scsi-pci`
  73 controller type for SCSI drives.
  74
  75 .Add Cloud-Init CD-ROM drive
  76
  77 [thumbnail="screenshot/gui-cloudinit-hardware.png"]
  78
  79 The next step is to configure a CD-ROM drive, which will be used to pass
  80 the Cloud-Init data to the VM.
  81
  82 ----
  83 qm set 9000 --ide2 local-lvm:cloudinit
  84 ----
  85
  86 To be able to boot directly from the Cloud-Init image, set the `boot` parameter
  87 to `order=scsi0` to restrict BIOS to boot from this disk only. This will speed
  88 up booting, because VM BIOS skips the testing for a bootable CD-ROM.
  89
  90 ----
  91 qm set 9000 --boot order=scsi0
  92 ----
  93
  94 For many Cloud-Init images, it is required to configure a serial console and use
  95 it as a display. If the configuration doesn't work for a given image however,
  96 switch back to the default display instead.
  97
  98 ----
  99 qm set 9000 --serial0 socket --vga serial0
 100 ----
 101
 102 In a last step, it is helpful to convert the VM into a template. From
 103 this template you can then quickly create linked clones.
 104 The deployment from VM templates is much faster than creating a full
 105 clone (copy).
 106 ----
 107 qm template 9000
 108 ----
 109
 110
 111 Deploying Cloud-Init Templates
 112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 113
 114 [thumbnail="screenshot/gui-cloudinit-config.png"]
 115
 116 You can easily deploy such a template by cloning:
 117
 118 ----
 119 qm clone 9000 123 --name ubuntu2
 120 ----
 121
 122 Then configure the SSH public key used for authentication, and configure
 123 the IP setup:
 124
 125 ----
 126 qm set 123 --sshkey ~/.ssh/id_rsa.pub
 127 qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1
 128 ----
 129
 130 You can also configure all the Cloud-Init options using a single command
 131 only. We have simply split the above example to separate the
 132 commands for reducing the line length. Also make sure to adopt the IP
 133 setup for your specific environment.
 134
 135
 136 Custom Cloud-Init Configuration
 137 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 138
 139 The Cloud-Init integration also allows custom config files to be used instead
 140 of the automatically generated configs. This is done via the `cicustom`
 141 option on the command line:
 142
 143 ----
 144 qm set 9000 --cicustom "user=<volume>,network=<volume>,meta=<volume>"
 145 ----
 146
 147 The custom config files have to be on a storage that supports snippets and have
 148 to be available on all nodes the VM is going to be migrated to. Otherwise the
 149 VM won't be able to start.
 150 For example:
 151
 152 ----
 153 qm set 9000 --cicustom "user=local:snippets/userconfig.yaml"
 154 ----
 155
 156 There are three kinds of configs for Cloud-Init. The first one is the `user`
 157 config as seen in the example above. The second is the `network` config and
 158 the third the `meta` config. They can all be specified together or mixed
 159 and matched however needed.
 160 The automatically generated config will be used for any that don't have a
 161 custom config file specified.
 162
 163 The generated config can be dumped to serve as a base for custom configs:
 164
 165 ----
 166 qm cloudinit dump 9000 user
 167 ----
 168
 169 The same command exists for `network` and `meta`.
 170
 171
 172 Cloud-Init specific Options
 173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 174
 175 include::qm-cloud-init-opts.adoc[]
 176
 177
 178 ifdef::wiki[]
 179
 180 See Also
 181 ~~~~~~~~
 182
 183 * link:/wiki/Qemu/KVM_Virtual_Machines[Qemu/KVM Virtual Machines]
 184
 185 endif::wiki[]