From 88d91bc154f49721ce74f3b83847e9632d1e5343 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Wed, 2 Sep 2026 14:59:42 +0200 Subject: [PATCH 1/5] docs: document applies_to authoring for settings YAML Settings YAML uses the same keys as body Markdown, but deployment keys are support flags so the Supported on line stays readable. Co-authored-by: Cursor --- docs/syntax/applies.md | 3 + docs/syntax/automated_settings.md | 71 +++++++++++++++++-- docs/syntax/settings-with-applies-example.yml | 26 ++++++- 3 files changed, 93 insertions(+), 7 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index ae8681f042..7b36ceaaaf 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -24,11 +24,14 @@ When documenting a new feature or behavior, answer these two questions: | You need to show entirely different content for each variant, not just tag the same content | [Versioned tabs](applies-switch.md) | | You're adding a version-specific note, tip, or warning | [Admonition annotation](admonitions.md) | | You're adding a version-specific dropdown | [Dropdown annotation](dropdowns.md) | +| You're tagging a `{settings}` YAML entry | [applies_to in settings YAML](automated_settings.md#settings-yaml) | ## Syntax reference The `applies_to` metadata supports an [exhaustive list of keys](#key-value-reference). When you write or edit documentation, only specify the keys that apply to that content. +`{settings}` YAML is an exception. Each setting renders a **Supported on** line, so you list every deployment key. Refer to [applies_to in settings YAML](automated_settings.md#settings-yaml). + Each key accepts values with the following syntax: ``` diff --git a/docs/syntax/automated_settings.md b/docs/syntax/automated_settings.md index 8809e3530e..b0b2c295a5 100644 --- a/docs/syntax/automated_settings.md +++ b/docs/syntax/automated_settings.md @@ -18,7 +18,7 @@ The `{settings}` directive is generic. Although the largest current examples com Valid values: `ech` (Elastic Cloud Hosted), `ece` (Elastic Cloud Enterprise), `eck` (Elastic Cloud on Kubernetes), `self` (self-managed). - A setting is considered available for a deployment type if its `applies_to.deployment` block explicitly lists that deployment with a non-removed lifecycle. If a setting has `applies_to` metadata but no entry for the requested deployment, it is treated as unavailable and hidden. + A setting is considered available for a deployment type if its `applies_to` metadata lists that deployment with a lifecycle other than `removed` or `unavailable`. Flat keys such as `ech: ga` and a nested `deployment:` map both work. If a setting has `applies_to` metadata but no entry for the requested deployment, it is treated as unavailable and hidden. Settings with no `applies_to` metadata at all are always shown, regardless of the filter. @@ -54,12 +54,16 @@ groups: # id: OPTIONAL # applies_to: OPTIONAL docs-builder applicability metadata # - # Supports docs-builder applies_to syntax, for example: + # Same keys as applies.md. The authoring contract is different. + # See "applies_to in settings YAML" on this page. # # applies_to: # stack: ga 9.2 # ech: ga + # ece: ga + # eck: ga # self: ga + # serverless: ga # # note: OPTIONAL # tip: OPTIONAL @@ -73,12 +77,69 @@ groups: # description: OPTIONAL # example: OPTIONAL multiline Markdown # settings: OPTIONAL nested settings list - # Child settings inherit applies_to from the parent unless overridden. + # Child settings inherit applies_to when they omit the field. + # A child applies_to map replaces the parent. It does not merge keys. # - setting: "[n].url" # description: | # REQUIRED ``` +### applies_to in settings YAML [settings-yaml] + +The keys are the same as [Applies to](applies.md). The authoring contract is different, because each setting renders a **Supported on** line. + +In body Markdown, name only the keys that apply to the content. In settings YAML, list every deployment key so that line is complete and the `:deployment:` filter is explicit. + +| Key | What it means here | Write | +|---|---|---| +| `stack` | Lifecycle and version of the setting | `ga`, `preview 9.2`, or a history such as `preview 9.0-9.2, ga 9.3+`. No version means all versions. | +| `ech`, `ece`, `eck`, `self` | Supported on that deployment, or not | Always list all four. `ga` if supported. `unavailable` if not. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. | +| `serverless` | Supported on serverless, or not | Always list it. `ga` if supported. `unavailable` if not. Never a version. | + +`ga` on a deployment key is a support flag. It does not mean the setting is generally available. If `stack` is `preview` and the setting exists on Elastic Cloud Hosted, write `ech: ga`. + +`unavailable` is not rendered as a badge. It hides the setting from `:deployment:`. Omitting a deployment key also hides it from that filter. Still write `unavailable` so the Supported on line is complete. + +Child settings inherit the parent's `applies_to` when they omit the field. If a child sets `applies_to`, that map replaces the parent. It does not merge keys. + +To scope a `note`, `tip`, `warning`, or `important` to a version or deployment, put `:applies_to:` on the first line of that field. docs-builder wraps the field in an admonition. Do not add a `:::{note}` wrapper. + +Preferred map (supported everywhere): + +```yaml +applies_to: + stack: ga 9.2 + ech: ga + ece: ga + eck: ga + self: ga + serverless: ga +``` + +Technical preview that is still supported on every deployment: + +```yaml +applies_to: + stack: preview 9.2 + ech: ga + ece: ga + eck: ga + self: ga + serverless: ga +``` + +Self-managed only: + +```yaml +applies_to: + stack: ga 9.2 + ech: unavailable + ece: unavailable + eck: unavailable + self: ga + serverless: unavailable +``` + ### Example See `/syntax/settings-with-applies-example.yml` for a full, schema-compliant sample. @@ -89,8 +150,10 @@ It demonstrates: - Setting `id`, `datatype`, `default`, and `options`. - `note`, `tip`, `warning`, `important`, and `deprecation_details`. - Nested `settings`. -- `applies_to` inheritance and override behavior. +- A complete `applies_to` map, including `unavailable` keys and `stack: preview` with `ech: ga`. +- `applies_to` inheritance when a child omits the field, and replacement when it sets its own map. - Inline `{applies_to}` badges inside a setting `description` (for example, to label per-version defaults in a bulleted list). +- A gated `warning` with `:applies_to:` on the first line. - Top-level `page_description`. ### Result diff --git a/docs/syntax/settings-with-applies-example.yml b/docs/syntax/settings-with-applies-example.yml index 0b71f3c42e..1e426fc706 100644 --- a/docs/syntax/settings-with-applies-example.yml +++ b/docs/syntax/settings-with-applies-example.yml @@ -23,8 +23,12 @@ groups: datatype: bool default: "true" applies_to: - stack: ga 9.2 + stack: preview 9.2 ech: ga + ece: ga + eck: ga + self: ga + serverless: ga options: - option: "true" description: Turns the feature on. @@ -41,12 +45,19 @@ groups: default: strict applies_to: stack: ga 9.2 + ech: ga + ece: ga + eck: ga + self: ga + serverless: ga options: - option: strict description: Full validation. - option: lenient description: Reduced validation. - warning: Lenient mode may hide configuration mistakes. + warning: | + :applies_to: stack: ga 9.2 + Lenient mode may hide configuration mistakes. important: Strict mode is recommended for production. deprecation_details: The `lenient` option will be deprecated in a future release. example: | @@ -76,7 +87,11 @@ groups: default: "[]" applies_to: stack: ga 9.2 + ech: unavailable + ece: unavailable + eck: unavailable self: ga + serverless: unavailable settings: - setting: "[n].url" id: xpack-example-hosts-url @@ -87,7 +102,7 @@ groups: - setting: "[n].mode" id: xpack-example-hosts-mode description: | - Child setting overrides applies_to. + Child setting replaces the parent applies_to map. datatype: enum default: strict tip: Keep all host modes aligned to simplify troubleshooting and reduce drift. @@ -98,6 +113,11 @@ groups: description: Allows lenient checks. applies_to: stack: preview 9.3 + ech: unavailable + ece: unavailable + eck: unavailable + self: ga + serverless: unavailable example: | ```yaml xpack.example.hosts: From cfddc0a04886a21b05689524d2af8a209c0d801c Mon Sep 17 00:00:00 2001 From: Florent LB Date: Wed, 2 Sep 2026 17:17:29 +0200 Subject: [PATCH 2/5] Update docs/syntax/automated_settings.md Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> --- docs/syntax/automated_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/automated_settings.md b/docs/syntax/automated_settings.md index b0b2c295a5..019c4f9bd5 100644 --- a/docs/syntax/automated_settings.md +++ b/docs/syntax/automated_settings.md @@ -92,7 +92,7 @@ In body Markdown, name only the keys that apply to the content. In settings YAML | Key | What it means here | Write | |---|---|---| -| `stack` | Lifecycle and version of the setting | `ga`, `preview 9.2`, or a history such as `preview 9.0-9.2, ga 9.3+`. No version means all versions. | +| `stack` | The setting's lifecycle and versions it's available in | `ga`, `preview 9.2`, or a history such as `preview 9.0-9.2, ga 9.3+`. Omit the version if the setting was added before 9.0. | | `ech`, `ece`, `eck`, `self` | Supported on that deployment, or not | Always list all four. `ga` if supported. `unavailable` if not. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. | | `serverless` | Supported on serverless, or not | Always list it. `ga` if supported. `unavailable` if not. Never a version. | From 442b2d0d37cc6a7f50925e8a19abe5b3be07b808 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Wed, 2 Sep 2026 17:19:21 +0200 Subject: [PATCH 3/5] Apply suggestion from @florent-leborgne --- docs/syntax/automated_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/automated_settings.md b/docs/syntax/automated_settings.md index 019c4f9bd5..630e2da475 100644 --- a/docs/syntax/automated_settings.md +++ b/docs/syntax/automated_settings.md @@ -88,7 +88,7 @@ groups: The keys are the same as [Applies to](applies.md). The authoring contract is different, because each setting renders a **Supported on** line. -In body Markdown, name only the keys that apply to the content. In settings YAML, list every deployment key so that line is complete and the `:deployment:` filter is explicit. +In settings YAML, list every deployment key so that line is complete and the `:deployment:` filter is explicit. | Key | What it means here | Write | |---|---|---| From c7deb7f6f3f32cd2c975f401bba884f02f1ada4f Mon Sep 17 00:00:00 2001 From: Florent LB Date: Wed, 2 Sep 2026 17:26:07 +0200 Subject: [PATCH 4/5] Document nested serverless project keys in settings YAML A scalar serverless flag over-claims when a setting exists on only one serverless project. Nest elasticsearch, observability, and security when they differ. Co-Authored-By: Cursor Grok 4.6 Co-authored-by: Cursor --- docs/syntax/automated_settings.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/syntax/automated_settings.md b/docs/syntax/automated_settings.md index 630e2da475..456bb6d516 100644 --- a/docs/syntax/automated_settings.md +++ b/docs/syntax/automated_settings.md @@ -94,10 +94,16 @@ In settings YAML, list every deployment key so that line is complete and the `:d |---|---|---| | `stack` | The setting's lifecycle and versions it's available in | `ga`, `preview 9.2`, or a history such as `preview 9.0-9.2, ga 9.3+`. Omit the version if the setting was added before 9.0. | | `ech`, `ece`, `eck`, `self` | Supported on that deployment, or not | Always list all four. `ga` if supported. `unavailable` if not. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. | -| `serverless` | Supported on serverless, or not | Always list it. `ga` if supported. `unavailable` if not. Never a version. | +| `serverless` | Supported on serverless, or not | Always list it. `ga` if every serverless project supports it. `unavailable` if none do. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. | `ga` on a deployment key is a support flag. It does not mean the setting is generally available. If `stack` is `preview` and the setting exists on Elastic Cloud Hosted, write `ech: ga`. +If availability differs by serverless project, nest `elasticsearch`, `observability`, and `security` under `serverless`. Those keys are support flags too. Write `ga` or `unavailable`. Never write a version. Never write `preview`, `experimental`, `deprecated`, or `removed`. + +List all three project keys. Do not mix a scalar `serverless:` with project keys. + +Existing settings YAML sometimes lists those project keys as siblings of `stack`. That form still parses. Prefer the nested `serverless:` map for new entries. + `unavailable` is not rendered as a badge. It hides the setting from `:deployment:`. Omitting a deployment key also hides it from that filter. Still write `unavailable` so the Supported on line is complete. Child settings inherit the parent's `applies_to` when they omit the field. If a child sets `applies_to`, that map replaces the parent. It does not merge keys. @@ -140,6 +146,21 @@ applies_to: serverless: unavailable ``` +Observability serverless only: + +```yaml +applies_to: + stack: ga 9.2 + ech: ga + ece: ga + eck: ga + self: ga + serverless: + observability: ga + elasticsearch: unavailable + security: unavailable +``` + ### Example See `/syntax/settings-with-applies-example.yml` for a full, schema-compliant sample. From 15758cdf8dd3a6a1428707db6c53a661dd09cdc5 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Wed, 2 Sep 2026 19:28:49 +0200 Subject: [PATCH 5/5] Scope nested serverless keys to project-specific settings Advanced Settings may exist on only some serverless projects. Nest elasticsearch, observability, or security when that is true. Co-Authored-By: Cursor Grok 4.6 Co-authored-by: Cursor --- docs/syntax/automated_settings.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/syntax/automated_settings.md b/docs/syntax/automated_settings.md index 456bb6d516..5e0afafa2a 100644 --- a/docs/syntax/automated_settings.md +++ b/docs/syntax/automated_settings.md @@ -94,13 +94,13 @@ In settings YAML, list every deployment key so that line is complete and the `:d |---|---|---| | `stack` | The setting's lifecycle and versions it's available in | `ga`, `preview 9.2`, or a history such as `preview 9.0-9.2, ga 9.3+`. Omit the version if the setting was added before 9.0. | | `ech`, `ece`, `eck`, `self` | Supported on that deployment, or not | Always list all four. `ga` if supported. `unavailable` if not. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. | -| `serverless` | Supported on serverless, or not | Always list it. `ga` if every serverless project supports it. `unavailable` if none do. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. | +| `serverless` | Supported on serverless, or not | Always list it. `ga` if every serverless project supports it. `unavailable` if none do. Never a version. Never `preview`, `experimental`, `deprecated`, or `removed`. If only some projects support it, nest those project keys. | `ga` on a deployment key is a support flag. It does not mean the setting is generally available. If `stack` is `preview` and the setting exists on Elastic Cloud Hosted, write `ech: ga`. -If availability differs by serverless project, nest `elasticsearch`, `observability`, and `security` under `serverless`. Those keys are support flags too. Write `ga` or `unavailable`. Never write a version. Never write `preview`, `experimental`, `deprecated`, or `removed`. +Some settings exist on only some serverless projects. This is common for Advanced Settings. When that is the case, nest those project keys under `serverless`. The keys are `elasticsearch`, `observability`, and `security`. Write `ga` on the projects that include the setting. Those keys are support flags. Never write a version. Never write `preview`, `experimental`, `deprecated`, or `removed`. -List all three project keys. Do not mix a scalar `serverless:` with project keys. +Do not mix a scalar `serverless:` with project keys. Existing settings YAML sometimes lists those project keys as siblings of `stack`. That form still parses. Prefer the nested `serverless:` map for new entries. @@ -157,8 +157,6 @@ applies_to: self: ga serverless: observability: ga - elasticsearch: unavailable - security: unavailable ``` ### Example