From 7eb69fd2b7da99cf24f94e8f5c66136d05a99140 Mon Sep 17 00:00:00 2001 From: Dietmar Maurer Date: Thu, 8 Mar 2018 13:32:13 +0100 Subject: [PATCH] split out cloud-init docs, make it available as wiki page --- qm-cloud-init.adoc | 131 ++++++++++++++++++++++++++++++++++++++++++++ qm.adoc | 133 +-------------------------------------------- 2 files changed, 134 insertions(+), 130 deletions(-) create mode 100644 qm-cloud-init.adoc diff --git a/qm-cloud-init.adoc b/qm-cloud-init.adoc new file mode 100644 index 0000000..cfac011 --- /dev/null +++ b/qm-cloud-init.adoc @@ -0,0 +1,131 @@ +[[qm_cloud_init]] +Cloud-Init Support +------------------ +ifdef::wiki[] +:pve-toplevel: +endif::wiki[] + +http://cloudinit.readthedocs.io[Cloud-Init] is the defacto +multi-distribution package that handles early initialization of a +virtual machine instance. Using Cloud-Init, one can configure network +devices and ssh keys on the hypervisor side. When the VM starts the +first time, the Cloud-Init software inside the VM applies those +settings. + +Many Linux distributions provides ready-to-use Cloud-Init images, +mostly designed for 'OpenStack'. Those images also works with +{pve}. While it may be convenient to use such read-to-use images, we +usually recommend to prepare those images by yourself. That way you know +exactly what is installed, and you can easily customize the image for +your needs. + +Once you created such image, it is best practice to convert it into a +VM template. It is really fast to create linked clones of VM +templates, so this is a very fast way to roll out new VM +instances. You just need to configure the network (any maybe ssh keys) +before you start the new VM. + +We recommend the use of SSH key-based authentication to login to VMs +provisioned by Cloud-Init. It is also possible to set a password, but +{pve} needs to store an encrypted version of that password inside the +Cloud-Init data. So this is not as safe as using SSH key-based +authentication. + +{pve} generates an ISO image to pass the Cloud-Init data to the VM. So +all Cloud-Init VMs needs to have an assigned CDROM drive for that +purpose. Also, many Cloud-Init Images assumes to have a serial +console, so it is best to add a serial console and use that as display +for those VMs. + + +Prepare Cloud-Init Templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first step is to prepare your VM. You can basically use any VM, +and simply install the Cloud-Init packages inside the VM you want to +prepare. On Debian/Ubuntu based systems this is as simple as: + +---- +apt-get install cloud-init +---- + +Many distributions provides ready-to-use Cloud-Init images (provided +as `.qcow2` files), so as alternative you can simply download and +import such image. For the following example, we will use the cloud +images 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 + +# 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 +---- + +NOTE: Ubuntu Cloud-Init images requires the `virtio-scsi-pci` +controller type for SCSI drives. + + +The next step is to configure a CDROM drive, used to pass the +Cloud-Init data to the VM. + +---- +qm set 9000 --ide2 local-lvm:cloudinit +---- + +We want to boot directly from the Cloud-Init image, so we set the +`bootdisk` parameter to `scsi0` and restrict BIOS to boot from disk +only. This simply speeds up booting, because VM BIOS skips testing for +a bootable CDROM. + +---- +qm set 9000 --boot c --bootdisk scsi0 +---- + +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. + +---- +qm set 9000 --serial0 socket --vga serial0 +---- + +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). + +---- +qm template 9000 +---- + + +Deploy Cloud-Init Templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can easily deploy such template by cloning: + +---- +qm clone 9000 123 --name ubuntu2 +---- + +Then configure the SSH public key used for authentication, and the IP setup + +---- +qm set 123 --sshkey ~/.ssh/id_rsa.pub +qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1 +---- + +You can configure all Cloud-Init options using a single command. I +just split above example to separate commands to reduce the line +length. Also make sure you adopt the IP setup for your environment. + + +Cloud-Init specific Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +include::qm-cloud-init-opts.adoc[] + + + diff --git a/qm.adoc b/qm.adoc index 7227510..154c5c1 100644 --- a/qm.adoc +++ b/qm.adoc @@ -537,136 +537,6 @@ process a great number of incoming connections, such as when the VM is running as a router, reverse proxy or a busy HTTP server doing long polling. -[[qm_cloud_init]] -Cloud-Init Support -~~~~~~~~~~~~~~~~~~ - -http://cloudinit.readthedocs.io[Cloud-Init] is the defacto -multi-distribution package that handles early initialization of a -virtual machine instance. Using Cloud-Init, one can configure network -devices and ssh keys on the hypervisor side. When the VM starts the -first time, the Cloud-Init software inside the VM applies those -settings. - -Many Linux distributions provides ready-to-use Cloud-Init images, -mostly designed for 'OpenStack'. Those images also works with -{pve}. While it may be convenient to use such read-to-use images, we -usually recommend to prepare those images by yourself. That way you know -exactly what is installed, and you can easily customize the image for -your needs. - -Once you created such image, it is best practice to convert it into a -VM template. It is really fast to create linked clones of VM -templates, so this is a very fast way to roll out new VM -instances. You just need to configure the network (any maybe ssh keys) -before you start the new VM. - -We recommend the use of SSH key-based authentication to login to VMs -provisioned by Cloud-Init. It is also possible to set a password, but -{pve} needs to store an encrypted version of that password inside the -Cloud-Init data. So this is not as safe as using SSH key-based -authentication. - -{pve} generates an ISO image to pass the Cloud-Init data to the VM. So -all Cloud-Init VMs needs to have an assigned CDROM drive for that -purpose. Also, many Cloud-Init Images assumes to have a serial -console, so it is best to add a serial console and use that as display -for those VMs. - - -Prepare Cloud-Init Templates -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The first step is to prepare your VM. You can basically use any VM, -and simply install the Cloud-Init packages inside the VM you want to -prepare. On Debian/Ubuntu based systems this is as simple as: - ----- -apt-get install cloud-init ----- - -Many distributions provides ready-to-use Cloud-Init images (provided -as `.qcow2` files), so as alternative you can simply download and -import such image. For the following example, we will use the cloud -images 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 - -# 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 ----- - -NOTE: Ubuntu Cloud-Init images requires the `virtio-scsi-pci` -controller type for SCSI drives. - - -The next step is to configure a CDROM drive, used to pass the -Cloud-Init data to the VM. - ----- -qm set 9000 --ide2 local-lvm:cloudinit ----- - -We want to boot directly from the Cloud-Init image, so we set the -`bootdisk` parameter to `scsi0` and restrict BIOS to boot from disk -only. This simply speeds up booting, because VM BIOS skips testing for -a bootable CDROM. - ----- -qm set 9000 --boot c --bootdisk scsi0 ----- - -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. - ----- -qm set 9000 --serial0 socket --vga serial0 ----- - -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). - ----- -qm template 9000 ----- - - -Deploy Cloud-Init Templates -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can easily deploy such template by cloning: - ----- -qm clone 9000 123 --name ubuntu2 ----- - -Then configure the SSH public key used for authentication, and the IP setup - ----- -qm set 123 --sshkey ~/.ssh/id_rsa.pub -qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1 ----- - -You can configure all Cloud-Init options using a single command. I -just split above example to separate commands to reduce the line -length. Also make sure you adopt the IP setup for your environment. - - -Cloud-Init specific Options -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - - -include::qm-cloud-init-opts.adoc[] - - - [[qm_usb_passthrough]] USB Passthrough ~~~~~~~~~~~~~~~ @@ -1013,6 +883,9 @@ Finally attach the unused disk to the SCSI controller of the VM: The VM is ready to be started. + +include::qm-cloud-init.adoc[] + Managing Virtual Machines with `qm` ------------------------------------ -- 2.39.2