Add "Key Concepts" documentation #5275
Conversation
docs/docs/understand/key_concepts.md
Outdated
| ## Data Sources | ||
|
|
||
| Data sources complement providers by fetching additional contextual information from | ||
| third-party APIs. While providers manage entities, data sources provide: |
There was a problem hiding this comment.
What do you think about updating the examples below, so it doesn't sound like data sources are solely for the purpose of enriching information about dependencies?
There was a problem hiding this comment.
Made some changes, what do you think?
docs/docs/understand/key_concepts.md
Outdated
|
|
||
| 2. *Evaluation*: Minder evaluates the entity against defined policies. | ||
|
|
||
| 3. *Remediation*: Issues identified during evaluation are flagged or resolved. |
There was a problem hiding this comment.
Should this be called Actions or perhaps add Alerting too to the list?
JAORMX
force-pushed
the
key-concepts
branch
2 times, most recently
from
35fe1f7 to
e5b5f99
Compare
This adds a new page that gives an overview of the different concepts in Minder. It starts adding the items that were recently implemented and are yet to be documented Signed-off-by: Juan Antonio Osorio <[email protected]>
There was a problem hiding this comment.
Thanks for starting this doc! Having some content and a straw-man organization really helped me wrap my head around what information we might want to present.
Let me know if you want me to PR to your branch for any of this content; I recognize that I've suggested a fairly large content rework.
| Providers communicate with Minder through APIs, webhook events, and scheduled updates. This ensures | ||
| continuous monitoring and up-to-date information about the entities they manage. | ||
|
|
||
| ## Entities and Checkpoints |
There was a problem hiding this comment.
I feel like if I were introducing Minder, I'd start with Entities, then move on to Providers ("where do entities come from"), then move on to "what do I do with entities" to introduce Profiles and Rules (I don't think we have a "Policy" entity), probably starting with the collection (Profiles) and then going down to RuleTypes.
I'd think of all of the above as "control plane" concepts -- they cover long-lived resources that users might create or manage directly.
I'd then have a second section on "Rule Evaluation" -- the "data plane" of Minder where things change based on external activity. I'd probably lay this out as "what is an Evaluation" (introduce the stages of ingestion, evaluation, remediation, and alerting), then talk about Ingesters, Checkpoints, Evaluation Engines (Rego and JQ), Data Sources, and Remediations and Alerts.
Here's a TOC, I think we could mostly just re-arrange the content:
- General Minder Introduction
- Managing Supply Chains with Minder
- Entities
- Providers
- Origination
- Profiles
- Rule Types
- Executing Policy with Minder
- The Phases of Rule Evaluation
- Ingesters
- Checkpoints
- Historical Evaluation records
- Evaluation Engines
- Data Sources
- Remediations and Alerts
| Checkpoints are points in time that capture the state of an entity. These snapshots enable: | ||
|
|
||
| * Auditability: Tracking changes and compliance over time. | ||
|
|
||
| * Granular Analysis: Evaluating an entity’s state at specific moments, such as a commit hash or artifact digest. |
There was a problem hiding this comment.
Can users see checkpoints, or are those an internal implementation detail? I wasn't aware that we were exposing these externally.
|
|
||
| * Granular Analysis: Evaluating an entity’s state at specific moments, such as a commit hash or artifact digest. | ||
|
|
||
| **Entity Lifecycle**: |
There was a problem hiding this comment.
Nit: why not use semantic markup (###) rather than bold styling?
|
|
||
| 3. *Action*: Issues identified during evaluation are either remediated or alerted. | ||
|
|
||
| ## Policies, Rules, and Profiles |
There was a problem hiding this comment.
| ## Policies, Rules, and Profiles | |
| ## Rules and Profiles |
| ## Origination | ||
|
|
||
| Origination describes one type of relationships between entities. For instance: | ||
|
|
||
| * A pull request originates from a repository. | ||
|
|
||
| This concept ensures that Minder maintains lifecycle consistency by: | ||
|
|
||
| * Automatically creating derived entities (e.g., pull requests) based on originating ones. | ||
|
|
||
| * Cleaning up dependent entities when the originating entity is removed. | ||
|
|
||
| Example Relationships: | ||
|
|
||
| Repository -> Pull Request | ||
|
|
||
| Repository -> Release |
There was a problem hiding this comment.
This feels weird here -- it feels like it belongs with either providers or entity lifecycle ("where do entities come from")
|
PRing to this PR is fine! Thanks for the thorough review |
Summary
This adds a new page that gives an overview of the different concepts in
Minder. It starts adding the items that were recently implemented and
are yet to be documented
Change Type
Mark the type of change your PR introduces:
Testing
Outline how the changes were tested, including steps to reproduce and any relevant configurations.
Attach screenshots if helpful.
Review Checklist: