docs(config): deprecate boolean configuration shorthand (#26680)

Author: pront

deprecation.d/boolean-configuration-shorthand.md

@@ -0,0 +1,39 @@
+---
+what: "Boolean shorthand for object-valued configuration options"
+deprecated_since: "0.60.0"
+---
+
+Boolean shorthand for object-valued configuration options is deprecated. Use the object form instead
+so that each setting has one consistent representation and the options being configured are explicit.
+
+Existing boolean values continue to work. Removal is not yet scheduled. We will give users at least
+one month to migrate before removing this shorthand.
+
+This applies to `healthcheck` on sinks, global and sink `acknowledgements`, `jetstream` on the NATS sink,
+and `acknowledgements` on the Splunk HEC source.
+Ordinary boolean options, such as `healthcheck.enabled`, are unaffected.
+
+Please also see the [dedicated note for `use_otlp_decoding`](/deprecations/#opentelemetry-use_otlp_decoding).
+
+### Settings with an `enabled` field
+
+For `healthcheck`, global and sink `acknowledgements`, NATS sink `jetstream`, and Splunk HEC source
+`acknowledgements`, replace the boolean with an object containing the same value in `enabled`.
+For example, within a sink configuration, replace:
+
+```yaml
+healthcheck: false
+acknowledgements: true
+```
+
+with:
+
+```yaml
+healthcheck:
+  enabled: false
+acknowledgements:
+  enabled: true
+```
+
+Other options in these objects retain their defaults. Use the same transformation for either `true`
+or `false`.

lib/vector-config/src/schema/helpers.rs

@@ -798,7 +798,9 @@ pub fn generate_bool_or_struct_schema(
             .definitions_mut()
             .insert(name.clone(), Schema::Bool(false));
         let object = get_or_generate_schema(config, generator, None)?;
-        let mut schema = generate_one_of_schema(&[generate_bool_schema(), object]);
+        let mut boolean = generate_bool_schema();
+        boolean.metadata().deprecated = true;
+        let mut schema = generate_one_of_schema(&[boolean, object]);
         let mut metadata = config.make_metadata();
         metadata.add_custom_attribute(CustomAttribute::kv(
             constants::DOCS_META_ENUM_TAGGING,

lib/vector-config/tests/integration/bool_or_struct.rs

@@ -136,6 +136,7 @@ fn shared_schema_preserves_defaults_descriptions_and_deprecation() {
         .unwrap();
     assert_eq!(shared["deprecated"], true);
     assert_eq!(shared["_metadata"]["docs::enum_tagging"], "untagged");
+    assert_eq!(shared["oneOf"][0]["deprecated"], true);
 }
 
 #[test]

lib/vector-core/src/serde.rs

@@ -25,14 +25,14 @@ pub fn is_default<E: Default + PartialEq>(e: &E) -> bool {
 /// Returns the error from deserializing the underlying struct.
 pub fn bool_or_struct<'de, T, D>(deserializer: D) -> Result<T, D::Error>
 where
-    T: Deserialize<'de> + From<bool>,
+    T: Deserialize<'de> + From<bool> + Configurable,
     D: Deserializer<'de>,
 {
     struct BoolOrStruct<T>(PhantomData<fn() -> T>);
 
     impl<'de, T> de::Visitor<'de> for BoolOrStruct<T>
     where
-        T: Deserialize<'de> + From<bool>,
+        T: Deserialize<'de> + From<bool> + Configurable,
     {
         type Value = T;
 
@@ -44,6 +44,12 @@ where
         where
             E: de::Error,
         {
+            // Already-deprecated types retain their existing migration guidance.
+            if !T::metadata().deprecated() {
+                tracing::warn!(
+                    "DEPRECATED: Boolean shorthand for an object-valued configuration option. Use the object form instead. See https://vector.dev/deprecations/ for migration instructions."
+                );
+            }
             Ok(value.into())
         }
 

website/cue/reference/components/sinks.cue

@@ -9,8 +9,13 @@ components: sinks: [Name=string]: {
 		inputs: generated.components.sinks.configuration.inputs
 		buffer: generated.components.sinks.configuration.buffer
 		healthcheck: {
-			description: generated.components.sinks.configuration.healthcheck.description
+			description: """
+				\(generated.components.sinks.configuration.healthcheck.description)
+
+				A boolean value sets `enabled`; other healthcheck options retain their defaults.
+				"""
 			required:    generated.components.sinks.configuration.healthcheck.required
+			type: bool: generated.components.sinks.configuration.healthcheck.type.bool
 			type: object: options: {
 				enabled: generated.components.sinks.configuration.healthcheck.type.object.options.enabled
 

website/data/deprecations.json

@@ -5,6 +5,11 @@
       "deprecated_since": "0.59.0",
       "description": "The `aggregate` transform now also emits the failed-updates counter with the `_total` suffix, matching Vector's counter naming convention:\n\n- `aggregate_failed_updates_total`\n\nThe previous name without the `_total` suffix is deprecated and will be removed in a future release. Migrate any dashboards or alerts that reference:\n\n- `aggregate_failed_updates`"
     },
+    {
+      "what": "Boolean shorthand for object-valued configuration options",
+      "deprecated_since": "0.60.0",
+      "description": "Boolean shorthand for object-valued configuration options is deprecated. Use the object form instead\nso that each setting has one consistent representation and the options being configured are explicit.\n\nExisting boolean values continue to work. Removal is not yet scheduled. We will give users at least\none month to migrate before removing this shorthand.\n\nThis applies to `healthcheck` on sinks, global and sink `acknowledgements`, `jetstream` on the NATS sink,\nand `acknowledgements` on the Splunk HEC source.\nOrdinary boolean options, such as `healthcheck.enabled`, are unaffected.\n\nPlease also see the [dedicated note for `use_otlp_decoding`](/deprecations/#opentelemetry-use_otlp_decoding).\n\n### Settings with an `enabled` field\n\nFor `healthcheck`, global and sink `acknowledgements`, NATS sink `jetstream`, and Splunk HEC source\n`acknowledgements`, replace the boolean with an object containing the same value in `enabled`.\nFor example, within a sink configuration, replace:\n\n```yaml\nhealthcheck: false\nacknowledgements: true\n```\n\nwith:\n\n```yaml\nhealthcheck:\n  enabled: false\nacknowledgements:\n  enabled: true\n```\n\nOther options in these objects retain their defaults. Use the same transformation for either `true`\nor `false`."
+    },
     {
       "what": "omitting the `version` field on `influxdb_logs` and `influxdb_metrics` sinks",
       "deprecated_since": "0.58.0",