[Request] Generate config settings docs

[kilfoyle]

Our first YAML-sourced config settings file is now fully ready to render into the docs output.

I've:

• Converted all descriptions, admonitions, and examples to Markdown format.
• Added applies_to properties with the versioning details (Note that these aren't exhaustive: I'm basically saying "supported on self-hosted and cloud" versus "supported on self-hosted only", since that's all I know for any given setting, and that's all that we currently have documented.).

This early Automated settings reference prototype looks very nice. I think what we still need is:

• Split the setting descriptions into multiple paragraphs.
• Call out the datatype, and any default or options on separate lines.
• Make sure that code examples are rendering.

---

xpack.actions.ssl.proxyVerificationMode

Controls the verification for the proxy server certificate that Kibana receives when making an outbound SSL/TLS connection to the proxy server.

Use full to perform hostname verification, certificate to skip hostname verification, and none to skip verification.

Equivalent Kibana setting

Datatype: enum
Default: full
Options:

• full
• certificate
• none

---

[lcawl]

In case it affects this issue, I've done some cleanup and consolidation of the manually-maintained copy of this settings file in elastic/kibana#214934, so we'd want to make sure any changes there are reflected in the yaml too before replacing the markdown file.

[kilfoyle]

@lcawl Thanks for the heads up. I can redo the yaml version of the Alert and Action settings file. Can you please tag me on the issue or PR for "Part 2" of the cleanup work when it happens? I might as well wait until that's complete just to avoid porting the changes over twice.

[lcawl]

Another passing note based on a slack thread where folks were asking how/if version-specific changes to the behaviour of settings would be called out. My assumption is that when there are significant changes to the behaviour in a setting (e.g. the index.codec setting was given as an example of one that changed between 8.14 and 8.17), they would be covered in prose in the description. Ideally when this rolls out we'll give some concrete examples of how to do that well.

It also makes me think the applies_to in these setting files should support all the same values as https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/applies#sections (i.e. so that we can indicate when a setting was added, removed, etc and what its lifecycle state is). If that occurs I think the state: deprecated/hidden/tech-preview field becomes redundant. If there's a more appropriate meta-issue to use for these future musings, lmk!

[lcawl]

Until the output can be generated automatically in markdown format (or read directly in yaml format), I've been manually copying changes into markdown format. For example, in elastic/kibana#220058

[kilfoyle]

Just in case it helps with testing or anything, I've opened a set of draft PRs for some of the other Kibana settings pages to convert them to YAML. All of those PRs are listed in elastic/kibana#206138

Also, just as a note: Some other pages, like the security settings for example, have groups nested within other groups, so I'm not sure yet how those should be handled.

[bmorelli25]

Note: Needs documentation on how to extend this functionality beyond Kibana docs. This includes showing how Kibana turns code into yaml files.

[kilfoyle]

Needs documentation on how to extend this functionality beyond Kibana docs. This includes showing how Kibana turns code into yaml files.

@bmorelli25 I'm not sure if this means that I should provide some docs? If there's anything I can help with or if a brief chat with the docs engineers would help, let me know.

For "showing how Kibana turns code into yaml files" this has only been done manually so far.

For "how to extend this functionality beyond Kibana docs" there's one limitation with the current yaml schema that we might want to chat about, but apart from that issue I think the schema should work for Elasticsearch config settings in the same way as for Kibana config settings.

Anyhow, happy to help! :-)

[bmorelli25]

Hey David 👋 . Sorry for the confusion.

For "showing how Kibana turns code into yaml files" this has only been done manually so far.

Aha! I didn't realize this was the case. I expected docs eng to be able to show how Kibana implemented that as an example for other teams.

For "how to extend this functionality beyond Kibana docs" there's one limitation with the current yaml schema that we might want to chat about, but apart from that issue I think the schema should work for Elasticsearch config settings in the same way as for Kibana config settings.

Are you able to share that limitation in this thread?

[kilfoyle]

Are you able to share that limitation in this thread?

Certainly! So, many config settings pages have settings divided into groups. For example, the Alerting and action settings page has groups: "General settings", "Action settings", "Preconfigured connector settings", and "Alerting settings". To account for this, the proposed YAML schema has a settings property, with all of the settings, nested within a groups property. All config pages would have at least one group. For most cases this is okay.

However, there are some outliers. Kibana pages like Security settings and Reporting settings have groups of settings nested within other groups.

For example:

• Security settings in Kibana
  • Encrypted saved objects settings
    • Audit logging settings
    • etc.

We could accommodate cases like these by expanding the YAML schema to allow for nested groups. However, I worry that created a schema that's overly complicated is partly defeating our goal of trying to make it easier for people to contribute to and maintain these docs. Alternatively, we could not support nested groups, which would mean reorganizing (flattening) these pages somehow.

One other complexity is the Fleet settings page which has settings nested below other settings, but for that one I think the docs page should be reworked rather than accommodated by the YAML.