From 3402c79b281b6b57010ce3f024b2aff5a9379e67 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 6 May 2026 13:48:22 +0000 Subject: [PATCH] docs(loki/tempo): clarify out-of-cluster setup The Loki and Tempo configuration docs previously assumed Holmes was running inside the Kubernetes cluster: example api_urls used *.svc.cluster.local DNS, and the "find your datasource UID" snippets unconditionally suggested `kubectl port-forward`. This made it hard for users running the Holmes CLI on a laptop (or Holmes outside the cluster) to figure out what URL to put in their config. Add explicit out-of-cluster examples (ingress hostname, external IP, port-forward) alongside the in-cluster ones, and note that the port-forward step is only needed when Grafana isn't already reachable from where the command is being run. Signed-off-by: Claude --- .../builtin-toolsets/grafanaloki.md | 21 +++++++++++++++---- .../builtin-toolsets/grafanatempo.md | 17 +++++++++------ 2 files changed, 28 insertions(+), 10 deletions(-) diff --git a/docs/data-sources/builtin-toolsets/grafanaloki.md b/docs/data-sources/builtin-toolsets/grafanaloki.md index b133fa1228..5feeab2f1e 100644 --- a/docs/data-sources/builtin-toolsets/grafanaloki.md +++ b/docs/data-sources/builtin-toolsets/grafanaloki.md @@ -37,33 +37,46 @@ HolmesGPT queries your self-hosted Loki through your Grafana instance's datasour **Find your Loki datasource UID:** ```bash -# Port forward to Grafana +# If Grafana isn't already reachable from where you're running this, port-forward first: kubectl port-forward svc/grafana 3000:80 -# Get Loki datasource UID +# Otherwise, replace http://localhost:3000 with the URL Holmes will use to reach Grafana +# (e.g. https://grafana.example.com for an ingress, or the in-cluster service URL). curl -s -u admin:admin http://localhost:3000/api/datasources | jq '.[] | select(.type == "loki") | .uid' ``` +Pick the `api_url` that matches where Holmes is running: + ```yaml-toolset-config toolsets: grafana/loki: enabled: true config: - api_url: http://grafana.monitoring.svc.cluster.local # Your Grafana URL + # In-cluster (Holmes running in Kubernetes): + api_url: http://grafana.monitoring.svc.cluster.local + # Out-of-cluster (Holmes CLI on a laptop, or Holmes running outside the cluster): + # api_url: https://grafana.example.com # ingress / external hostname + # api_url: http:// # external LoadBalancer + # api_url: http://localhost:3000 # via `kubectl port-forward` api_key: grafana_datasource_uid: ``` ### Self-Hosted Loki - Direct Connection -HolmesGPT connects directly to a self-hosted Loki API endpoint without going through Grafana. +HolmesGPT connects directly to a self-hosted Loki API endpoint without going through Grafana. Pick the `api_url` that matches where Holmes is running: ```yaml-toolset-config toolsets: grafana/loki: enabled: true config: + # In-cluster (Holmes running in Kubernetes): api_url: http://loki.monitoring.svc.cluster.local:3100 + # Out-of-cluster (Holmes CLI on a laptop, or Holmes running outside the cluster): + # api_url: https://loki.example.com # ingress / external hostname + # api_url: http://:3100 # external LoadBalancer + # api_url: http://localhost:3100 # via `kubectl port-forward svc/loki 3100:3100` additional_headers: X-Scope-OrgID: "" # Only needed for multi-tenant Loki ``` diff --git a/docs/data-sources/builtin-toolsets/grafanatempo.md b/docs/data-sources/builtin-toolsets/grafanatempo.md index 36b408c16b..f9e9a095c6 100644 --- a/docs/data-sources/builtin-toolsets/grafanatempo.md +++ b/docs/data-sources/builtin-toolsets/grafanatempo.md @@ -39,23 +39,26 @@ See this [video](https://www.loom.com/share/f969ab3af509444693802254ab040791?sid **Find your Tempo datasource UID:** ```bash -# Port forward to Grafana +# If Grafana isn't already reachable from where you're running this, port-forward first: kubectl port-forward svc/robusta-grafana 3000:80 -# Get Tempo datasource UID +# Otherwise, replace http://localhost:3000 with the URL Holmes will use to reach Grafana +# (e.g. https://grafana.example.com for an ingress, or the in-cluster service URL). curl -s -u : http://localhost:3000/api/datasources | jq '.[] | select(.type == "tempo") | .uid' ``` === "Holmes CLI" - Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist: + Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist. Use a `api_url` that's reachable from the machine running `holmes` (a laptop running the CLI typically can't resolve `*.svc.cluster.local`): ```yaml toolsets: grafana/tempo: enabled: true config: - api_url: # e.g. http://grafana.monitoring.svc.cluster.local + # Out-of-cluster (CLI on a laptop): use an ingress, external hostname, or `kubectl port-forward` + api_url: https://grafana.example.com + # api_url: http://localhost:3000 # via `kubectl port-forward svc/grafana 3000:80` api_key: grafana_datasource_uid: ``` @@ -138,14 +141,16 @@ HolmesGPT connects directly to a self-hosted Tempo API endpoint without going th === "Holmes CLI" - Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist: + Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist. Use a `api_url` that's reachable from the machine running `holmes` (a laptop running the CLI typically can't resolve `*.svc.cluster.local`): ```yaml toolsets: grafana/tempo: enabled: true config: - api_url: http://tempo.monitoring.svc.cluster.local:3200 + # Out-of-cluster (CLI on a laptop): use an ingress, external hostname, or `kubectl port-forward` + api_url: https://tempo.example.com + # api_url: http://localhost:3200 # via `kubectl port-forward svc/tempo 3200:3200` additional_headers: X-Scope-OrgID: "" # Only needed for multi-tenant Tempo ```