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