From eb4a7387466d7c9011c4662766fc17014f320ce2 Mon Sep 17 00:00:00 2001 From: Jason Kulatunga Date: Mon, 9 May 2022 16:37:05 -0700 Subject: [PATCH] documentation & updates for configuring scrutiny behind a reverse proxy with path rewriting. --- README.md | 2 +- .../collector-metrics/collector-metrics.go | 3 +- .../collector-selftest/collector-selftest.go | 2 +- docs/TROUBLESHOOTING_REVERSE_PROXY.md | 58 +++++++++++++++++++ example.collector.yaml | 4 ++ 5 files changed, 66 insertions(+), 3 deletions(-) create mode 100644 docs/TROUBLESHOOTING_REVERSE_PROXY.md diff --git a/README.md b/README.md index 2bebda4..af4d1f3 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ docker run --rm \ --cap-add SYS_RAWIO \ --device=/dev/sda \ --device=/dev/sdb \ - -e SCRUTINY_API_ENDPOINT=http://SCRUTINY_WEB_IPADDRESS:8080 \ + -e COLLECTOR_API_ENDPOINT=http://SCRUTINY_WEB_IPADDRESS:8080 \ --name scrutiny-collector \ ghcr.io/analogj/scrutiny:master-collector ``` diff --git a/collector/cmd/collector-metrics/collector-metrics.go b/collector/cmd/collector-metrics/collector-metrics.go index 14782e0..a170f16 100644 --- a/collector/cmd/collector-metrics/collector-metrics.go +++ b/collector/cmd/collector-metrics/collector-metrics.go @@ -161,7 +161,8 @@ OPTIONS: &cli.StringFlag{ Name: "api-endpoint", Usage: "The api server endpoint", - EnvVars: []string{"SCRUTINY_API_ENDPOINT"}, + EnvVars: []string{"COLLECTOR_API_ENDPOINT", "SCRUTINY_API_ENDPOINT"}, + //SCRUTINY_API_ENDPOINT is deprecated, but kept for backwards compatibility }, &cli.StringFlag{ diff --git a/collector/cmd/collector-selftest/collector-selftest.go b/collector/cmd/collector-selftest/collector-selftest.go index a603b4a..ac2e2fa 100644 --- a/collector/cmd/collector-selftest/collector-selftest.go +++ b/collector/cmd/collector-selftest/collector-selftest.go @@ -114,7 +114,7 @@ OPTIONS: Name: "api-endpoint", Usage: "The api server endpoint", Value: "http://localhost:8080", - EnvVars: []string{"SCRUTINY_API_ENDPOINT"}, + EnvVars: []string{"COLLECTOR_API_ENDPOINT"}, }, &cli.StringFlag{ diff --git a/docs/TROUBLESHOOTING_REVERSE_PROXY.md b/docs/TROUBLESHOOTING_REVERSE_PROXY.md new file mode 100644 index 0000000..667f31e --- /dev/null +++ b/docs/TROUBLESHOOTING_REVERSE_PROXY.md @@ -0,0 +1,58 @@ +# Reverse Proxy Support + +Scrutiny is designed so that it can be used with a reverse proxy, leveraging `domain`, `port` or `path` based matching to correctly route to the Scrutiny service. + +For simple `domain` and/or `port` based routing, this is easy. + +If your domain:port pair is similar to `http://scrutiny.example.com` or `http://localhost:54321`, just update your reverse proxy configuration +to route traffic to the Scrutiny backend, which is listening on `0.0.0.0:8080` by default. + +```yaml +# default config +web: + listen: + port: 8080 + host: 0.0.0.0 +``` + +However if you're using `path` based routing to differentiate your reverse proxy protected services, things become more complicated. + +If you'd like to access Scrutiny using a path like: `http://example.com/scrutiny/`, then we need a way to configure Scrutiny so that it +understands `http://example.com/scrutiny/api/health` actually means `http://localhost:8080/api/health`. + +Thankfully this can be done by changing **two** settings. + +1. The webserver has a `web.listen.basepath` key +2. The collectors have a `api.endpoint` key. + +## Webserver Configuration + +When setting the `web.listen.basepath` key in the web config file, make sure the `basepath` key is prefixed with `/`. + +```yaml +# customized webserver config +web: + listen: + port: 8080 + host: 0.0.0.0 + # if you're using a reverse proxy like apache/nginx, you can override this value to serve scrutiny on a subpath. + # eg. http://example.com/custombasepath/* vs http://example.com:8080 + basepath: '/custombasepath' +``` + +## Collector Configuration + +Here's how you can update the collector `api.endpoint` key: + +```yaml +# customized collector config +api: + endpoint: 'http://localhost:8080/custombasepath' +``` + +# Environmental Variables. + +You may also configure these values using the following environmental variables + +- `COLLECTOR_API_ENDPOINT=http://localhost:8080/custombasepath` +- `SCRUTINY_WEB_LISTEN_BASEPATH=/custombasepath` \ No newline at end of file diff --git a/example.collector.yaml b/example.collector.yaml index 113aebf..008927d 100644 --- a/example.collector.yaml +++ b/example.collector.yaml @@ -60,6 +60,10 @@ devices: # #api: # endpoint: 'http://localhost:8080' +# endpoint: 'http://localhost:8080/custombasepath' +# if you need to use a custom base path (for a reverse proxy), you can add a suffix to the endpoint. +# See docs/TROUBLESHOOTING_REVERSE_PROXY.md for more info, + ######################################################################################################################## # FEATURES COMING SOON