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 The next step is to configure a CDROM drive, used to pass the
  76 Cloud-Init data to the VM.
  77
  78 ----
  79 qm set 9000 --ide2 local-lvm:cloudinit
  80 ----
  81
  82 We want to boot directly from the Cloud-Init image, so we set the
  83 `bootdisk` parameter to `scsi0` and restrict BIOS to boot from disk
  84 only. This simply speeds up booting, because VM BIOS skips testing for
  85 a bootable CDROM.
  86
  87 ----
  88 qm set 9000 --boot c --bootdisk scsi0
  89 ----
  90
  91 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.
  92
  93 ----
  94 qm set 9000 --serial0 socket --vga serial0
  95 ----
  96
  97 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).
  98
  99 ----
 100 qm template 9000
 101 ----
 102
 103
 104 Deploy Cloud-Init Templates
 105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 106
 107 You can easily deploy such template by cloning:
 108
 109 ----
 110 qm clone 9000 123 --name ubuntu2
 111 ----
 112
 113 Then configure the SSH public key used for authentication, and the IP setup
 114
 115 ----
 116 qm set 123 --sshkey ~/.ssh/id_rsa.pub
 117 qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1
 118 ----
 119
 120 You can configure all Cloud-Init options using a single command. I
 121 just split above example to separate commands to reduce the line
 122 length. Also make sure you adopt the IP setup for your environment.
 123
 124
 125 Cloud-Init specific Options
 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 127
 128 include::qm-cloud-init-opts.adoc[]
 129
 130
 131