mirror of
https://github.com/TwiN/gatus.git
synced 2024-12-14 11:58:04 +00:00
oidc: Add documentation
This commit is contained in:
TwiN
parent
139a78b2f6
commit
8838f6f2ad
1 changed files with 232 additions and 198 deletions
128
README.md
128
README.md
|
|
@ -51,6 +51,9 @@ Have any feedback or want to share your good/bad experience with Gatus? Feel fre
|
|||
- [Configuring custom alerts](#configuring-custom-alerts)
|
||||
- [Setting a default alert](#setting-a-default-alert)
|
||||
- [Maintenance](#maintenance)
|
||||
- [Security](#security)
|
||||
- [Basic](#basic)
|
||||
- [OIDC (ALPHA)](#oidc-alpha)
|
||||
- [Deployment](#deployment)
|
||||
- [Docker](#docker)
|
||||
- [Helm Chart](#helm-chart)
|
||||
|
|
@ -66,7 +69,6 @@ Have any feedback or want to share your good/bad experience with Gatus? Feel fre
|
|||
- [Monitoring an endpoint using DNS queries](#monitoring-an-endpoint-using-dns-queries)
|
||||
- [Monitoring an endpoint using STARTTLS](#monitoring-an-endpoint-using-starttls)
|
||||
- [Monitoring an endpoint using TLS](#monitoring-an-endpoint-using-tls)
|
||||
- [Basic authentication](#basic-authentication)
|
||||
- [disable-monitoring-lock](#disable-monitoring-lock)
|
||||
- [Reloading configuration on the fly](#reloading-configuration-on-the-fly)
|
||||
- [Endpoint groups](#endpoint-groups)
|
||||
|
|
@ -142,7 +144,7 @@ If you want to test it locally, see [Docker](#docker).
|
|||
|
||||
## Configuration
|
||||
| Parameter | Description | Default |
|
||||
|:---------------------------------------- |:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------|
|
||||
| `debug` | Whether to enable debug logs. | `false` |
|
||||
| `metrics` | Whether to expose metrics at /metrics. | `false` |
|
||||
| `storage` | [Storage configuration](#storage) | `{}` |
|
||||
|
|
@ -171,10 +173,7 @@ If you want to test it locally, see [Docker](#docker).
|
|||
| `endpoints[].ui.hide-hostname` | Whether to include the hostname in the result. | `false` |
|
||||
| `endpoints[].ui.dont-resolve-failed-conditions` | Whether to resolve failed conditions for the UI. | `false` |
|
||||
| `alerting` | [Alerting configuration](#alerting). | `{}` |
|
||||
| `security` | Security configuration. | `{}` |
|
||||
| `security.basic` | Basic authentication security configuration. | `{}` |
|
||||
| `security.basic.username` | Username for Basic authentication. | Required `""` |
|
||||
| `security.basic.password-sha512` | Password's SHA512 hash for Basic authentication. | Required `""` |
|
||||
| `security` | [Security configuration](#security). | `{}` |
|
||||
| `disable-monitoring-lock` | Whether to [disable the monitoring lock](#disable-monitoring-lock). | `false` |
|
||||
| `skip-invalid-config-update` | Whether to ignore invalid configuration update. <br />See [Reloading configuration on the fly](#reloading-configuration-on-the-fly). | `false` |
|
||||
| `web` | Web configuration. | `{}` |
|
||||
|
|
@ -190,7 +189,7 @@ If you want to test it locally, see [Docker](#docker).
|
|||
Here are some examples of conditions you can use:
|
||||
|
||||
| Condition | Description | Passing values | Failing values |
|
||||
|:-----------------------------|:------------------------------------------------------- |:-------------------------- | -------------- |
|
||||
|:---------------------------------|:----------------------------------------------------|:---------------------------|------------------|
|
||||
| `[STATUS] == 200` | Status must be equal to 200 | 200 | 201, 404, ... |
|
||||
| `[STATUS] < 300` | Status must lower than 300 | 200, 201, 299 | 301, 302, ... |
|
||||
| `[STATUS] <= 299` | Status must be less than or equal to 299 | 200, 201, 299 | 301, 302, ... |
|
||||
|
|
@ -214,30 +213,30 @@ Here are some examples of conditions you can use:
|
|||
|
||||
#### Placeholders
|
||||
| Placeholder | Description | Example of resolved value |
|
||||
|:-------------------------- |:--------------------------------------------------------------- |:------------------------- |
|
||||
| `[STATUS]` | Resolves into the HTTP status of the request | 404
|
||||
| `[RESPONSE_TIME]` | Resolves into the response time the request took, in ms | 10
|
||||
| `[IP]` | Resolves into the IP of the target host | 192.168.0.232
|
||||
| `[BODY]` | Resolves into the response body. Supports JSONPath. | `{"name":"john.doe"}`
|
||||
| `[CONNECTED]` | Resolves into whether a connection could be established | `true`
|
||||
| `[CERTIFICATE_EXPIRATION]` | Resolves into the duration before certificate expiration | `24h`, `48h`, 0 (if not protocol with certs)
|
||||
| `[DNS_RCODE]` | Resolves into the DNS status of the response | NOERROR
|
||||
|:---------------------------|:---------------------------------------------------------|:---------------------------------------------|
|
||||
| `[STATUS]` | Resolves into the HTTP status of the request | 404 |
|
||||
| `[RESPONSE_TIME]` | Resolves into the response time the request took, in ms | 10 |
|
||||
| `[IP]` | Resolves into the IP of the target host | 192.168.0.232 |
|
||||
| `[BODY]` | Resolves into the response body. Supports JSONPath. | `{"name":"john.doe"}` |
|
||||
| `[CONNECTED]` | Resolves into whether a connection could be established | `true` |
|
||||
| `[CERTIFICATE_EXPIRATION]` | Resolves into the duration before certificate expiration | `24h`, `48h`, 0 (if not protocol with certs) |
|
||||
| `[DNS_RCODE]` | Resolves into the DNS status of the response | NOERROR |
|
||||
|
||||
|
||||
#### Functions
|
||||
| Function | Description | Example |
|
||||
|:-----------|:---------------------------------------------------------------------------------------------------------------- |:-------------------------- |
|
||||
| `len` | Returns the length of the object/slice. Works only with the `[BODY]` placeholder. | `len([BODY].username) > 8`
|
||||
| `has` | Returns `true` or `false` based on whether a given path is valid. Works only with the `[BODY]` placeholder. | `has([BODY].errors) == false`
|
||||
| `pat` | Specifies that the string passed as parameter should be evaluated as a pattern. Works only with `==` and `!=`. | `[IP] == pat(192.168.*)`
|
||||
| `any` | Specifies that any one of the values passed as parameters is a valid value. Works only with `==` and `!=`. | `[BODY].ip == any(127.0.0.1, ::1)`
|
||||
|:---------|:---------------------------------------------------------------------------------------------------------------|:-----------------------------------|
|
||||
| `len` | Returns the length of the object/slice. Works only with the `[BODY]` placeholder. | `len([BODY].username) > 8` |
|
||||
| `has` | Returns `true` or `false` based on whether a given path is valid. Works only with the `[BODY]` placeholder. | `has([BODY].errors) == false` |
|
||||
| `pat` | Specifies that the string passed as parameter should be evaluated as a pattern. Works only with `==` and `!=`. | `[IP] == pat(192.168.*)` |
|
||||
| `any` | Specifies that any one of the values passed as parameters is a valid value. Works only with `==` and `!=`. | `[BODY].ip == any(127.0.0.1, ::1)` |
|
||||
|
||||
**NOTE**: Use `pat` only when you need to. `[STATUS] == pat(2*)` is a lot more expensive than `[STATUS] < 300`.
|
||||
|
||||
|
||||
### Storage
|
||||
| Parameter | Description | Default |
|
||||
|:------------------ |:-------------------------------------------------------------------------------------- |:-------------- |
|
||||
|:---------------|:-------------------------------------------------------------------------------|:-----------|
|
||||
| `storage` | Storage configuration | `{}` |
|
||||
| `storage.path` | Path to persist the data in. Only supported for types `sqlite` and `postgres`. | `""` |
|
||||
| `storage.type` | Type of storage. Valid types: `memory`, `sqlite`, `postgres`. | `"memory"` |
|
||||
|
|
@ -271,7 +270,7 @@ In order to support a wide range of environments, each monitored endpoint has a
|
|||
the client used to send the request.
|
||||
|
||||
| Parameter | Description | Default |
|
||||
|:-------------------------|:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:-------------------------|:------------------------------------------------------------------------|:--------|
|
||||
| `client.insecure` | Whether to skip verifying the server's certificate chain and host name. | `false` |
|
||||
| `client.ignore-redirect` | Whether to ignore redirects (true) or follow them (false, default). | `false` |
|
||||
| `client.timeout` | Duration before timing out. | `10s` |
|
||||
|
|
@ -310,7 +309,7 @@ Note that if an alerting provider is not properly configured, all alerts configu
|
|||
ignored.
|
||||
|
||||
| Parameter | Description | Default |
|
||||
|:-----------------------|:---------------------------------------------------------------------------------------------------------------------- |:-------|
|
||||
|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------|:--------|
|
||||
| `alerting.discord` | Configuration for alerts of type `discord`. <br />See [Configuring Discord alerts](#configuring-discord-alerts). | `{}` |
|
||||
| `alerting.email` | Configuration for alerts of type `email`. <br />See [Configuring Email alerts](#configuring-email-alerts). | `{}` |
|
||||
| `alerting.mattermost` | Configuration for alerts of type `mattermost`. <br />See [Configuring Mattermost alerts](#configuring-mattermost-alerts). | `{}` |
|
||||
|
|
@ -326,7 +325,7 @@ ignored.
|
|||
|
||||
#### Configuring Discord alerts
|
||||
| Parameter | Description | Default |
|
||||
|:---------------------------------------- |:-------------------------------------------- |:-------------- |
|
||||
|:---------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.discord` | Configuration for alerts of type `discord` | `{}` |
|
||||
| `alerting.discord.webhook-url` | Discord Webhook URL | Required `""` |
|
||||
| `alerting.discord.default-alert` | Default alert configuration. <br />See [Setting a default alert](#setting-a-default-alert) | N/A |
|
||||
|
|
@ -354,7 +353,7 @@ endpoints:
|
|||
|
||||
#### Configuring Email alerts
|
||||
| Parameter | Description | Default |
|
||||
|:---------------------------------- |:------------------------------------------------- |:-------------- |
|
||||
|:-------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.email` | Configuration for alerts of type `email` | `{}` |
|
||||
| `alerting.email.from` | Email used to send the alert | Required `""` |
|
||||
| `alerting.email.password` | Password of the email used to send the alert | Required `""` |
|
||||
|
|
@ -392,7 +391,7 @@ endpoints:
|
|||
|
||||
#### Configuring Mattermost alerts
|
||||
| Parameter | Description | Default |
|
||||
|:----------------------------------- |:------------------------------------------------------------------------------------------- |:-------------- |
|
||||
|:------------------------------------|:--------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.mattermost` | Configuration for alerts of type `mattermost` | `{}` |
|
||||
| `alerting.mattermost.webhook-url` | Mattermost Webhook URL | Required `""` |
|
||||
| `alerting.mattermost.client` | Client configuration. <br />See [Client configuration](#client-configuration). | `{}` |
|
||||
|
|
@ -427,7 +426,7 @@ Here's an example of what the notifications look like:
|
|||
|
||||
#### Configuring Messagebird alerts
|
||||
| Parameter | Description | Default |
|
||||
|:-------------------------------------|:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:-------------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.messagebird` | Settings for alerts of type `messagebird` | `{}` |
|
||||
| `alerting.messagebird.access-key` | Messagebird access key | Required `""` |
|
||||
| `alerting.messagebird.originator` | The sender of the message | Required `""` |
|
||||
|
|
@ -460,7 +459,7 @@ endpoints:
|
|||
|
||||
#### Configuring Opsgenie alerts
|
||||
| Parameter | Description | Default |
|
||||
|:------------------------------------------------------ |:----------------------------------------------------------------------------- |:-------------------- |
|
||||
|:----------------------------------|:--------------------------------------------|:---------------------|
|
||||
| `alerting.opsgenie` | Configuration for alerts of type `opsgenie` | `{}` |
|
||||
| `alerting.opsgenie.api-key` | Opsgenie API Key | Required `""` |
|
||||
| `alerting.opsgenie.priority` | Priority level of the alert. | `P1` |
|
||||
|
|
@ -479,7 +478,7 @@ alerting:
|
|||
|
||||
#### Configuring PagerDuty alerts
|
||||
| Parameter | Description | Default |
|
||||
|:------------------------------------------------------ |:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:-------------------------------------------------|:-------------------------------------------------------------------------------------------|:--------|
|
||||
| `alerting.pagerduty` | Configuration for alerts of type `pagerduty` | `{}` |
|
||||
| `alerting.pagerduty.integration-key` | PagerDuty Events API v2 integration key | `""` |
|
||||
| `alerting.pagerduty.default-alert` | Default alert configuration. <br />See [Setting a default alert](#setting-a-default-alert) | N/A |
|
||||
|
|
@ -542,7 +541,7 @@ endpoints:
|
|||
|
||||
#### Configuring Slack alerts
|
||||
| Parameter | Description | Default |
|
||||
|:-------------------------------- |:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:-------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.slack` | Configuration for alerts of type `slack` | `{}` |
|
||||
| `alerting.slack.webhook-url` | Slack Webhook URL | Required `""` |
|
||||
| `alerting.slack.default-alert` | Default alert configuration. <br />See [Setting a default alert](#setting-a-default-alert) | N/A |
|
||||
|
|
@ -579,7 +578,7 @@ Here's an example of what the notifications look like:
|
|||
|
||||
#### Configuring Teams alerts
|
||||
| Parameter | Description | Default |
|
||||
|:-------------------------------- |:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:-------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.teams` | Configuration for alerts of type `teams` | `{}` |
|
||||
| `alerting.teams.webhook-url` | Teams Webhook URL | Required `""` |
|
||||
| `alerting.teams.default-alert` | Default alert configuration. <br />See [Setting a default alert](#setting-a-default-alert) | N/A |
|
||||
|
|
@ -610,7 +609,7 @@ Here's an example of what the notifications look like:
|
|||
|
||||
#### Configuring Telegram alerts
|
||||
| Parameter | Description | Default |
|
||||
|:----------------------------------- |:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:----------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.telegram` | Configuration for alerts of type `telegram` | `{}` |
|
||||
| `alerting.telegram.token` | Telegram Bot Token | Required `""` |
|
||||
| `alerting.telegram.id` | Telegram User ID | Required `""` |
|
||||
|
|
@ -642,7 +641,7 @@ Here's an example of what the notifications look like:
|
|||
|
||||
#### Configuring Twilio alerts
|
||||
| Parameter | Description | Default |
|
||||
|:--------------------------------- |:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:--------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.twilio` | Settings for alerts of type `twilio` | `{}` |
|
||||
| `alerting.twilio.sid` | Twilio account SID | Required `""` |
|
||||
| `alerting.twilio.token` | Twilio auth token | Required `""` |
|
||||
|
|
@ -677,7 +676,7 @@ endpoints:
|
|||
|
||||
#### Configuring custom alerts
|
||||
| Parameter | Description | Default |
|
||||
|:----------------------------------|:----------------------------------------------------------------------------- |:-------------- |
|
||||
|:--------------------------------|:-------------------------------------------------------------------------------------------|:--------------|
|
||||
| `alerting.custom` | Configuration for custom actions on failure or alerts | `{}` |
|
||||
| `alerting.custom.url` | Custom alerting request url | Required `""` |
|
||||
| `alerting.custom.method` | Request method | `GET` |
|
||||
|
|
@ -837,7 +836,7 @@ If you have maintenance windows, you may not want to be annoyed by alerts.
|
|||
To do that, you'll have to use the maintenance configuration:
|
||||
|
||||
| Parameter | Description | Default |
|
||||
|:----------------------- |:----------------------------------------------------------------------------- |:--------------- |
|
||||
|:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------------|:--------------|
|
||||
| `maintenance.enabled` | Whether the maintenance period is enabled | `true` |
|
||||
| `maintenance.start` | Time at which the maintenance window starts in `hh:mm` format (e.g. `23:00`) | Required `""` |
|
||||
| `maintenance.duration` | Duration of the maintenance window (e.g. `1h`, `30m`) | Required `""` |
|
||||
|
|
@ -863,6 +862,53 @@ maintenance:
|
|||
```
|
||||
|
||||
|
||||
### Security
|
||||
| Parameter | Description | Default |
|
||||
|:---------------------------------|:-----------------------------|:--------------|
|
||||
| `security` | Security configuration | `{}` |
|
||||
| `security.basic` | HTTP Basic configuration | `{}` |
|
||||
| `security.oidc` | OpenID Connect configuration | `{}` |
|
||||
|
||||
#### Basic
|
||||
| Parameter | Description | Default |
|
||||
|:---------------------------------|:-----------------------------------------------------------|:--------------|
|
||||
| `security.basic` | HTTP Basic configuration | `{}` |
|
||||
| `security.basic.username` | Username for Basic authentication. | Required `""` |
|
||||
| `security.basic.password-sha512` | Password's SHA512 hash for Basic authentication. | Required `""` |
|
||||
|
||||
The example below will require that you authenticate with the username `john.doe` and the password `hunter2`:
|
||||
```yaml
|
||||
security:
|
||||
basic:
|
||||
username: "john.doe"
|
||||
password-sha512: "6b97ed68d14eb3f1aa959ce5d49c7dc612e1eb1dafd73b1e705847483fd6a6c809f2ceb4e8df6ff9984c6298ff0285cace6614bf8daa9f0070101b6c89899e22"
|
||||
```
|
||||
|
||||
#### OIDC (ALPHA)
|
||||
| Parameter | Description | Default |
|
||||
|:---------------------------------|:---------------------------------------------------------------|:--------------|
|
||||
| `security.oidc` | OpenID Connect configuration | `{}` |
|
||||
| `security.oidc.issuer-url` | Issuer URL | Required `""` |
|
||||
| `security.oidc.redirect-url` | Redirect URL. Must end with `/authorization-code/callback` | Required `""` |
|
||||
| `security.oidc.client-id` | Client id | Required `""` |
|
||||
| `security.oidc.client-secret` | Client secret | Required `""` |
|
||||
| `security.oidc.scopes` | Scopes to request. The only scope you need is `openid`. | Required `[]` |
|
||||
| `security.oidc.allowed-subjects` | List of subjects to allow. If empty, all subjects are allowed. | `[]` |
|
||||
|
||||
```yaml
|
||||
security:
|
||||
oidc:
|
||||
issuer-url: "https://example.okta.com"
|
||||
redirect-url: "https://status.example.com/authorization-code/callback"
|
||||
client-id: "123456789"
|
||||
client-secret: "abcdefghijk"
|
||||
scopes: ["openid"]
|
||||
# You may optionally specify a list of allowed subjects. If this is not specified, all subjects will be allowed.
|
||||
#allowed-subjects: ["johndoe@example.com"]
|
||||
```
|
||||
|
||||
**NOTE:** The OIDC feature is currently in Alpha. Breaking changes may occur. Use this feature at your own risk.
|
||||
|
||||
|
||||
## Deployment
|
||||
Many examples can be found in the [.examples](.examples) folder, but this section will focus on the most popular ways of deploying Gatus.
|
||||
|
|
@ -1080,18 +1126,6 @@ endpoints:
|
|||
```
|
||||
|
||||
|
||||
### Basic authentication
|
||||
You can require Basic authentication by leveraging the `security.basic` configuration:
|
||||
```yaml
|
||||
security:
|
||||
basic:
|
||||
username: "john.doe"
|
||||
password-sha512: "6b97ed68d14eb3f1aa959ce5d49c7dc612e1eb1dafd73b1e705847483fd6a6c809f2ceb4e8df6ff9984c6298ff0285cace6614bf8daa9f0070101b6c89899e22"
|
||||
```
|
||||
|
||||
The example above will require that you authenticate with the username `john.doe` as well as the password `hunter2`.
|
||||
|
||||
|
||||
### disable-monitoring-lock
|
||||
Setting `disable-monitoring-lock` to `true` means that multiple endpoints could be monitored at the same time.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue