]>
Commit | Line | Data |
---|---|---|
7eb69fd2 DM |
1 | [[qm_cloud_init]] |
2 | Cloud-Init Support | |
3 | ------------------ | |
4 | ifdef::wiki[] | |
5 | :pve-toplevel: | |
6 | endif::wiki[] | |
7 | ||
a55d30db | 8 | https://cloudinit.readthedocs.io[Cloud-Init] is the de facto |
7eb69fd2 | 9 | multi-distribution package that handles early initialization of a |
85d697af TL |
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 | |
7eb69fd2 | 29 | provisioned by Cloud-Init. It is also possible to set a password, but |
85d697af TL |
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. | |
7eb69fd2 | 33 | |
85d697af | 34 | {pve} generates an ISO image to pass the Cloud-Init data to the VM. For |
3a433e9b | 35 | that purpose, all Cloud-Init VMs need to have an assigned CD-ROM drive. |
2050eb19 FE |
36 | Usually, a serial console should be added and used as a display. Many Cloud-Init |
37 | images rely on this, it is a requirement for OpenStack. However, other images | |
38 | might have problems with this configuration. Switch back to the default display | |
39 | configuration if using a serial console doesn't work. | |
7eb69fd2 DM |
40 | |
41 | ||
85d697af | 42 | Preparing Cloud-Init Templates |
a3cc9331 | 43 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
7eb69fd2 | 44 | |
85d697af TL |
45 | The first step is to prepare your VM. Basically you can use any VM. |
46 | Simply install the Cloud-Init packages inside the VM that you want to | |
7eb69fd2 DM |
47 | prepare. On Debian/Ubuntu based systems this is as simple as: |
48 | ||
49 | ---- | |
50 | apt-get install cloud-init | |
51 | ---- | |
52 | ||
88cb1214 FE |
53 | WARNING: This command is *not* intended to be executed on the {pve} host, but |
54 | only inside the VM. | |
55 | ||
85d697af TL |
56 | Already many distributions provide ready-to-use Cloud-Init images (provided |
57 | as `.qcow2` files), so alternatively you can simply download and | |
58 | import such images. For the following example, we will use the cloud | |
59 | image provided by Ubuntu at https://cloud-images.ubuntu.com. | |
7eb69fd2 DM |
60 | |
61 | ---- | |
62 | # download the image | |
63 | wget https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img | |
64 | ||
e33a118a FE |
65 | # create a new VM with VirtIO SCSI controller |
66 | qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci | |
7eb69fd2 | 67 | |
e33a118a FE |
68 | # import the downloaded disk to the local-lvm storage, attaching it as a SCSI drive |
69 | qm set 9000 --scsi0 local-lvm:0,import-from=/path/to/bionic-server-cloudimg-amd64.img | |
7eb69fd2 DM |
70 | ---- |
71 | ||
85d697af | 72 | NOTE: Ubuntu Cloud-Init images require the `virtio-scsi-pci` |
7eb69fd2 DM |
73 | controller type for SCSI drives. |
74 | ||
3a433e9b | 75 | .Add Cloud-Init CD-ROM drive |
d528c7ba | 76 | |
1ff5e4e8 | 77 | [thumbnail="screenshot/gui-cloudinit-hardware.png"] |
d528c7ba | 78 | |
3a433e9b | 79 | The next step is to configure a CD-ROM drive, which will be used to pass |
85d697af | 80 | the Cloud-Init data to the VM. |
7eb69fd2 DM |
81 | |
82 | ---- | |
83 | qm set 9000 --ide2 local-lvm:cloudinit | |
84 | ---- | |
85 | ||
44562c3b FE |
86 | To be able to boot directly from the Cloud-Init image, set the `boot` parameter |
87 | to `order=scsi0` to restrict BIOS to boot from this disk only. This will speed | |
88 | up booting, because VM BIOS skips the testing for a bootable CD-ROM. | |
7eb69fd2 DM |
89 | |
90 | ---- | |
44562c3b | 91 | qm set 9000 --boot order=scsi0 |
7eb69fd2 DM |
92 | ---- |
93 | ||
2050eb19 FE |
94 | For many Cloud-Init images, it is required to configure a serial console and use |
95 | it as a display. If the configuration doesn't work for a given image however, | |
96 | switch back to the default display instead. | |
7eb69fd2 DM |
97 | |
98 | ---- | |
99 | qm set 9000 --serial0 socket --vga serial0 | |
100 | ---- | |
101 | ||
85d697af TL |
102 | In a last step, it is helpful to convert the VM into a template. From |
103 | this template you can then quickly create linked clones. | |
104 | The deployment from VM templates is much faster than creating a full | |
105 | clone (copy). | |
7eb69fd2 DM |
106 | ---- |
107 | qm template 9000 | |
108 | ---- | |
109 | ||
110 | ||
85d697af | 111 | Deploying Cloud-Init Templates |
a3cc9331 | 112 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
7eb69fd2 | 113 | |
1ff5e4e8 | 114 | [thumbnail="screenshot/gui-cloudinit-config.png"] |
d528c7ba | 115 | |
85d697af | 116 | You can easily deploy such a template by cloning: |
7eb69fd2 DM |
117 | |
118 | ---- | |
119 | qm clone 9000 123 --name ubuntu2 | |
120 | ---- | |
121 | ||
85d697af TL |
122 | Then configure the SSH public key used for authentication, and configure |
123 | the IP setup: | |
7eb69fd2 DM |
124 | |
125 | ---- | |
126 | qm set 123 --sshkey ~/.ssh/id_rsa.pub | |
127 | qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1 | |
128 | ---- | |
129 | ||
85d697af | 130 | You can also configure all the Cloud-Init options using a single command |
5f318cc0 | 131 | only. We have simply split the above example to separate the |
85d697af TL |
132 | commands for reducing the line length. Also make sure to adopt the IP |
133 | setup for your specific environment. | |
7eb69fd2 | 134 | |
d528c7ba | 135 | |
a3e7e4e3 ML |
136 | Custom Cloud-Init Configuration |
137 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
138 | ||
139 | The Cloud-Init integration also allows custom config files to be used instead | |
140 | of the automatically generated configs. This is done via the `cicustom` | |
141 | option on the command line: | |
142 | ||
143 | ---- | |
144 | qm set 9000 --cicustom "user=<volume>,network=<volume>,meta=<volume>" | |
145 | ---- | |
146 | ||
147 | The custom config files have to be on a storage that supports snippets and have | |
148 | to be available on all nodes the VM is going to be migrated to. Otherwise the | |
149 | VM won't be able to start. | |
150 | For example: | |
151 | ||
152 | ---- | |
153 | qm set 9000 --cicustom "user=local:snippets/userconfig.yaml" | |
154 | ---- | |
155 | ||
156 | There are three kinds of configs for Cloud-Init. The first one is the `user` | |
157 | config as seen in the example above. The second is the `network` config and | |
158 | the third the `meta` config. They can all be specified together or mixed | |
159 | and matched however needed. | |
160 | The automatically generated config will be used for any that don't have a | |
161 | custom config file specified. | |
162 | ||
163 | The generated config can be dumped to serve as a base for custom configs: | |
164 | ||
165 | ---- | |
166 | qm cloudinit dump 9000 user | |
167 | ---- | |
168 | ||
169 | The same command exists for `network` and `meta`. | |
170 | ||
171 | ||
7eb69fd2 DM |
172 | Cloud-Init specific Options |
173 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
174 | ||
175 | include::qm-cloud-init-opts.adoc[] | |
16b4185a DM |
176 | |
177 | ||
178 | ifdef::wiki[] | |
179 | ||
180 | See Also | |
181 | ~~~~~~~~ | |
182 | ||
183 | * link:/wiki/Qemu/KVM_Virtual_Machines[Qemu/KVM Virtual Machines] | |
184 | ||
185 | endif::wiki[] |