docs: Mimir on Juju docs#361
Conversation
YanisaHS
left a comment
YanisaHS
left a comment
There was a problem hiding this comment.
Ok I've made a lot of high-level feedback, so have fun 😅
LMK if you have questions or want to discuss!
|
|
||
| This guide walks you through the prerequisites and deployment planning needed to install the Canonical Observability Stack (COS). Use it to prepare your environment, create a Terraform plan, and deploy supporting components in the recommended order. | ||
|
|
||
| ```{note} |
There was a problem hiding this comment.
This is going to get messy super fast though if you want to address other upstreams. I would remove this note and find a different way to work with these users.
The easiest resolution would be just to have a "Related topics" section at the bottom that links here (and if you have other key docs to link to)
The other option would be to understand what you want to accomplish with this note from a general sense - are you actually just targeting Mimir and won't be any other docs? Do you want to highlight other docs for HA users? For deploying standalone components?
E.g., you could also have a section at the bottom named "Standalone components" or "Other deployment options" (or ..... ) with a note like "If you're not deploying the whole Canonical Observability Stack, you can deploy some components independently:
- [mimir doc]
"
| ```{toctree} | ||
| :maxdepth: 1 | ||
|
|
||
| Standalone Mimir on Juju <mimir-on-juju> |
There was a problem hiding this comment.
In general, I would make this a how-to instead of a tutorial btw. But I give that feedback to your team many times now 😇
If it stays as a tutorial, I'd suggest moving it to the bottom of this list though, so it's the last tutorial on the sidebar
|
|
||
| # Get started with standalone Mimir on Juju | ||
|
|
||
| This tutorial is for readers who already know upstream Grafana Mimir and want |
There was a problem hiding this comment.
So these users might have no knowledge of Juju or what Mimir on Juju really is?
If yes, you should have some background information on what they need to know, like briefly what Juju is and link to their docs at least, what does it mean to be running Mimir on Juju, stuff like that
| This tutorial is for readers who already know upstream Grafana Mimir and want | ||
| the Juju-native path to a working deployment. | ||
|
|
||
| You will deploy a small standalone Mimir topology on Kubernetes, back it with |
There was a problem hiding this comment.
In general, I don't understand where the boundaries of COS actually are. I.e., why is this not considered COS? Is it just because it doesn't deploy the official COS bundle? (to me this is like "you're not deploying COS, you're just deploying a bunch of pieces of COS", which isn't considered COS?
Sharing that because to me this doesn't sound like deploying "standalone Mimir", it seems more like it's a "Mimir-focused" deployment, and that's what the difference is between this guide vs. a generic COS deployment. (i.e., that Mimir is the focus point, not the general COS bundle)
Calling this tutorial "standalone" Mimir might be confusing to someone unfamiliar with COS (or Juju), since it's not actually about just deploying Mimir as a single component. An alternative title/framing could be like "Deploy Mimir on Juju without the COS bundle" (or something like that)
| [Mimir Terraform module](https://github.com/canonical/mimir-operators/tree/main/terraform). | ||
| ``` | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
Are your users going to know how to meet these Prereqs? Any docs you can link to from these?
|
|
||
| You should see an `s3` integration between `mimir` and `mimir-s3`. | ||
|
|
||
| ## Recommended bucket layout |
There was a problem hiding this comment.
"bucket layout" sounds odd to me (although I'm not that familiar with the domain terminology here)
"Recommended deployment configuration"? "Recommended object-storage configuration" / "layout" ?
I don't really have an issue with "layout", but "bucket" isn't clear what it refers to IMO
|
|
||
| You should see an `s3` integration between `mimir` and `mimir-s3`. | ||
|
|
||
| ## Recommended bucket layout |
There was a problem hiding this comment.
I'm also confused why this section is at the bottom - aren't these relevant to know before you begin the guide? (similar to another comment I made in the next section)
| | Purpose | Recommendation | | ||
| |---|---| | ||
| | Bucket | Dedicated bucket per Mimir deployment | | ||
| | Credentials | Dedicated credentials per deployment | | ||
| | TLS | Prefer HTTPS in shared or production environments | | ||
| | Testing | Use Minio only for local or disposable environments | |
There was a problem hiding this comment.
Is this actually helpful? Maybe yes, idk. Just seems super broad to me
| Use this guide when your workload is **not** managed by Juju and you want to | ||
| ship its metrics into standalone Mimir. |
There was a problem hiding this comment.
Wait what does this mean? 😅
"Use this guide when you have an application outside Juju that exposes metrics, and you want to send those metrics into the Mimir deployment you created with Juju."
or
"Use this guide to send metrics from an application outside Juju to Mimir (Juju-managed)."
...something like that instead? (if that is actually what you meant?)
In general (I commented this in the tutorial too), I think you should find avoid saying "standalone Mimir", and also be clearer when it's Mimir on Juju. IMO "standalone Mimir" without anything else sounds like it's not related to Juju
| Use this guide when your workload is **not** managed by Juju and you want to | ||
| ship its metrics into standalone Mimir. | ||
|
|
||
| The recommended path is to run the OpenTelemetry Collector snap near the |
There was a problem hiding this comment.
Oh I just noticed it's the otelcol snap (not charm) - I think there should be more context about what's happening here in this guide. In general, just describe what's going to happen here (and why) before the actual steps start
2 participants
Issue
Based on: grafana/mimir#15202.
Solution
Checklist
Context
Testing Instructions
Upgrade Notes