Docs: document the configuration file's format

[roy-work]

Is your documentation request related to a feature? If so, which one?

AFAICT, the format of the YAML config file is undocumented. There's some sparse examples of it, e.g., here, but no documentation.

For example, the documentation says,

Note: Blocks storage cannot be located in the same path of the same bucket as the ruler and alertmanager stores. When using the common configuration, make blocks_storage use either a:

• different bucket, overriding the common bucket name
• storage prefix

(Also note: the formatting appears to be messed up here: that list seems like it should be part of that … "blockquote" … but it isn't. I've replicated the error in Github, i.e., the original docs are also this way.)

But the only keys that seem to appear in the example are bucket_name and service_account. "Prefix" is never mentioned in an example of a config.

I did find the S3 config & the GCS config in the source code, so that at least gives me an idea of what keys exist & what they should be set to. (But having to read the source is a documentation failure, IMO.)

(The parent config struct is here.)

I'm still in the dark about prefix: the docs mention it, but neither the S3 nor GCS configs have an applicable sounding key. (Nor does the parent config.)

Edit: geez I was so close. There's a wrapping struct here — that has storage_prefix. This would be at the same level as s3, I think, so something like,

blocks_storage:
  s3: ...
  storage_prefix: 'asdf'

… now to try that out …

Describe the solution that you’d like or the expected outcome

The structure of the config documented, not leaving the user to attempt to infer the structure from a few short examples.

[pstibrany]

Hello,

config file structure is documented here: https://grafana.com/docs/mimir/latest/references/configuration-parameters/

Specifically:

• blocks_storage: https://grafana.com/docs/mimir/latest/references/configuration-parameters/#blocks_storage
• ruler_storage: https://grafana.com/docs/mimir/latest/references/configuration-parameters/#ruler_storage
• alertmanager_storage: https://grafana.com/docs/mimir/latest/references/configuration-parameters/#alertmanager_storage

all mention storage_prefix field.

(I'm sometimes lost in those section names myself, and I agree that could perhaps be improved. My personal preference would be to have tree-like view of structure of yaml file.)

[dimitarvdimitrov]

FYI @jdbaldry regarding how admonition displays on the website

[roy-work]

config file structure is documented here: https://grafana.com/docs/mimir/latest/references/configuration-parameters/

Ah! Perhaps a link from Configure → Object Storage? (which is where I was reading / got lost)

[jdbaldry]

Thanks for the heads up about the note formatting, that's actually fixed in https://grafana.com/docs/mimir/next/configure/configure-object-storage-backend/ thanks to https://github.com/grafana/mimir/pull/7420. I can backport to latest if we want to see those fixes live now.