elastic / elastic/docs-builder

Settings YAML: support per-offering default values (serverless-observability, serverless-security, etc.)

Open
#3,296 2 comments 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question ai:writer-question needs triage stale
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.