[[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
~~~~~~~~~~~~~~~~~~~~~~~~~~~

`cicustom`: `[meta=<volume>] [,network=<volume>] [,user=<volume>]` ::

Specify custom files to replace the automatically generated ones at start.

`meta`=`<volume>` ;;

Specify a custom file containing all meta data passed to the VM via"
	    ." cloud-init. This is provider specific meaning configdrive2 and nocloud differ.

`network`=`<volume>` ;;

Specify a custom file containing all network data passed to the VM via cloud-init.

`user`=`<volume>` ;;

Specify a custom file containing all user data passed to the VM via cloud-init.

`cipassword`: `<string>` ::

Password to assign the user. Using this is generally not recommended. Use ssh keys instead. Also note that older cloud-init versions do not support hashed passwords.

`citype`: `<configdrive2 | nocloud>` ::

Specifies the cloud-init configuration format. The default depends on the configured operating system type (`ostype`. We use the `nocloud` format for Linux, and `configdrive2` for windows.

`ciuser`: `<string>` ::

User name to change ssh keys and password for instead of the image's configured default user.

`ipconfig[n]`: `[gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]` ::

Specify IP addresses and gateways for the corresponding interface.
+
IP addresses use CIDR notation, gateways are optional but need an IP of the same type specified.
+
The special string 'dhcp' can be used for IP addresses to use DHCP, in which case no explicit
gateway should be provided.
For IPv6 the special string 'auto' can be used to use stateless autoconfiguration.
+
If cloud-init is enabled and neither an IPv4 nor an IPv6 address is specified, it defaults to using
dhcp on IPv4.

`gw`=`<GatewayIPv4>` ;;

Default gateway for IPv4 traffic.
+
NOTE: Requires option(s): `ip`

`gw6`=`<GatewayIPv6>` ;;

Default gateway for IPv6 traffic.
+
NOTE: Requires option(s): `ip6`

`ip`=`<IPv4Format/CIDR>` ('default =' `dhcp`);;

IPv4 address in CIDR format.

`ip6`=`<IPv6Format/CIDR>` ('default =' `dhcp`);;

IPv6 address in CIDR format.

`nameserver`: `<string>` ::

Sets DNS server IP address for a container. Create will'
	    .' automatically use the setting from the host if neither searchdomain nor nameserver'
	    .' are set.

`searchdomain`: `<string>` ::

Sets DNS search domains for a container. Create will'
	    .' automatically use the setting from the host if neither searchdomain nor nameserver'
	    .' are set.

`sshkeys`: `<string>` ::

Setup public SSH keys (one key per line, OpenSSH format).


Source : https://git.proxmox.com/?p=pve-docs.git;a=summary
