From f149b56063443620cc1846092bc70ca0eddec720 Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Thu, 1 Mar 2018 08:42:03 +0100 Subject: [PATCH] Enhance API, REST, ping documentation. --- docs/configuration/api.md | 103 ++++++++++++++++++++++++++-- docs/configuration/backends/rest.md | 7 +- docs/configuration/backends/web.md | 89 ++++++++++++------------ docs/configuration/ping.md | 81 +++++++++++++++++----- docs/user-guide/examples.md | 65 ------------------ 5 files changed, 210 insertions(+), 135 deletions(-) diff --git a/docs/configuration/api.md b/docs/configuration/api.md index 298812f3b..cdcddf939 100644 --- a/docs/configuration/api.md +++ b/docs/configuration/api.md @@ -11,14 +11,14 @@ # Default: "traefik" # entryPoint = "traefik" - + # Enabled Dashboard # # Optional # Default: true # dashboard = true - + # Enable debug mode. # This will install HTTP handlers to expose Go expvars under /debug/vars and # pprof profiling data under /debug/pprof. @@ -43,7 +43,7 @@ For more customization, see [entry points](/configuration/entrypoints/) document | Path | Method | Description | |-----------------------------------------------------------------|------------------|-------------------------------------------| | `/` | `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/providers` | `GET` | Providers | | `/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. 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 curl -s "http://localhost:8080/api" | jq . diff --git a/docs/configuration/backends/rest.md b/docs/configuration/backends/rest.md index 8c1dbe0e3..b8821d45e 100644 --- a/docs/configuration/backends/rest.md +++ b/docs/configuration/backends/rest.md @@ -29,9 +29,10 @@ Træfik can be configured: ```shell -curl -XPUT @file "http://localhost:8080/api" +curl -XPUT @file "http://localhost:8080/api/providers/rest" ``` -with `@file` + +with `@file`: ```json { "frontends": { @@ -88,4 +89,4 @@ with `@file` } } } -``` \ No newline at end of file +``` diff --git a/docs/configuration/backends/web.md b/docs/configuration/backends/web.md index 6e3b2852c..cb27d9e04 100644 --- a/docs/configuration/backends/web.md +++ b/docs/configuration/backends/web.md @@ -386,41 +386,6 @@ curl -s "http://localhost:8080/api" | jq . ### 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 As the web provider is deprecated, you can handle the `Address` option like this: @@ -432,28 +397,64 @@ defaultEntryPoints = ["http"] [entryPoints.http] address = ":80" - [entryPoints.ping] + [entryPoints.foo] address = ":8082" - [entryPoints.api] + [entryPoints.bar] address = ":8083" [ping] -entryPoint = "ping" +entryPoint = "foo" [api] -entryPoint = "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/foo` +* 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. +#### 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 As the web provider is deprecated, you can handle the `auth` option like this: @@ -465,17 +466,17 @@ defaultEntryPoints = ["http"] [entryPoints.http] address = ":80" - [entryPoints.api] + [entryPoints.foo] address=":8080" - [entryPoints.api.auth] - [entryPoints.api.auth.basic] + [entryPoints.foo.auth] + [entryPoints.foo.auth.basic] users = [ "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0", ] [api] -entrypoint="api" +entrypoint="foo" ``` For more information, see [entry points](/configuration/entrypoints/) . diff --git a/docs/configuration/ping.md b/docs/configuration/ping.md index de1d805e5..98d50a71f 100644 --- a/docs/configuration/ping.md +++ b/docs/configuration/ping.md @@ -21,24 +21,67 @@ !!! warning 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... -* Connected to localhost (::1) port 8080 (#0) -> GET /ping HTTP/1.1 -> Host: localhost:8080 -> User-Agent: curl/7.43.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< Date: Thu, 25 Aug 2016 01:35:36 GMT -< Content-Length: 2 -< Content-Type: text/plain; charset=utf-8 -< -* Connection #0 to host localhost left intact -OK -``` \ No newline at end of file + +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. diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md index c7f6f4c86..f38bbb2d1 100644 --- a/docs/user-guide/examples.md +++ b/docs/user-guide/examples.md @@ -335,68 +335,3 @@ providersThrottleDuration = "5s" [respondingTimeouts] 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.