Skip to content

Add a doc for APIs #1540

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 2, 2019
Merged

Add a doc for APIs #1540

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
01d290e
Rename Config API doc so we can cover all APIs in one doc
bboreham Aug 1, 2019
3530e03
Add brief documentation about Prometheus Remote APIs
bboreham Aug 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 24 additions & 9 deletions docs/configs-api.md → docs/apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,31 @@
# Configs API
# Cortex APIs

[this is a work in progress]

## Remote API

Cortex supports Prometheus'
[`remote_read`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_read)
and
[`remote_write`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write)
APIs. The encoding is Protobuf over http.

Read is on `/api/prom/read` and write is on `/api/prom/push`.


## Configs API

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 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.

## Configs Format
### 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.

The following schema is used both when retrieving the current configs from the API and when setting new configs via the API.

### Schema:
#### Schema:

```json
{
Expand All @@ -30,7 +45,7 @@ The following schema is used both when retrieving the current configs from the A
}
```

### Formatting
#### Formatting

`id` - should be incremented every time data is updated; Cortex will use the config with the highest number.

Expand All @@ -42,9 +57,9 @@ The following schema is used both when retrieving the current configs from the A

`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
### Endpoints

### Manage Alertmanager
#### Manage Alertmanager

`GET /api/prom/configs/alertmanager` - Get current Alertmanager config

Expand Down Expand Up @@ -73,7 +88,7 @@ Error Response: BadRequest(400)
}
```

### Manage Rules
#### Manage Rules

`GET /api/prom/configs/rules` - Get current rule files

Expand All @@ -85,7 +100,7 @@ Error Response: BadRequest(400)
- Normal Response Codes: NoContent(204)
- Error Response Codes: Unauthorized(401), BadRequest(400)

### Manage Templates
#### Manage Templates

`GET /api/prom/configs/templates` - Get current templates

Expand All @@ -97,7 +112,7 @@ Error Response: BadRequest(400)
- Normal Response Codes: NoContent(204)
- Error Response Codes: Unauthorized(401), BadRequest(400)

### Deactivate/Restore Configs
#### Deactivate/Restore Configs

`DELETE /api/prom/configs/deactivate` - Disable configs for a tenant

Expand Down