add configs api docs

[agrahamlincoln]

Signed-off-by: Graham Rounds [email protected]

---

Wrote this when exploring ruler/configs functionality and figured it would be valuable the official repo. Please correct anything incorrect and/or misleading I may have overlooked.

[tomwilkie]

Thanks @agrahamlincoln, this LGTM! We need a second +1 to merge though. @gouthamve @bboreham @csmarchbanks ?

[csmarchbanks]

Thanks for the writeup!

I left a couple of comments, in addition, I think both /api/prom/configs/rules and /api/prom/config/alertmanager take/return all the config (all rules files, and alertmanager config).

It's been awhile since I used this API, so sorry if I am not remembering correctly!

[jtlisi]

@csmarchbanks It does take a different input. Here is an example:

{
  "new_config": {
    "format_version": "2",
    "files": {
      "example_rules.yaml": "groups:\n  - name: test\n    rules:\n    - record: test_ruler_sum_up\n      expr: sum(up)"
    }
  },
  "old_config": {
    "format_version": "2",
    "files": {
      "example_rules.yaml": ""
    }
  }
}```

[agrahamlincoln]

Thanks for all the feedback! I've added the templates API endpoints, and updated the examples to be accurate. Let me know if there is anything else incorrect or that could use more elaboration.

[rsteneteg]

@agrahamlincoln, I read the updated document, and it sounds like you can send a partial update with only templates or only rules etc.. but that is not correct, each post to any of the endpoints will replace the config with whatever was in the request. So you will need to post everything AM config, rules, templates in each request for all endpoints.

[rsteneteg]

It would however be nice if you could post a partial update with only templates or rules etc, we should create a task to fix that

[bboreham]

I think partial updates are listed as part of #619

[bboreham]

I took the liberty of pushing to your branch some updates which I think bring it more into line with what the code implements.

Also I don't think we should include internal APIs in the same doc.

[bboreham]

This can probably close #322

[agrahamlincoln]

I took the liberty of pushing to your branch some updates which I think bring it more into line with what the code implements.

Thanks! I appreciate you bringing together links to paint some color around why the behavior is what it is today.

[agrahamlincoln]

Given that POST requests use the same payload, I consolidated them all into a section and used the extra real-estate to document expected return codes.

I'm pretty comfortable with this doc at this point - but definitely open to any more feedback

[bboreham]

Let's merge this now, then any further updates can be a new PR.

[bboreham]

"compatability" is triggering a CI failure - better fix that or CI will be broken on master

[csmarchbanks]

This LGTM now.