all lists on lists.proxmox.com
 help / color / mirror / Atom feed
From: Daniel Herzig <d.herzig@proxmox.com>
To: pve-devel@lists.proxmox.com
Cc: Leo Nunner <l.nunner@proxmox.com>
Subject: [pve-devel] [PATCH 8/8 docs] pct: document cloudinit for LXC
Date: Mon, 10 Feb 2025 13:07:22 +0100	[thread overview]
Message-ID: <20250210120722.163622-9-d.herzig@proxmox.com> (raw)
In-Reply-To: <20250210120722.163622-1-d.herzig@proxmox.com>

From: Leo Nunner <l.nunner@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@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.
+
+{pve} writes the Cloud-init configuration directly into the container.
+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.
+
+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
+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:
+
+----
+# download an image
+pveam download local ubuntu-22.10-standard_22.10-1_amd64.tar.zst
+
+# create a new container
+pct create 9000 local:vztmpl/ubuntu-22.10-standard_22.10-1_amd64.tar.zst \
+    --storage local-lvm --memory 512 \
+    --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
+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
+----
+
+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"
+----
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
 -----------------------
 
-- 
2.39.5


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel


  parent reply	other threads:[~2025-02-10 12:07 UTC|newest]

Thread overview: 23+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-02-10 12:07 [pve-devel] [PATCH 0/8 container/manager/docs] fix #4686: Cloudinit support " Daniel Herzig
2025-02-10 12:07 ` [pve-devel] [PATCH 1/8 container] cloudinit: introduce config parameters Daniel Herzig
2025-02-13 10:10   ` Fiona Ebner
2025-02-13 10:18     ` Mira Limbeck
2025-02-13 10:22       ` Fiona Ebner
2025-02-13 10:23   ` Fiona Ebner
2025-02-13 15:05     ` Daniel Herzig
2025-02-13 12:15   ` Fiona Ebner
2025-02-10 12:07 ` [pve-devel] [PATCH 2/8 container] cloudinit: basic implementation Daniel Herzig
2025-02-13 11:01   ` Fiona Ebner
2025-02-13 11:29     ` Mira Limbeck
2025-02-13 12:02       ` Fiona Ebner
2025-02-13 15:09       ` Daniel Herzig
2025-02-13 12:06     ` Fiona Ebner
2025-02-10 12:07 ` [pve-devel] [PATCH 3/8 container] cloudinit: add dump command to pct Daniel Herzig
2025-02-13 12:00   ` Fiona Ebner
2025-02-10 12:07 ` [pve-devel] [PATCH 4/8 container] cloudinit: add function dumping options for docs Daniel Herzig
2025-02-10 12:07 ` [pve-devel] [PATCH 5/8 manager] cloudinit: rename qemu cloudinit panel Daniel Herzig
2025-02-10 12:07 ` [pve-devel] [PATCH 6/8 manager] cloudinit: introduce panel for LXCs Daniel Herzig
2025-02-10 12:07 ` [pve-devel] [PATCH 7/8 docs] pct: add script to generate cloudinit options Daniel Herzig
2025-02-13  9:52   ` Fiona Ebner
2025-02-10 12:07 ` Daniel Herzig [this message]
2025-02-12 15:46   ` [pve-devel] [PATCH 8/8 docs] pct: document cloudinit for LXC Fiona Ebner

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20250210120722.163622-9-d.herzig@proxmox.com \
    --to=d.herzig@proxmox.com \
    --cc=l.nunner@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal