From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <l.nunner@proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by lists.proxmox.com (Postfix) with ESMTPS id 0568F9D17C
 for <pve-devel@lists.proxmox.com>; Fri,  2 Jun 2023 13:58:25 +0200 (CEST)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
 by firstgate.proxmox.com (Proxmox) with ESMTP id DB33829C05
 for <pve-devel@lists.proxmox.com>; Fri,  2 Jun 2023 13:57:54 +0200 (CEST)
Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com
 [94.136.29.106])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by firstgate.proxmox.com (Proxmox) with ESMTPS
 for <pve-devel@lists.proxmox.com>; Fri,  2 Jun 2023 13:57:53 +0200 (CEST)
Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1])
 by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 76B9B48482
 for <pve-devel@lists.proxmox.com>; Fri,  2 Jun 2023 13:57:53 +0200 (CEST)
From: Leo Nunner <l.nunner@proxmox.com>
To: pve-devel@lists.proxmox.com
Date: Fri,  2 Jun 2023 13:57:31 +0200
Message-Id: <20230602115731.121151-9-l.nunner@proxmox.com>
X-Mailer: git-send-email 2.30.2
In-Reply-To: <20230602115731.121151-1-l.nunner@proxmox.com>
References: <20230602115731.121151-1-l.nunner@proxmox.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-SPAM-LEVEL: Spam detection results:  0
 AWL -0.513 Adjusted score from AWL reputation of From: address
 BAYES_00                 -1.9 Bayes spam probability is 0 to 1%
 DMARC_MISSING             0.1 Missing DMARC policy
 KAM_ASCII_DIVIDERS 0.8 Email that uses ascii formatting dividers and possible
 spam tricks
 KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
 SPF_HELO_NONE           0.001 SPF: HELO does not publish an SPF Record
 SPF_PASS               -0.001 SPF: sender matches SPF record
 T_SCC_BODY_TEXT_LINE    -0.01 -
Subject: [pve-devel] [PATCH docs 2/2] pct: document cloudinit for LXC
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
X-List-Received-Date: Fri, 02 Jun 2023 11:58:25 -0000

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 b8a0666..ec5319a 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 fdeb6dd..7cfb09e 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.30.2