[pve-devel] [PATCH 8/8 docs] pct: document cloudinit for LXC

[Fiona Ebner]

Planning to look at the code patches tomorrow, for now I started here :)

Am 10.02.25 um 13:07 schrieb Daniel Herzig:
> From: Leo Nunner <l.nunner at proxmox.com>
> 
> adds documentation for Cloud-Init for containers. Most of it has been
> taken from the VM documentation, since the configuration mostly works
> the same. Added a script to extract the cloudinit parameters the same
> way it's already done for VMs.
> 
> Signed-off-by: Leo Nunner <l.nunner at proxmox.com>
> ---
>  Makefile            |   1 +
>  pct-cloud-init.adoc | 114 ++++++++++++++++++++++++++++++++++++++++++++
>  pct.adoc            |   4 ++
>  3 files changed, 119 insertions(+)
>  create mode 100644 pct-cloud-init.adoc
> 
> diff --git a/Makefile b/Makefile
> index f30d77a..24836b8 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -53,6 +53,7 @@ GEN_SCRIPTS=					\
>  	gen-pct.conf.5-opts.pl			\
>  	gen-pct-network-opts.pl			\
>  	gen-pct-mountpoint-opts.pl		\
> +	gen-pct-cloud-init-opts.pl		\
>  	gen-qm.conf.5-opts.pl			\
>  	gen-cpu-models.conf.5-opts.pl 		\
>  	gen-qm-cloud-init-opts.pl		\
> diff --git a/pct-cloud-init.adoc b/pct-cloud-init.adoc
> new file mode 100644
> index 0000000..1398e7b
> --- /dev/null
> +++ b/pct-cloud-init.adoc
> @@ -0,0 +1,114 @@
> +[[pct_cloud_init]]
> +Cloud-Init Support
> +------------------
> +ifdef::wiki[]
> +:pve-toplevel:
> +endif::wiki[]
> +
> +{pve} supports the Cloud-init 'nocloud' format for LXC.

s/Cloud-init/Cloud-Init/

Although the official name seems to be "cloud-init", the documentation
for VMs uses "Cloud-Init" as the capitalization, so I think we should
stick to it (or change it to "cloud-init" consistently everywhere).

> +
> +{pve} writes the Cloud-init configuration directly into the container.

s/Cloud-init/Cloud-Init/

> +When the 'cienable' option is set to true, the configuration is updated
> +directly before before every boot. Each configuration is identified by
> +an 'instance id', which Cloud-Init uses to decide whether it should run
> +again or not.

Maybe add a quick sentence what happens if "cienable" is not set, just
for clarity? Hmm, seems strange actually:

* previously added SSH keys will stay added
* previously added users will stay added
* package upgrades seems to revert to default 'No'

If this really is intentional, this should be documented of course.
Seems like it behaves the same for VMs, should be documented there too.

> +
> +Preparing Cloud-Init Templates
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The first step is to prepare your container. Any template will suffice.
> +Simply install the Cloud-Init packages inside the CT that you want to

s/CT/countainer/

> +prepare. On Debian/Ubuntu based systems this is as simple as:
> +
> +----
> +apt install cloud-init
> +----
> +
> +WARNING: This command is *not* intended to be executed on the {pve} host, but
> +only inside the container.
> +
> +A simple preparation for a cloud-init capable container could look like this:

s/cloud-init/Cloud-Init/

> +
> +----
> +# download an image
> +pveam download local ubuntu-22.10-standard_22.10-1_amd64.tar.zst

This one doesn't exists (on PVE 8.3), would be nice to have a working
example.

> +
> +# create a new container
> +pct create 9000 local:vztmpl/ubuntu-22.10-standard_22.10-1_amd64.tar.zst \
> +    --storage local-lvm --memory 512 \

Maybe specify an explicit rootfs with size rather than the '--storage'
option. The automatic default of 4 GiB is a bit magic-y and like this,
users won't see how to adapt the size for their use case straight away.

I'd also add --unprivileged 1 --features nesting=1 since that is usually
desired and are the UI defaults too. As well as setting the 'cores'.

> +    --net0 name=eth0,bridge=vmbr0,ip=dhcp,type=veth
> +----
> +
> +Now, the package can be installed inside the container:
> +
> +----
> +# install the needed packages
> +pct start 9000

NOTE: you will need to wait until the network is ready ;)

> +pct exec 9000 apt update
> +pct exec 9000 apt install cloud-init
> +pct stop 9000
> +----
> +
> +Finally, it can be helpful to turn the container into a template, to be able
> +to quickly create clones whenever needed.
> +
> +----
> +pct template 9000
> +----
> +

I think there should be a section about describing how to actually
configure the settings (also referring to the UI). Currently, there only
is the description with the custom configuration, but the basic
configuration is not mentioned at all.

> +Deploying Cloud-Init Templates
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +A template can easily be deployed by cloning:
> +
> +----
> +pct clone 9000 3000 --hostname ubuntu
> +----
> +
> +Cloud-Init can now be enabled, and will run automatically on the next boot.
> +
> +----
> +pct set 3000 --cienable=1
> +----
> +
> +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:
> +
> +----
> +pct set 9000 --cicustom "user=<volume>,meta=<volume>"
> +----
> +
> +The custom config files have to be on a storage that supports snippets and have
> +to be available on all nodes the container is going to be migrated to. Otherwise the
> +container won't be able to start.
> +For example:
> +
> +----
> +qm set 9000 --cicustom "user=local:snippets/userconfig.yaml"

Uses qm instead of pct

> +----
> +
> +In contrast to the options for VMs, containers only support custom 'user'
> +and 'vendor' scripts, but not 'network'. Network configuration is done through
> +the already existing facilities integrated into {pve}. They can all be specified
> +together or mixed and matched however needed.
> +The automatically generated config will be used for any section that doesn't have a
> +custom config file specified.
> +
> +The generated config can be dumped to serve as a base for custom configs:
> +
> +----
> +pct cloudinit dump 9000 user
> +----
> +
> +The same command exists for `meta`.
> +
> +
> +Cloud-Init specific Options
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~

Doesn't use title case

> +
> +include::pct-cloud-init-opts.adoc[]
> +
> diff --git a/pct.adoc b/pct.adoc
> index 529b72f..de80347 100644
> --- a/pct.adoc
> +++ b/pct.adoc
> @@ -622,6 +622,10 @@ It will be called during various phases of the guests lifetime.  For an example
>  and documentation see the example script under
>  `/usr/share/pve-docs/examples/guest-example-hookscript.pl`.
>  
> +ifndef::wiki[]
> +include::pct-cloud-init.adoc[]
> +endif::wiki[]
> +
>  Security Considerations
>  -----------------------
>