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