diff --git a/deprecation.d/boolean-configuration-shorthand.md b/deprecation.d/boolean-configuration-shorthand.md new file mode 100644 index 0000000000000..9ca9fa3b91aae --- /dev/null +++ b/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`. diff --git a/lib/vector-config/src/schema/helpers.rs b/lib/vector-config/src/schema/helpers.rs index ea6c322f9fcb1..df23bd3ca0181 100644 --- a/lib/vector-config/src/schema/helpers.rs +++ b/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, diff --git a/lib/vector-config/tests/integration/bool_or_struct.rs b/lib/vector-config/tests/integration/bool_or_struct.rs index 41814d42422da..c23e95cea6594 100644 --- a/lib/vector-config/tests/integration/bool_or_struct.rs +++ b/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] diff --git a/lib/vector-core/src/serde.rs b/lib/vector-core/src/serde.rs index 168ce525de717..876efdc11d266 100644 --- a/lib/vector-core/src/serde.rs +++ b/lib/vector-core/src/serde.rs @@ -25,14 +25,14 @@ pub fn is_default(e: &E) -> bool { /// Returns the error from deserializing the underlying struct. pub fn bool_or_struct<'de, T, D>(deserializer: D) -> Result where - T: Deserialize<'de> + From, + T: Deserialize<'de> + From + Configurable, D: Deserializer<'de>, { struct BoolOrStruct(PhantomData T>); impl<'de, T> de::Visitor<'de> for BoolOrStruct where - T: Deserialize<'de> + From, + T: Deserialize<'de> + From + 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()) } diff --git a/website/cue/reference/components/sinks.cue b/website/cue/reference/components/sinks.cue index 5034ca6cdfd8f..12477629eba19 100644 --- a/website/cue/reference/components/sinks.cue +++ b/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 diff --git a/website/data/deprecations.json b/website/data/deprecations.json index 171ca9076ef80..bbfaf87ad41ab 100644 --- a/website/data/deprecations.json +++ b/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",