feat(systemd): convert warning level message to deprecation (canonica…

…l#5209)

Avoid using warning level messages as there may be some
use-cases in the wild that need to invoke cloud-init boot
stages after boot for some reason unknown to upstream.

Provide a detailed warning message informing admins to file
issues against cloud-init to better represent those feature
needs before dropping this feature altogether.

cloudinit/cmd/main.py

@@ -79,23 +79,30 @@ def print_exc(msg=""):
     sys.stderr.write("\n")
 
 
+DEPRECATE_BOOT_STAGE_MESSAGE = (
+    "Triggering cloud-init boot stages outside of intial system boot is not a"
+    " fully supported operation which can lead to incomplete or incorrect"
+    " configuration. As such, cloud-init is deprecating this feature in the"
+    " future. If you currently use cloud-init in this way,"
+    " please file an issue describing in detail your use case so that"
+    " cloud-init can better support your needs:"
+    " https://github.com/canonical/cloud-init/issues/new"
+)
+
+
 def log_ppid(distro, bootstage_name):
     if distro.is_linux:
         ppid = os.getppid()
-        log = LOG.info
-        extra_message = ""
         if 1 != ppid and distro.uses_systemd():
-            log = LOG.warning
-            extra_message = (
-                " Unsupported configuration: boot stage called "
-                "outside of systemd"
+            util.deprecate(
+                deprecated=(
+                    "Unsupported configuration: boot stage called "
+                    f"by PID [{ppid}] outside of systemd"
+                ),
+                deprecated_version="24.3",
+                extra_message=DEPRECATE_BOOT_STAGE_MESSAGE,
             )
-        log(
-            "PID [%s] started cloud-init '%s'.%s",
-            ppid,
-            bootstage_name,
-            extra_message,
-        )
+    LOG.info("PID [%s] started cloud-init '%s'.", ppid, bootstage_name)
 
 
 def welcome(action, msg=None):

doc/rtd/reference/cli.rst

@@ -212,9 +212,10 @@ Example output:
 
 Generally run by OS init systems to execute ``cloud-init``'s stages:
 *init* and *init-local*. See :ref:`boot_stages` for more info.
-Can be run on the command line, but is generally gated to run only once
-due to semaphores in :file:`/var/lib/cloud/instance/sem/` and
-:file:`/var/lib/cloud/sem`.
+Can be run on the command line, but is deprecated, because incomplete
+configuration can be applied when run later in boot. The boot stages are
+generally gated to run only once due to semaphores in
+:file:`/var/lib/cloud/instance/sem/` and :file:`/var/lib/cloud/sem`.
 
 * :command:`--local`: Run *init-local* stage instead of *init*.
 * :command:`--file` : Use additional yaml configuration files.
@@ -226,16 +227,19 @@ due to semaphores in :file:`/var/lib/cloud/instance/sem/` and
 
 Generally run by OS init systems to execute ``modules:config`` and
 ``modules:final`` boot stages. This executes cloud config :ref:`modules`
-configured to run in the Init, Config and Final stages. The modules are
-declared to run in various boot stages in the file
+configured to run in the Init, Config and Final stages. Can be run on the
+command line, but this is not recommended and will generate a warning because
+incomplete configuration can be applied when run later in boot.
+The modules are declared to run in various boot stages in the file
 :file:`/etc/cloud/cloud.cfg` under keys:
 
 * ``cloud_init_modules``
 * ``cloud_config_modules``
 * ``cloud_final_modules``
 
-Can be run on the command line, but each module is gated to run only once due
-to semaphores in :file:`/var/lib/cloud/`.
+Can be run on the command line, but is deprecated, because incomplete
+configuration can be applied when run later in boot. Each module is gated to
+run only once due to semaphores in :file:`/var/lib/cloud/`.
 
 * :command:`--mode [init|config|final]`: Run ``modules:init``,
   ``modules:config`` or ``modules:final`` ``cloud-init`` stages.