elastic / elastic/docs-builder
Settings YAML: support per-offering default values (serverless-observability, serverless-security, etc.)
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
## Problem
The settings YAML format currently supports a single `default:` scalar value per setting:
\`\`\`yaml
- setting: xpack.task_manager.capacity
datatype: int
default: 10
\`\`\`
However, many Kibana settings have **different effective defaults depending on the deployment type or serverless solution**. This is defined in the Kibana codebase at three layers:
1. **\`offeringBasedSchema\`** — a TypeScript utility that branches schema/defaults between \`serverless\` and \`traditional\` (stateful).
2. **\`config/serverless.yml\`** — base overrides for all serverless deployments.
3. **\`config/serverless.oblt.yml\` / \`config/serverless.security.yml\` / \`config/serverless.es.yml\`** — per-solution overrides that stack on top.
Example: a setting might have default \`1000\` on stateful, \`500\` on all serverless, and \`700\` specifically on serverless Observability.
There is currently no way to express this in the settings YAML, so docs either pick one value (usually the stateful default) or add a freeform prose note.
## Proposed solution
Extend the `default:` field to optionally accept a structured map of offering/solution-specific defaults alongside the base default:
\`\`\`yaml
- setting: xpack.task_manager.capacity
datatype: int
default: 10
default_overrides:
serverless: 20
serverless-observability: 20
serverless-security: 10
serverless-search: 10
\`\`\`
Or alternatively, keep `default:` as the stateful default and add a separate `defaults:` map:
\`\`\`yaml
- setting: xpack.apm.serviceMapFingerprintGlobalBucketSize
datatype: int
default: 1000
defaults:
serverless-observability: 700
serverless-security: 400
\`\`\`
The renderer could then display these as a small table or inline notes beneath the default value, similar to how `applies_to` already handles per-offering availability.
## Context
- Discovered while auditing all Kibana configuration reference YAML files against plugin config schemas and the ECH allowlist.
- The three-layer default system in Kibana makes it impossible to accurately document defaults with a single scalar today.
- Related: the `applies_to` field already has per-offering structure — `default` could follow the same pattern.
Contributor guide
Assessment
This issue has not been assessed yet.