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, one can configure network
  11 devices and ssh keys on the hypervisor side. When the VM starts the
  12 first time, the Cloud-Init software inside the VM applies those
  13 settings.
  14
  15 Many Linux distributions provides ready-to-use Cloud-Init images,
  16 mostly designed for 'OpenStack'. Those images also works with
  17 {pve}. While it may be convenient to use such read-to-use images, we
  18 usually recommend to prepare those images by yourself. That way you know
  19 exactly what is installed, and you can easily customize the image for
  20 your needs.
  21
  22 Once you created such image, it is best practice to convert it into a
  23 VM template. It is really fast to create linked clones of VM
  24 templates, so this is a very fast way to roll out new VM
  25 instances. You just need to configure the network (any maybe ssh keys)
  26 before you start the new VM.
  27
  28 We recommend the use of SSH key-based authentication to login to VMs
  29 provisioned by Cloud-Init. It is also possible to set a password, but
  30 {pve} needs to store an encrypted version of that password inside the
  31 Cloud-Init data. So this is not as safe as using SSH key-based
  32 authentication.
  33
  34 {pve} generates an ISO image to pass the Cloud-Init data to the VM. So
  35 all Cloud-Init VMs needs to have an assigned CDROM drive for that
  36 purpose. Also, many Cloud-Init Images assumes to have a serial
  37 console, so it is best to add a serial console and use that as display
  38 for those VMs.
  39
  40
  41 Prepare Cloud-Init Templates
  42 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  43
  44 The first step is to prepare your VM. You can basically use any VM,
  45 and simply install the Cloud-Init packages inside the VM you want to
  46 prepare. On Debian/Ubuntu based systems this is as simple as:
  47
  48 ----
  49 apt-get install cloud-init
  50 ----
  51
  52 Many distributions provides ready-to-use Cloud-Init images (provided
  53 as `.qcow2` files), so as alternative you can simply download and
  54 import such image. For the following example, we will use the cloud
  55 images provided by Ubuntu at https://cloud-images.ubuntu.com.
  56
  57 ----
  58 # download the image
  59 wget https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img
  60
  61 # create a new VM
  62 qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0
  63
  64 # import the downloaded disk to local-lvm storage
  65 qm importdisk 9000 bionic-server-cloudimg-amd64.img local-lvm
  66
  67 # finally attach the new disk to the VM as scsi drive
  68 qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-1
  69 ----
  70
  71 NOTE: Ubuntu Cloud-Init images requires the `virtio-scsi-pci`
  72 controller type for SCSI drives.
  73
  74
  75 .Add Cloud-Init CDROM drive
  76
  77 [thumbnail="gui-cloudinit-hardware.png"]
  78
  79 The next step is to configure a CDROM drive, used to pass the
  80 Cloud-Init data to the VM.
  81
  82 ----
  83 qm set 9000 --ide2 local-lvm:cloudinit
  84 ----
  85
  86 We want to boot directly from the Cloud-Init image, so we set the
  87 `bootdisk` parameter to `scsi0` and restrict BIOS to boot from disk
  88 only. This simply speeds up booting, because VM BIOS skips testing for
  89 a bootable CDROM.
  90
  91 ----
  92 qm set 9000 --boot c --bootdisk scsi0
  93 ----
  94
  95 We also want to configure a serial console and use that as display. Many Cloud-Init images rely on that, because it is an requirement for OpenStack images.
  96
  97 ----
  98 qm set 9000 --serial0 socket --vga serial0
  99 ----
 100
 101 Finally, it is usually a good idea to transform such VM into a template. You can create linked clones with them, so deployment from VM templates is much faster than creating a full clone (copy).
 102
 103 ----
 104 qm template 9000
 105 ----
 106
 107
 108 Deploy Cloud-Init Templates
 109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 110
 111 [thumbnail="gui-cloudinit-config.png"]
 112
 113 You can easily deploy such template by cloning:
 114
 115 ----
 116 qm clone 9000 123 --name ubuntu2
 117 ----
 118
 119 Then configure the SSH public key used for authentication, and the IP setup
 120
 121 ----
 122 qm set 123 --sshkey ~/.ssh/id_rsa.pub
 123 qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1
 124 ----
 125
 126 You can configure all Cloud-Init options using a single command. I
 127 just split above example to separate commands to reduce the line
 128 length. Also make sure you adopt the IP setup for your environment.
 129
 130
 131
 132 Cloud-Init specific Options
 133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 134
 135 include::qm-cloud-init-opts.adoc[]
 136
 137
 138