From 93a33dc9bb369eda5423e2efa968b85adbe9bc12 Mon Sep 17 00:00:00 2001 From: Ahmed Al-Tuwaijari Date: Mon, 25 May 2026 15:30:07 +0300 Subject: [PATCH 1/4] docs: document per-frequency shell script MIME types Add a dedicated subsection explaining text/x-shellscript-per-boot, text/x-shellscript-per-instance, and text/x-shellscript-per-once content types, including their execution frequency, on-disk script directories, and pointers to the handler and modules. Fixes #6283 Signed-off-by: Ahmed Al-Tuwaijari --- doc/rtd/explanation/format/mime.rst | 31 +++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/rtd/explanation/format/mime.rst b/doc/rtd/explanation/format/mime.rst index 829367eb964..d711564f599 100644 --- a/doc/rtd/explanation/format/mime.rst +++ b/doc/rtd/explanation/format/mime.rst @@ -77,4 +77,35 @@ Create user-data containing 3 shell scripts: $ cloud-init devel make-mime -a always.sh:x-shellscript-per-boot -a instance.sh:x-shellscript-per-instance -a once.sh:x-shellscript-per-once +Per-frequency shell scripts +--------------------------- + +Cloud-init supports three MIME content types for controlling how often a +shell script runs: + +``text/x-shellscript-per-boot`` + The script runs on **every boot**. Useful for tasks that must be + repeated each time the instance starts, such as mounting ephemeral + storage or refreshing dynamic configuration. + +``text/x-shellscript-per-instance`` + The script runs **once per instance** (on first boot only). Useful + for one-time instance setup tasks. + +``text/x-shellscript-per-once`` + The script runs **exactly once**, even across different instances + created from the same image. Useful for tasks that should never + repeat regardless of instance lifecycle. + +Scripts are stored on disk under the following directories: + +- ``/var/lib/cloud/scripts/per-boot/`` +- ``/var/lib/cloud/scripts/per-instance/`` +- ``/var/lib/cloud/scripts/per-once/`` + +These are handled by :ref:`cc_scripts_per_boot`, +:ref:`cc_scripts_per_instance`, and +:ref:`cc_scripts_per_once` respectively, via +``cloudinit/handlers/shell_script_by_frequency.py``. + .. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py From 1463c0419feb871bfefe13bc8c90405daf746ac1 Mon Sep 17 00:00:00 2001 From: Ahmed <76178825+Ahmedaltu@users.noreply.github.com> Date: Tue, 26 May 2026 22:26:11 +0300 Subject: [PATCH 2/4] docs: clarify per-instance runs once per instance-id, not first boot only Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- doc/rtd/explanation/format/mime.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/rtd/explanation/format/mime.rst b/doc/rtd/explanation/format/mime.rst index d711564f599..4ae84451693 100644 --- a/doc/rtd/explanation/format/mime.rst +++ b/doc/rtd/explanation/format/mime.rst @@ -89,8 +89,8 @@ shell script runs: storage or refreshing dynamic configuration. ``text/x-shellscript-per-instance`` - The script runs **once per instance** (on first boot only). Useful - for one-time instance setup tasks. + The script runs **once per instance-id** (typically on first boot + for that instance). Useful for one-time instance setup tasks. ``text/x-shellscript-per-once`` The script runs **exactly once**, even across different instances From 73f17eb9022ea7af748b47cffa0c00b8b5a0a839 Mon Sep 17 00:00:00 2001 From: Ahmed Al-Tuwaijari Date: Tue, 26 May 2026 22:34:17 +0300 Subject: [PATCH 3/4] docs: clarify per-once uses cloud-level semaphore state Signed-off-by: Ahmed Al-Tuwaijari --- doc/rtd/explanation/format/mime.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/rtd/explanation/format/mime.rst b/doc/rtd/explanation/format/mime.rst index d711564f599..e14536627f3 100644 --- a/doc/rtd/explanation/format/mime.rst +++ b/doc/rtd/explanation/format/mime.rst @@ -93,9 +93,12 @@ shell script runs: for one-time instance setup tasks. ``text/x-shellscript-per-once`` - The script runs **exactly once**, even across different instances - created from the same image. Useful for tasks that should never - repeat regardless of instance lifecycle. + The script runs **once per cloud-init state**, using the cloud-level + semaphore directory (:file:`/var/lib/cloud/sem`). A freshly + provisioned instance will normally run it once, but an instance + created from an image that preserves existing cloud-init state may + not. To allow it to run again, clean cloud-init state (for example, + remove :file:`/var/lib/cloud` or run :command:`cloud-init clean`). Scripts are stored on disk under the following directories: From 224afb483071f47c662c9cca99f03ff7fae9d300 Mon Sep 17 00:00:00 2001 From: Ahmed Al-Tuwaijari Date: Wed, 27 May 2026 16:48:24 +0300 Subject: [PATCH 4/4] docs: remove internal implementation details per review Signed-off-by: Ahmed Al-Tuwaijari --- doc/rtd/explanation/format/mime.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/doc/rtd/explanation/format/mime.rst b/doc/rtd/explanation/format/mime.rst index 2a3e1d51543..95da17fe43d 100644 --- a/doc/rtd/explanation/format/mime.rst +++ b/doc/rtd/explanation/format/mime.rst @@ -100,15 +100,4 @@ shell script runs: not. To allow it to run again, clean cloud-init state (for example, remove :file:`/var/lib/cloud` or run :command:`cloud-init clean`). -Scripts are stored on disk under the following directories: - -- ``/var/lib/cloud/scripts/per-boot/`` -- ``/var/lib/cloud/scripts/per-instance/`` -- ``/var/lib/cloud/scripts/per-once/`` - -These are handled by :ref:`cc_scripts_per_boot`, -:ref:`cc_scripts_per_instance`, and -:ref:`cc_scripts_per_once` respectively, via -``cloudinit/handlers/shell_script_by_frequency.py``. - .. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py