Docs: Add a disclaimer for users who set up health-checks and prometh…

…eus endpoints in a containers environment. (#2194) fixes #2079 The health check and the prometheus endpoint listen to 127.0.0.1 by default. While this is a safe default, it prevents other pods from performing healthchecks and scrapping prometheus data. This behavior and customization is now documented. Co-authored-by: Gary Pennington <[email protected]>
apollographql · Dec 2, 2022 · fda9f15 · fda9f15
1 parent 4360256
commit fda9f15
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 1 deletion.
diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
@@ -291,7 +291,7 @@ By [@goto-bus-stop](https://github.com/goto-bus-stop) in https://github.com/apol
 
 The docs CORS regex example now displays a working and safe way to allow `HTTPS` subdomains of `api.example.com`.
 
-By [@col](https://github.com/o0Ignition0o) in https://github.com/apollographql/router/pull/2152
+By [@o0Ignition0o](https://github.com/o0Ignition0o) in https://github.com/apollographql/router/pull/2152
 
 
 ### update documentation to reflect new examples structure ([Issue #2095](https://github.com/apollographql/router/issues/2095))
@@ -300,3 +300,11 @@ We recently updated the examples directory structure. This fixes the documentati
 
 By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/2133
 
+
+### Docs: Add a disclaimer for users who set up health-checks and prometheus endpoints in a containers environment ([Issue #2079](https://github.com/apollographql/router/issues/2079))
+
+The health check and the prometheus endpoint listen to 127.0.0.1 by default.
+While this is a safe default, it prevents other pods from performing healthchecks and scraping prometheus data.
+This behavior and customization is now documented in the [health-checks](https://www.apollographql.com/docs/router/configuration/health-checks) and the [prometheus](https://www.apollographql.com/docs/router/configuration/metrics#using-prometheus) sections.
+
+By [@o0Ignition0o](https://github.com/o0Ignition0o) in https://github.com/apollographql/router/pull/2194
diff --git a/docs/source/configuration/health-checks.mdx b/docs/source/configuration/health-checks.mdx
@@ -37,6 +37,18 @@ $ curl -v "http://127.0.0.1:8088/health"
 {"status":"UP"}
 ```
 
+## Using in a containers environment
+
+The health-check listens to 127.0.0.1 by default, which won't allow connections issued from a network.
+While this is a safe default, *other containers won't be able to perform healthchecks*, which will prevent the router pod from switching to a healthy state.
+
+You can change this by setting `health-check`:
+```yaml title="router.yaml"
+health-check:
+  listen: 0.0.0.0:8088
+  enabled: true
+```
+
 ## Using with Kubernetes
 In Kubernetes, you can configure health checks by setting `readinessProbe` and `livenessProbe` on the `containers` object of the resource definition:
 ```yaml

diff --git a/docs/source/configuration/metrics.mdx b/docs/source/configuration/metrics.mdx
@@ -24,6 +24,23 @@ telemetry:
       path: /metrics
 ```
 
+## Using in a containers environment
+
+The prometheus endpoint listens to 127.0.0.1 by default, which won't allow connections issued from a network.
+While this is a safe default, *other containers won't be able to access the prometheus endpoint*, which will disable metric scraping.
+
+You can change this by setting:
+```yaml title="router.yaml"
+telemetry:
+  metrics:
+    prometheus:
+      # By setting this endpoint you enable other containers and pods to access the prometheus endpoint
+      enabled: true
+      listen: 0.0.0.0:9090
+      path: /metrics
+```
+
+
 Assuming you're running locally:
 
 1. Run a query against the router.