X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=qm-cloud-init.adoc;h=b275d7a79083181e61c9927cfdcc3b7ad3abf2ee;hb=0031ebd89c7cc703500139d9142e47abc5d5cd8a;hp=9ab98da0be26c997e4831c949b5652a01bc71296;hpb=85d697af2b25de0386dda10d28de545c2e41bf87;p=pve-docs.git diff --git a/qm-cloud-init.adoc b/qm-cloud-init.adoc index 9ab98da..b275d7a 100644 --- a/qm-cloud-init.adoc +++ b/qm-cloud-init.adoc @@ -5,7 +5,7 @@ ifdef::wiki[] :pve-toplevel: endif::wiki[] -http://cloudinit.readthedocs.io[Cloud-Init] is the defacto +https://cloudinit.readthedocs.io[Cloud-Init] is the de facto multi-distribution package that handles early initialization of a virtual machine instance. Using Cloud-Init, configuration of network devices and ssh keys on the hypervisor side is possible. When the VM @@ -32,13 +32,15 @@ needs to store an encrypted version of that password inside the Cloud-Init data. {pve} generates an ISO image to pass the Cloud-Init data to the VM. For -that purpose all Cloud-Init VMs need to have an assigned CDROM drive. -Also many Cloud-Init images assume to have a serial console, so it is -recommended to add a serial console and use it as display for those VMs. +that purpose, all Cloud-Init VMs need to have an assigned CD-ROM drive. +Usually, a serial console should be added and used as a display. Many Cloud-Init +images rely on this, it is a requirement for OpenStack. However, other images +might have problems with this configuration. Switch back to the default display +configuration if using a serial console doesn't work. Preparing Cloud-Init Templates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The first step is to prepare your VM. Basically you can use any VM. Simply install the Cloud-Init packages inside the VM that you want to @@ -48,6 +50,9 @@ prepare. On Debian/Ubuntu based systems this is as simple as: apt-get install cloud-init ---- +WARNING: This command is *not* intended to be executed on the {pve} host, but +only inside the VM. + Already many distributions provide ready-to-use Cloud-Init images (provided as `.qcow2` files), so alternatively you can simply download and import such images. For the following example, we will use the cloud @@ -57,41 +62,38 @@ image provided by Ubuntu at https://cloud-images.ubuntu.com. # download the image wget https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img -# create a new VM -qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 - -# import the downloaded disk to local-lvm storage -qm importdisk 9000 bionic-server-cloudimg-amd64.img local-lvm +# create a new VM with VirtIO SCSI controller +qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci -# finally attach the new disk to the VM as scsi drive -qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-1 +# import the downloaded disk to the local-lvm storage, attaching it as a SCSI drive +qm set 9000 --scsi0 local-lvm:0,import-from=/path/to/bionic-server-cloudimg-amd64.img ---- NOTE: Ubuntu Cloud-Init images require the `virtio-scsi-pci` controller type for SCSI drives. -.Add Cloud-Init CDROM drive +.Add Cloud-Init CD-ROM drive -[thumbnail="gui-cloudinit-hardware.png"] +[thumbnail="screenshot/gui-cloudinit-hardware.png"] -The next step is to configure a CDROM drive which will be used to pass +The next step is to configure a CD-ROM drive, which will be used to pass the Cloud-Init data to the VM. ---- qm set 9000 --ide2 local-lvm:cloudinit ---- -To be able to boot directly from the Cloud-Init image, set the -`bootdisk` parameter to `scsi0`, and restrict BIOS to boot from disk -only. This will speed up booting, because VM BIOS skips the testing for -a bootable CDROM. +To be able to boot directly from the Cloud-Init image, set the `boot` parameter +to `order=scsi0` to restrict BIOS to boot from this disk only. This will speed +up booting, because VM BIOS skips the testing for a bootable CD-ROM. ---- -qm set 9000 --boot c --bootdisk scsi0 +qm set 9000 --boot order=scsi0 ---- -Also configure a serial console and use it as a display. Many Cloud-Init -images rely on this, as it is an requirement for OpenStack images. +For many Cloud-Init images, it is required to configure a serial console and use +it as a display. If the configuration doesn't work for a given image however, +switch back to the default display instead. ---- qm set 9000 --serial0 socket --vga serial0 @@ -107,9 +109,9 @@ qm template 9000 Deploying Cloud-Init Templates -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -[thumbnail="gui-cloudinit-config.png"] +[thumbnail="screenshot/gui-cloudinit-config.png"] You can easily deploy such a template by cloning: @@ -126,12 +128,58 @@ qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1 ---- You can also configure all the Cloud-Init options using a single command -only. We have simply splitted the above example to separate the +only. We have simply split the above example to separate the commands for reducing the line length. Also make sure to adopt the IP setup for your specific environment. +Custom Cloud-Init Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Cloud-Init integration also allows custom config files to be used instead +of the automatically generated configs. This is done via the `cicustom` +option on the command line: + +---- +qm set 9000 --cicustom "user=,network=,meta=" +---- + +The custom config files have to be on a storage that supports snippets and have +to be available on all nodes the VM is going to be migrated to. Otherwise the +VM won't be able to start. +For example: + +---- +qm set 9000 --cicustom "user=local:snippets/userconfig.yaml" +---- + +There are three kinds of configs for Cloud-Init. The first one is the `user` +config as seen in the example above. The second is the `network` config and +the third the `meta` config. They can all be specified together or mixed +and matched however needed. +The automatically generated config will be used for any that don't have a +custom config file specified. + +The generated config can be dumped to serve as a base for custom configs: + +---- +qm cloudinit dump 9000 user +---- + +The same command exists for `network` and `meta`. + + Cloud-Init specific Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ include::qm-cloud-init-opts.adoc[] + + +ifdef::wiki[] + +See Also +~~~~~~~~ + +* link:/wiki/Qemu/KVM_Virtual_Machines[Qemu/KVM Virtual Machines] + +endif::wiki[]