From 891419f25385921dd0a1e0603b50a57ee4fbaae0 Mon Sep 17 00:00:00 2001 From: Graham Rounds Date: Thu, 31 Jan 2019 13:31:19 -0800 Subject: [PATCH 1/7] add configs api docs Signed-off-by: Graham Rounds --- docs/configs-api.md | 95 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/configs-api.md diff --git a/docs/configs-api.md b/docs/configs-api.md new file mode 100644 index 00000000000..3d5988a58ac --- /dev/null +++ b/docs/configs-api.md @@ -0,0 +1,95 @@ +# Configs API + +The configs api provides API-driven multi-tenant approach to prometheus' Rule files and Alertmanager configs. + +Each tenant has a single Rule file and Alertmanager Configuration. A POST operation will effectively replace the existing copy with the configs provided in the request body. + +Although Prometheus works with YAML files by default, these HTTP API's only accept JSON. You may convert your YAML to JSON using a tool such as [yaml2json](https://github.com/bronze1man/yaml2json). + +### Manage Rules + +`GET /api/prom/configs/rules` - Get current rule file + +`POST /api/prom/configs/rules` - Replace current rule file + +Returns and Accepts a JSON object representing a [Prometheus rule file](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#recording-rules). + +Example: + +```json +{ + "groups": [ + { + "name": "example", + "rules": [ + { + "record": "job:http_inprogress_requests:sum", + "expr": "sum(http_inprogress_requests) by (job)" + } + ] + } + ] +} +``` + +### Manage Alertmanager + +`GET /api/prom/configs/alertmanager` - Get current Alertmanager config + +`POST /api/prom/configs/alertmanager` - Replace current Alertmanager config + +`POST /api/prom/configs/alertmanager/validate` - Validate Alertmanager config + +Returns and Accepts a JSON object representing an [Alertmanager configuration file](https://prometheus.io/docs/alerting/configuration/#configuration-file). + +Example: + +```json +{ + "global": { + "slack_api_url": "http://my.slack.com/webhook/url" + }, + "route": { + "receiver": "default-receiver", + "group_wait": "30s", + "group_interval": "5m", + "repeat_interval": "4h", + "group_by": [ "cluster", "alertname" ], + "routes": [ + { + "receiver": "database-pager", + "group_wait": "10s", + "match_re": { + "service": "mysql|cassandra" + } + }, + { + "receiver": "frontend-pager", + "group_by": [ "product", "environment" ], + "match": { + "team": "frontend" + } + } + ] + } +} +``` + +**Note:** Template files and Email Notifications are not supported in Cortex yet. + + +### Deactivate/Restore Configs + +`DELETE /api/prom/configs/deactivate` - Disable Alertmanager config & rule file + +`POST /api/prom/configs/restore` - Re-enable Alertmanager config & rule file + +These API endpoints will disable/enable the current Rule and Alertmanager configuration for a tenant. + +Note that setting a new config will effectively "re-enable" the Rules and Alertmanager configuration for a tenant. + +### Internal APIs + +`GET /private/api/prom/configs/rules` - Get current rule file + +`GET /private/api/prom/configs/alertmanager` - Get current Alertmanager config \ No newline at end of file From 51e9bcb7134c943251b9f4f4229e2060acadbf35 Mon Sep 17 00:00:00 2001 From: Graham Rounds Date: Mon, 22 Apr 2019 20:19:34 -0700 Subject: [PATCH 2/7] address reviewer comments Signed-off-by: Graham Rounds --- docs/configs-api.md | 95 ++++++++++++++++++++------------------------- 1 file changed, 43 insertions(+), 52 deletions(-) diff --git a/docs/configs-api.md b/docs/configs-api.md index 3d5988a58ac..3ff5ada4aa3 100644 --- a/docs/configs-api.md +++ b/docs/configs-api.md @@ -1,10 +1,24 @@ # Configs API -The configs api provides API-driven multi-tenant approach to prometheus' Rule files and Alertmanager configs. +The configs service provides an API-driven multi-tenant approach to handling various configuration files for prometheus. The service hosts an API where users can read and write Prometheus rule files, Alertmanager configuration files, and Alertmanager templates to a database. -Each tenant has a single Rule file and Alertmanager Configuration. A POST operation will effectively replace the existing copy with the configs provided in the request body. +Each tenant will have it's own set of rule files, Alertmanager config, and templates. A POST operation will effectively replace the existing copy with the configs provided in the request body. -Although Prometheus works with YAML files by default, these HTTP API's only accept JSON. You may convert your YAML to JSON using a tool such as [yaml2json](https://github.com/bronze1man/yaml2json). +### Manage Alertmanager + +`GET /api/prom/configs/alertmanager` - Get current Alertmanager config + +`POST /api/prom/configs/alertmanager` - Replace current Alertmanager config + +`POST /api/prom/configs/alertmanager/validate` - Validate Alertmanager config + +Example Payload: + +```json +{ + "alertmanager_config": "" +} +``` ### Manage Rules @@ -12,77 +26,54 @@ Although Prometheus works with YAML files by default, these HTTP API's only acce `POST /api/prom/configs/rules` - Replace current rule file -Returns and Accepts a JSON object representing a [Prometheus rule file](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#recording-rules). - Example: ```json { - "groups": [ - { - "name": "example", - "rules": [ - { - "record": "job:http_inprogress_requests:sum", - "expr": "sum(http_inprogress_requests) by (job)" - } - ] - } - ] + "rules_files": { + "rules.yaml": "", + "rules2.yaml": "", + }, + "rule_format_version": "2", } ``` -### Manage Alertmanager +### Manage Templates -`GET /api/prom/configs/alertmanager` - Get current Alertmanager config +`GET /api/prom/configs/templates` - Get current templates -`POST /api/prom/configs/alertmanager` - Replace current Alertmanager config +`POST /api/prom/configs/templates` - Replace current templates -`POST /api/prom/configs/alertmanager/validate` - Validate Alertmanager config +```json +{ + "template_files": { + "templates.tmpl": "", + "templates2.tmpl": "" + } +} +``` -Returns and Accepts a JSON object representing an [Alertmanager configuration file](https://prometheus.io/docs/alerting/configuration/#configuration-file). +### Update All Files -Example: +One can update all types of files together by combining the POST body. Any of the `POST /api/prom/configs/*` endpoints will update any files provided. + +The following content would update both the Alertmanager configuration and the Alertmanager templates: ```json { - "global": { - "slack_api_url": "http://my.slack.com/webhook/url" - }, - "route": { - "receiver": "default-receiver", - "group_wait": "30s", - "group_interval": "5m", - "repeat_interval": "4h", - "group_by": [ "cluster", "alertname" ], - "routes": [ - { - "receiver": "database-pager", - "group_wait": "10s", - "match_re": { - "service": "mysql|cassandra" - } - }, - { - "receiver": "frontend-pager", - "group_by": [ "product", "environment" ], - "match": { - "team": "frontend" - } - } - ] + "alertmanager_config": "", + "template_files": { + "templates.tmpl": "", + "templates2.tmpl": "" } } ``` -**Note:** Template files and Email Notifications are not supported in Cortex yet. - - ### Deactivate/Restore Configs -`DELETE /api/prom/configs/deactivate` - Disable Alertmanager config & rule file +`DELETE /api/prom/configs/deactivate` - Disable configs for a tenant -`POST /api/prom/configs/restore` - Re-enable Alertmanager config & rule file +`POST /api/prom/configs/restore` - Re-enable configs for a tenant These API endpoints will disable/enable the current Rule and Alertmanager configuration for a tenant. From 16d1f3165ec932fac7a30e99f1421399ca2dfc8d Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Fri, 3 May 2019 09:58:03 +0000 Subject: [PATCH 3/7] Updated examples and added more references All APIs take all data types; updated the examples and removed the implication that this might not be the case. Added `id` and `config` to examples, and link to Prometheus docs. Signed-off-by: Bryan Boreham --- docs/configs-api.md | 66 +++++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 23 deletions(-) diff --git a/docs/configs-api.md b/docs/configs-api.md index 3ff5ada4aa3..cb06d95b5c0 100644 --- a/docs/configs-api.md +++ b/docs/configs-api.md @@ -4,6 +4,9 @@ The configs service provides an API-driven multi-tenant approach to handling var Each tenant will have it's own set of rule files, Alertmanager config, and templates. A POST operation will effectively replace the existing copy with the configs provided in the request body. +At the current time of writing, the API is part-way through a migration from a single Configs service that handled all three sets of data to a split API. [Tracking issue](https://github.com/cortexproject/cortex/issues/619). So, unfortunately, all APIs take and return all sets of data. + + ### Manage Alertmanager `GET /api/prom/configs/alertmanager` - Get current Alertmanager config @@ -15,11 +18,21 @@ Each tenant will have it's own set of rule files, Alertmanager config, and templ Example Payload: ```json -{ - "alertmanager_config": "" +{ + "id": 99, + "rule_format_version": "2", + "config": { + "rules_files": { } + "alertmanager_config":"" + } } ``` +The ID should be incremented every time you update the data; Cortex +will use the config with the highest number. + +The contents of the config file should be as described [here](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/), encoded as a single string to fit within the overall JSON payload. + ### Manage Rules `GET /api/prom/configs/rules` - Get current rule file @@ -30,14 +43,27 @@ Example: ```json { - "rules_files": { - "rules.yaml": "", - "rules2.yaml": "", - }, + "id": 99, + "config": { + "alertmanager_config":"" + "rules_files": { + "rules.yaml": "", + "rules2.yaml": "", + }, + } "rule_format_version": "2", } ``` +The contents of the rules file should be as described [here](http://prometheus.io/docs/prometheus/latest/configuration/recording_rules/), encoded as a single string to fit within the overall JSON payload. + +The ID should be incremented every time you update the rules; Cortex +will use the config with the highest number. + +The `rule_format_version` allows compatibility for tenants with config +in Prometheus V1 format. Pass "1" or "2" according to which +Prometheus version you want to match. + ### Manage Templates `GET /api/prom/configs/templates` - Get current templates @@ -46,28 +72,22 @@ Example: ```json { - "template_files": { - "templates.tmpl": "", - "templates2.tmpl": "" + "id": 99, + "config": { + "alertmanager_config":"" + "rules_files": { } + "template_files": { + "templates.tmpl": "", + "templates2.tmpl": "" + } } } ``` -### Update All Files - -One can update all types of files together by combining the POST body. Any of the `POST /api/prom/configs/*` endpoints will update any files provided. +The contents of the template file should be as described [here](https://prometheus.io/docs/alerting/notification_examples/#defining-reusable-templates), encoded as a single string to fit within the overall JSON payload. -The following content would update both the Alertmanager configuration and the Alertmanager templates: - -```json -{ - "alertmanager_config": "", - "template_files": { - "templates.tmpl": "", - "templates2.tmpl": "" - } -} -``` +The ID should be incremented every time you update the data; Cortex +will use the config with the highest number. ### Deactivate/Restore Configs From fec6b50b033f7cb5e86d7178ca8da230e61afb0f Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Fri, 3 May 2019 10:01:55 +0000 Subject: [PATCH 4/7] Remove internal APIs from doc Signed-off-by: Bryan Boreham --- docs/configs-api.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/configs-api.md b/docs/configs-api.md index cb06d95b5c0..08bce98e775 100644 --- a/docs/configs-api.md +++ b/docs/configs-api.md @@ -98,9 +98,3 @@ will use the config with the highest number. These API endpoints will disable/enable the current Rule and Alertmanager configuration for a tenant. Note that setting a new config will effectively "re-enable" the Rules and Alertmanager configuration for a tenant. - -### Internal APIs - -`GET /private/api/prom/configs/rules` - Get current rule file - -`GET /private/api/prom/configs/alertmanager` - Get current Alertmanager config \ No newline at end of file From 365b9b5a0a96b9212a2125cfaaceb4e2674f4523 Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Fri, 3 May 2019 10:05:59 +0000 Subject: [PATCH 5/7] Fix my JSON typos Signed-off-by: Bryan Boreham --- docs/configs-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/configs-api.md b/docs/configs-api.md index 08bce98e775..3f12244b9ce 100644 --- a/docs/configs-api.md +++ b/docs/configs-api.md @@ -22,7 +22,7 @@ Example Payload: "id": 99, "rule_format_version": "2", "config": { - "rules_files": { } + "rules_files": { }, "alertmanager_config":"" } } @@ -45,12 +45,12 @@ Example: { "id": 99, "config": { - "alertmanager_config":"" + "alertmanager_config":"", "rules_files": { "rules.yaml": "", "rules2.yaml": "", }, - } + }, "rule_format_version": "2", } ``` @@ -74,8 +74,8 @@ Prometheus version you want to match. { "id": 99, "config": { - "alertmanager_config":"" - "rules_files": { } + "alertmanager_config":"", + "rules_files": { }, "template_files": { "templates.tmpl": "", "templates2.tmpl": "" From 19d2d51be3291e6cb2e8804992543b9809c067f8 Mon Sep 17 00:00:00 2001 From: Graham Rounds Date: Fri, 3 May 2019 11:14:08 -0700 Subject: [PATCH 6/7] consolidate configs format and add return codes to docs Signed-off-by: Graham Rounds --- docs/configs-api.md | 118 +++++++++++++++++++++++++------------------- 1 file changed, 66 insertions(+), 52 deletions(-) diff --git a/docs/configs-api.md b/docs/configs-api.md index 3f12244b9ce..09af6657ded 100644 --- a/docs/configs-api.md +++ b/docs/configs-api.md @@ -4,97 +4,111 @@ The configs service provides an API-driven multi-tenant approach to handling var Each tenant will have it's own set of rule files, Alertmanager config, and templates. A POST operation will effectively replace the existing copy with the configs provided in the request body. -At the current time of writing, the API is part-way through a migration from a single Configs service that handled all three sets of data to a split API. [Tracking issue](https://github.com/cortexproject/cortex/issues/619). So, unfortunately, all APIs take and return all sets of data. +## Configs Format +At the current time of writing, the API is part-way through a migration from a single Configs service that handled all three sets of data to a split API ([Tracking issue](https://github.com/cortexproject/cortex/issues/619)). All APIs take and return all sets of data. -### Manage Alertmanager - -`GET /api/prom/configs/alertmanager` - Get current Alertmanager config - -`POST /api/prom/configs/alertmanager` - Replace current Alertmanager config - -`POST /api/prom/configs/alertmanager/validate` - Validate Alertmanager config +The following schema is used both when retrieving the current configs from the API and when setting new configs via the API. -Example Payload: +### Schema: ```json { "id": 99, "rule_format_version": "2", "config": { - "rules_files": { }, - "alertmanager_config":"" + "alertmanager_config": "", + "rules_files": { + "rules.yaml": "", + "rules2.yaml": "" + }, + "template_files": { + "templates.tmpl": "", + "templates2.tmpl": "" + } } } ``` -The ID should be incremented every time you update the data; Cortex -will use the config with the highest number. +### Formatting -The contents of the config file should be as described [here](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/), encoded as a single string to fit within the overall JSON payload. +`id` - should be incremented every time data is updated; Cortex will use the config with the highest number. -### Manage Rules +`rule_format_version` - allows compatability for tenants with config in Prometheus V1 format. Pass "1" or "2" according to which Prometheus version you want to match. -`GET /api/prom/configs/rules` - Get current rule file +`config.alertmanager_config` - The contents of the alertmanager config file should be as described [here](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/), encoded as a single string to fit within the overall JSON payload. -`POST /api/prom/configs/rules` - Replace current rule file +`config.rules_files` - The contents of a rules file should be as described [here](http://prometheus.io/docs/prometheus/latest/configuration/recording_rules/), encoded as a single string to fit within the overall JSON payload. -Example: +`config.template_files` - The contents of a template file should be as described [here](https://prometheus.io/docs/alerting/notification_examples/#defining-reusable-templates), encoded as a single string to fit within the overall JSON payload. +## Endpoints + +### Manage Alertmanager + +`GET /api/prom/configs/alertmanager` - Get current Alertmanager config + +- Normal Response Codes: OK(200) +- Error Response Codes: Unauthorized(401), NotFound(404) + +`POST /api/prom/configs/alertmanager` - Replace current Alertmanager config + +- Normal Response Codes: NoContent(204) +- Error Response Codes: Unauthorized(401), BadRequest(400) + +`POST /api/prom/configs/alertmanager/validate` - Validate Alertmanager config + +Normal Response: OK(200) ```json -{ - "id": 99, - "config": { - "alertmanager_config":"", - "rules_files": { - "rules.yaml": "", - "rules2.yaml": "", - }, - }, - "rule_format_version": "2", +{ + "status": "success" } ``` -The contents of the rules file should be as described [here](http://prometheus.io/docs/prometheus/latest/configuration/recording_rules/), encoded as a single string to fit within the overall JSON payload. +Error Response: BadRequest(400) +```json +{ + "status": "error", + "error": "error message" +} +``` -The ID should be incremented every time you update the rules; Cortex -will use the config with the highest number. +### Manage Rules -The `rule_format_version` allows compatibility for tenants with config -in Prometheus V1 format. Pass "1" or "2" according to which -Prometheus version you want to match. +`GET /api/prom/configs/rules` - Get current rule files + +- Normal Response Codes: OK(200) +- Error Response Codes: Unauthorized(400), NotFound(404) + +`POST /api/prom/configs/rules` - Replace current rule files + +- Normal Response Codes: NoContent(204) +- Error Response Codes: Unauthorized(401), BadRequest(400) ### Manage Templates `GET /api/prom/configs/templates` - Get current templates -`POST /api/prom/configs/templates` - Replace current templates - -```json -{ - "id": 99, - "config": { - "alertmanager_config":"", - "rules_files": { }, - "template_files": { - "templates.tmpl": "", - "templates2.tmpl": "" - } - } -} -``` +- Normal Response Codes: OK(200) +- Error Response Codes: Unauthorized(401), NotFound(404) -The contents of the template file should be as described [here](https://prometheus.io/docs/alerting/notification_examples/#defining-reusable-templates), encoded as a single string to fit within the overall JSON payload. +`POST /api/prom/configs/templates` - Replace current templates -The ID should be incremented every time you update the data; Cortex -will use the config with the highest number. +- Normal Response Codes: NoContent(204) +- Error Response Codes: Unauthorized(401), BadRequest(400) ### Deactivate/Restore Configs `DELETE /api/prom/configs/deactivate` - Disable configs for a tenant +- Normal Response Codes: OK(200) +- Error Response Codes: Unauthorized(401), NotFound(404) + `POST /api/prom/configs/restore` - Re-enable configs for a tenant +- Normal Response Codes OK(200) +- Error Response Codes: Unauthorized(401), NotFound(404) + These API endpoints will disable/enable the current Rule and Alertmanager configuration for a tenant. Note that setting a new config will effectively "re-enable" the Rules and Alertmanager configuration for a tenant. From 576313f34e0fb01bff2eb18a17f29f2edf23c179 Mon Sep 17 00:00:00 2001 From: Graham Rounds Date: Fri, 3 May 2019 14:15:29 -0700 Subject: [PATCH 7/7] fix spelling error Signed-off-by: Graham Rounds --- docs/configs-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configs-api.md b/docs/configs-api.md index 09af6657ded..4b42ac7f963 100644 --- a/docs/configs-api.md +++ b/docs/configs-api.md @@ -34,7 +34,7 @@ The following schema is used both when retrieving the current configs from the A `id` - should be incremented every time data is updated; Cortex will use the config with the highest number. -`rule_format_version` - allows compatability for tenants with config in Prometheus V1 format. Pass "1" or "2" according to which Prometheus version you want to match. +`rule_format_version` - allows compatibility for tenants with config in Prometheus V1 format. Pass "1" or "2" according to which Prometheus version you want to match. `config.alertmanager_config` - The contents of the alertmanager config file should be as described [here](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/), encoded as a single string to fit within the overall JSON payload.