log: Add standardized deprecation tooling (SC-1312) (#2026)

- Add deprecation log level
- Add deprecation utilities for structured format and messaging
- Update existing deprecation log sites, add deprecated versions

7 files changed, 44 insertions, 36 deletions

diff --git a/cloudinit/config/cc_apt_configure.py b/cloudinit/config/cc_apt_configure.py
index 98957f8d..17c2fb58 100644
--- a/cloudinit/config/cc_apt_configure.py
+++ b/cloudinit/config/cc_apt_configure.py
@@ -614,9 +614,10 @@ def add_apt_sources(
 def convert_v1_to_v2_apt_format(srclist):
     """convert v1 apt format to v2 (dict in apt_sources)"""
     srcdict = {}
-    LOG.warning(
-        "DEPRECATION: 'apt_sources' deprecated config key found."
-        " Use 'apt' instead"
+    util.deprecate(
+        deprecated="Config key 'apt_sources'",
+        deprecated_version="22.1",
+        extra_message="Use 'apt' instead",
     )
     if isinstance(srclist, list):
         LOG.debug("apt config: convert V1 to V2 format (source list to dict)")
@@ -692,18 +693,17 @@ def convert_v2_to_v3_apt_format(oldcfg):
     # no old config, so no new one to be created
     if not needtoconvert:
         return oldcfg
-    LOG.warning(
-        "DEPRECATION apt: converted deprecated config V2 to V3 format for"
-        " keys '%s'. Use updated config keys.",
-        ", ".join(needtoconvert),
+    util.deprecate(
+        deprecated=f"The following config key(s): {needtoconvert}",
+        deprecated_version="22.1",
     )
 
     # if old AND new config are provided, prefer the new one (LP #1616831)
     newaptcfg = oldcfg.get("apt", None)
     if newaptcfg is not None:
-        LOG.warning(
-            "DEPRECATION: apt config: deprecated V1/2 and V3 format specified,"
-            " preferring V3"
+        util.deprecate(
+            deprecated="Support for combined old and new apt module keys",
+            deprecated_version="22.1",
         )
         for oldkey in needtoconvert:
             newkey = mapoldkeys[oldkey]
diff --git a/cloudinit/config/cc_ca_certs.py b/cloudinit/config/cc_ca_certs.py
index 51b8577c..b1c4a2bf 100644
--- a/cloudinit/config/cc_ca_certs.py
+++ b/cloudinit/config/cc_ca_certs.py
@@ -229,9 +229,10 @@ def handle(
     @param args: Any module arguments from cloud.cfg
     """
     if "ca-certs" in cfg:
-        LOG.warning(
-            "DEPRECATION: key 'ca-certs' is now deprecated. Use 'ca_certs'"
-            " instead."
+        util.deprecate(
+            deprecated="Key 'ca-certs'",
+            deprecated_version="22.1",
+            extra_message="Use 'ca_certs' instead.",
         )
     elif "ca_certs" not in cfg:
         LOG.debug(
@@ -251,9 +252,10 @@ def handle(
     # If there is a remove_defaults option set to true, disable the system
     # default trusted CA certs first.
     if "remove-defaults" in ca_cert_cfg:
-        LOG.warning(
-            "DEPRECATION: key 'ca-certs.remove-defaults' is now deprecated."
-            " Use 'ca_certs.remove_defaults' instead."
+        util.deprecate(
+            deprecated="Key 'remove-defaults'",
+            deprecated_version="22.1",
+            extra_message="Use 'remove_defaults' instead.",
         )
     if ca_cert_cfg.get(
         "remove_defaults", ca_cert_cfg.get("remove-defaults", False)
diff --git a/cloudinit/config/cc_growpart.py b/cloudinit/config/cc_growpart.py
index f3acbe2a..2a496820 100644
--- a/cloudinit/config/cc_growpart.py
+++ b/cloudinit/config/cc_growpart.py
@@ -583,9 +583,10 @@ def handle(
     mode = mycfg.get("mode", "auto")
     if util.is_false(mode):
         if mode != "off":
-            log.warning(
-                f"DEPRECATED: growpart mode '{mode}' is deprecated. "
-                "Use 'off' instead."
+            util.deprecate(
+                deprecated="Growpart's 'mode' key with value '{mode}'",
+                deprecated_version="22.2",
+                extra_message="Use 'off' instead.",
             )
         log.debug("growpart disabled: mode=%s" % mode)
         return
diff --git a/cloudinit/config/cc_rsyslog.py b/cloudinit/config/cc_rsyslog.py
index 9baaf094..47ade927 100644
--- a/cloudinit/config/cc_rsyslog.py
+++ b/cloudinit/config/cc_rsyslog.py
@@ -107,9 +107,9 @@ def load_config(cfg: dict) -> dict:
     mycfg = cfg.get("rsyslog", {})
 
     if isinstance(cfg.get("rsyslog"), list):
-        LOG.warning(
-            "DEPRECATION: This rsyslog list format is deprecated and will be "
-            "removed in a future version of cloud-init. Use documented keys."
+        util.deprecate(
+            deprecated="The rsyslog key with value of type 'list'",
+            deprecated_version="22.2",
         )
         mycfg = {KEYNAME_CONFIGS: cfg.get("rsyslog")}
         if KEYNAME_LEGACY_FILENAME in cfg:
diff --git a/cloudinit/config/cc_set_passwords.py b/cloudinit/config/cc_set_passwords.py
index 3a0b3f5b..bd27d533 100644
--- a/cloudinit/config/cc_set_passwords.py
+++ b/cloudinit/config/cc_set_passwords.py
@@ -133,10 +133,10 @@ def handle_ssh_pwauth(pw_auth, distro: Distro):
     cfg_name = "PasswordAuthentication"
 
     if isinstance(pw_auth, str):
-        LOG.warning(
-            "DEPRECATION: The 'ssh_pwauth' config key should be set to "
-            "a boolean value. The string format is deprecated and will be "
-            "removed in a future version of cloud-init."
+        util.deprecate(
+            deprecated="Using a string value for the 'ssh_pwauth' key",
+            deprecated_version="22.2",
+            extra_message="Use a boolean value with 'ssh_pwauth'.",
         )
     if util.is_true(pw_auth):
         cfg_val = "yes"
@@ -192,17 +192,19 @@ def handle(
         chfg = cfg["chpasswd"]
         users_list = util.get_cfg_option_list(chfg, "users", default=[])
         if "list" in chfg and chfg["list"]:
-            log.warning(
-                "DEPRECATION: key 'lists' is now deprecated. Use 'users'."
+            util.deprecate(
+                deprecated="Config key 'lists'",
+                deprecated_version="22.3",
+                extra_message="Use 'users' instead.",
             )
             if isinstance(chfg["list"], list):
                 log.debug("Handling input for chpasswd as list.")
                 plist = util.get_cfg_option_list(chfg, "list", plist)
             else:
-                log.warning(
-                    "DEPRECATION: The chpasswd multiline string format is "
-                    "deprecated and will be removed from a future version of "
-                    "cloud-init. Use the list format instead."
+                util.deprecate(
+                    deprecated="The chpasswd multiline string",
+                    deprecated_version="22.2",
+                    extra_message="Use string type instead.",
                 )
                 log.debug("Handling input for chpasswd as multiline string.")
                 multiline = util.get_cfg_option_str(chfg, "list")
diff --git a/cloudinit/config/cc_update_etc_hosts.py b/cloudinit/config/cc_update_etc_hosts.py
index 7bb9dff0..695bc019 100644
--- a/cloudinit/config/cc_update_etc_hosts.py
+++ b/cloudinit/config/cc_update_etc_hosts.py
@@ -106,9 +106,10 @@ def handle(
 
     if util.translate_bool(manage_hosts, addons=["template"]):
         if manage_hosts == "template":
-            log.warning(
-                "DEPRECATED: please use manage_etc_hosts: true instead of"
-                " 'template'"
+            util.deprecate(
+                deprecated="Value 'template' for key 'manage_etc_hosts'",
+                deprecated_version="22.2",
+                extra_message="Use 'true' instead.",
             )
         (hostname, fqdn, _) = util.get_hostname_fqdn(cfg, cloud)
         if not hostname:
diff --git a/cloudinit/config/schema.py b/cloudinit/config/schema.py
index b0b5fccf..9bccdcec 100644
--- a/cloudinit/config/schema.py
+++ b/cloudinit/config/schema.py
@@ -476,7 +476,9 @@ def validate_cloudconfig_schema(
             prefix="Deprecated cloud-config provided:\n",
             separator="\n",
         )
-        LOG.warning(message)
+        # This warning doesn't fit the standardized util.deprecated() utility
+        # format, but it is a deprecation log, so log it directly.
+        LOG.deprecated(message)  # type: ignore
     if strict and (errors or deprecations):
         raise SchemaValidationError(errors, deprecations)
     if errors: