You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

184 lines

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