Enhance API, REST, ping documentation.

This commit is contained in:
Ludovic Fernandez 2018-03-01 08:42:03 +01:00 committed by Traefiker Bot
parent 49a9e2a9e0
commit f149b56063
5 changed files with 210 additions and 135 deletions

View file

@ -43,7 +43,7 @@ For more customization, see [entry points](/configuration/entrypoints/) document
| Path | Method | Description | | Path | Method | Description |
|-----------------------------------------------------------------|------------------|-------------------------------------------| |-----------------------------------------------------------------|------------------|-------------------------------------------|
| `/` | `GET` | Provides a simple HTML frontend of Træfik | | `/` | `GET` | Provides a simple HTML frontend of Træfik |
| `/health` | `GET` | json health metrics | | `/health` | `GET` | JSON health metrics |
| `/api` | `GET` | Configuration for all providers | | `/api` | `GET` | Configuration for all providers |
| `/api/providers` | `GET` | Providers | | `/api/providers` | `GET` | Providers |
| `/api/providers/{provider}` | `GET`, `PUT` | Get or update provider (1) | | `/api/providers/{provider}` | `GET`, `PUT` | Get or update provider (1) |
@ -62,7 +62,102 @@ For more customization, see [entry points](/configuration/entrypoints/) document
For compatibility reason, when you activate the rest provider, you can use `web` or `rest` as `provider` value. For compatibility reason, when you activate the rest provider, you can use `web` or `rest` as `provider` value.
But be careful, in the configuration for all providers the key is still `web`. But be careful, in the configuration for all providers the key is still `web`.
### Provider configurations ### Address / Port
You can define a custom address/port like this:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.foo]
address = ":8082"
[entryPoints.bar]
address = ":8083"
[ping]
entryPoint = "foo"
[api]
entryPoint = "bar"
```
In the above example, you would access a regular path, administration panel, and health-check as follows:
* Regular path: `http://hostname:80/path`
* Admin Panel: `http://hostname:8083/`
* Ping URL: `http://hostname:8082/ping`
In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`.
Otherwise, you are likely to expose _all_ services via that entry point.
### Custom Path
You can define a custom path like this:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.foo]
address = ":8080"
[entryPoints.bar]
address = ":8081"
# Activate API and Dashboard
[api]
entryPoint = "bar"
dashboard = true
[file]
[backends]
[backends.backend1]
[backends.backend1.servers.server1]
url = "http://127.0.0.1:8081"
[frontends]
[frontends.frontend1]
entryPoints = ["foo"]
backend = "backend1"
[frontends.frontend1.routes.test_1]
rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix"
```
### Authentication
You can define the authentication like this:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.foo]
address=":8080"
[entryPoints.foo.auth]
[entryPoints.foo.auth.basic]
users = [
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
]
[api]
entrypoint="foo"
```
For more information, see [entry points](/configuration/entrypoints/) .
### Provider call example
```shell ```shell
curl -s "http://localhost:8080/api" | jq . curl -s "http://localhost:8080/api" | jq .

View file

@ -29,9 +29,10 @@ Træfik can be configured:
```shell ```shell
curl -XPUT @file "http://localhost:8080/api" curl -XPUT @file "http://localhost:8080/api/providers/rest"
``` ```
with `@file`
with `@file`:
```json ```json
{ {
"frontends": { "frontends": {

View file

@ -386,41 +386,6 @@ curl -s "http://localhost:8080/api" | jq .
### Deprecation compatibility ### Deprecation compatibility
#### Path
As the web provider is deprecated, you can handle the `Path` option like this:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.dashboard]
address = ":8080"
[entryPoints.api]
address = ":8081"
# Activate API and Dashboard
[api]
entryPoint = "api"
[file]
[backends]
[backends.backend1]
[backends.backend1.servers.server1]
url = "http://127.0.0.1:8081"
[frontends]
[frontends.frontend1]
entryPoints = ["dashboard"]
backend = "backend1"
[frontends.frontend1.routes.test_1]
rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix"
```
#### Address #### Address
As the web provider is deprecated, you can handle the `Address` option like this: As the web provider is deprecated, you can handle the `Address` option like this:
@ -432,28 +397,64 @@ defaultEntryPoints = ["http"]
[entryPoints.http] [entryPoints.http]
address = ":80" address = ":80"
[entryPoints.ping] [entryPoints.foo]
address = ":8082" address = ":8082"
[entryPoints.api] [entryPoints.bar]
address = ":8083" address = ":8083"
[ping] [ping]
entryPoint = "ping" entryPoint = "foo"
[api] [api]
entryPoint = "api" entryPoint = "bar"
``` ```
In the above example, you would access a regular path, administration panel, and health-check as follows: In the above example, you would access a regular path, administration panel, and health-check as follows:
* Regular path: `http://hostname:80/foo` * Regular path: `http://hostname:80/path`
* Admin Panel: `http://hostname:8083/` * Admin Panel: `http://hostname:8083/`
* Ping URL: `http://hostname:8082/ping` * Ping URL: `http://hostname:8082/ping`
In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`. In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`.
Otherwise, you are likely to expose _all_ services via that entry point. Otherwise, you are likely to expose _all_ services via that entry point.
#### Path
As the web provider is deprecated, you can handle the `Path` option like this:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.foo]
address = ":8080"
[entryPoints.bar]
address = ":8081"
# Activate API and Dashboard
[api]
entryPoint = "bar"
dashboard = true
[file]
[backends]
[backends.backend1]
[backends.backend1.servers.server1]
url = "http://127.0.0.1:8081"
[frontends]
[frontends.frontend1]
entryPoints = ["foo"]
backend = "backend1"
[frontends.frontend1.routes.test_1]
rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix"
```
#### Authentication #### Authentication
As the web provider is deprecated, you can handle the `auth` option like this: As the web provider is deprecated, you can handle the `auth` option like this:
@ -465,17 +466,17 @@ defaultEntryPoints = ["http"]
[entryPoints.http] [entryPoints.http]
address = ":80" address = ":80"
[entryPoints.api] [entryPoints.foo]
address=":8080" address=":8080"
[entryPoints.api.auth] [entryPoints.foo.auth]
[entryPoints.api.auth.basic] [entryPoints.foo.auth.basic]
users = [ users = [
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0", "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
] ]
[api] [api]
entrypoint="api" entrypoint="foo"
``` ```
For more information, see [entry points](/configuration/entrypoints/) . For more information, see [entry points](/configuration/entrypoints/) .

View file

@ -21,24 +21,67 @@
!!! warning !!! warning
Even if you have authentication configured on entry point, the `/ping` path of the api is excluded from authentication. Even if you have authentication configured on entry point, the `/ping` path of the api is excluded from authentication.
## Example ## Examples
The `/ping` health-check URL is enabled with the command-line `--ping` or config file option `[ping]`.
Thus, if you have a regular path for `/foo` and an entrypoint on `:80`, you would access them as follows:
* Regular path: `http://hostname:80/foo`
* Admin panel: `http://hostname:8080/`
* Ping URL: `http://hostname:8080/ping`
However, for security reasons, you may want to be able to expose the `/ping` health-check URL to outside health-checkers, e.g. an Internet service or cloud load-balancer, _without_ exposing your administration panel's port.
In many environments, the security staff may not _allow_ you to expose it.
You have two options:
* Enable `/ping` on a regular entry point
* Enable `/ping` on a dedicated port
### Ping health check on a regular entry point
To proxy `/ping` from a regular entry point to the administration one without exposing the panel, do the following:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[ping]
entryPoint = "http"
```shell
curl -sv "http://localhost:8080/ping"
``` ```
```shell
* Trying ::1... The above link `ping` on the `http` entry point and then expose it on port `80`
* Connected to localhost (::1) port 8080 (#0)
> GET /ping HTTP/1.1 ### Enable ping health check on dedicated port
> Host: localhost:8080
> User-Agent: curl/7.43.0 If you do not want to or cannot expose the health-check on a regular entry point - e.g. your security rules do not allow it, or you have a conflicting path - then you can enable health-check on its own entry point.
> Accept: */* Use the following configuration:
>
< HTTP/1.1 200 OK ```toml
< Date: Thu, 25 Aug 2016 01:35:36 GMT defaultEntryPoints = ["http"]
< Content-Length: 2
< Content-Type: text/plain; charset=utf-8 [entryPoints]
< [entryPoints.http]
* Connection #0 to host localhost left intact address = ":80"
OK [entryPoints.ping]
address = ":8082"
[ping]
entryPoint = "ping"
``` ```
The above is similar to the previous example, but instead of enabling `/ping` on the _default_ entry point, we enable it on a _dedicated_ entry point.
In the above example, you would access a regular path and health-check as follows:
* Regular path: `http://hostname:80/foo`
* Ping URL: `http://hostname:8082/ping`
Note the dedicated port `:8082` for `/ping`.
In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`.
Otherwise, you are likely to expose _all_ services via this entry point.

View file

@ -335,68 +335,3 @@ providersThrottleDuration = "5s"
[respondingTimeouts] [respondingTimeouts]
idleTimeout = "360s" idleTimeout = "360s"
``` ```
## Ping Health Check
The `/ping` health-check URL is enabled with the command-line `--ping` or config file option `[ping]`.
Thus, if you have a regular path for `/foo` and an entrypoint on `:80`, you would access them as follows:
* Regular path: `http://hostname:80/foo`
* Admin panel: `http://hostname:8080/`
* Ping URL: `http://hostname:8080/ping`
However, for security reasons, you may want to be able to expose the `/ping` health-check URL to outside health-checkers, e.g. an Internet service or cloud load-balancer, _without_ exposing your administration panel's port.
In many environments, the security staff may not _allow_ you to expose it.
You have two options:
* Enable `/ping` on a regular entry point
* Enable `/ping` on a dedicated port
### Enable ping health check on a regular entry point
To proxy `/ping` from a regular entry point to the administration one without exposing the panel, do the following:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[ping]
entryPoint = "http"
```
The above link `ping` on the `http` entry point and then expose it on port `80`
### Enable ping health check on dedicated port
If you do not want to or cannot expose the health-check on a regular entry point - e.g. your security rules do not allow it, or you have a conflicting path - then you can enable health-check on its own entry point.
Use the following configuration:
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.ping]
address = ":8082"
[ping]
entryPoint = "ping"
```
The above is similar to the previous example, but instead of enabling `/ping` on the _default_ entry point, we enable it on a _dedicated_ entry point.
In the above example, you would access a regular path and health-check as follows:
* Regular path: `http://hostname:80/foo`
* Ping URL: `http://hostname:8082/ping`
Note the dedicated port `:8082` for `/ping`.
In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`.
Otherwise, you are likely to expose _all_ services via this entry point.