Run the relay on Kubernetes
The Helm chart in deploy/relay/helm/guidely-relay runs the relay as a Deployment. It works on EKS, GKE, AKS and any other cluster, and is usually the simplest option when Prometheus, Loki, Tempo or Grafana already run in the cluster: the relay reaches them by their service names.
What it creates:
- A Deployment (one replica by default) with liveness and readiness probes on
/healthz. - A Secret with the relay token and any upstream credentials, or none if you bring your own (
existingSecret). - A ServiceAccount with no API token mounted: the relay never calls the Kubernetes API.
- No Service and no Ingress: nothing connects to the relay.
The pod runs as a non-root user with a read-only root filesystem, no privilege escalation, all capabilities dropped and the runtime's default seccomp profile, so it's accepted by the restricted Pod Security Standard.
Install
Clone the repository (or copy the chart folder), then:
helm install guidely-relay ./deploy/relay/helm/guidely-relay \
--namespace observability --create-namespace \
--set token=gly_rly_... \
--set 'targets[0].name=prom,targets[0].kind=prometheus,targets[0].url=http://prometheus-server.monitoring.svc:80' \
--set 'targets[1].name=logs,targets[1].kind=loki,targets[1].url=http://loki-gateway.monitoring.svc:80'
Or with a values file:
token: gly_rly_... # or existingSecret, below
targets:
- name: prom
kind: prometheus
url: http://prometheus-server.monitoring.svc:80
- name: logs
kind: loki
url: http://loki-gateway.monitoring.svc:80
- name: traces
kind: tempo
url: http://tempo.monitoring.svc:3200
- name: grafana
kind: grafana
url: http://grafana.monitoring.svc:80
targetCredentials:
TARGET_GRAFANA_BEARER: glsa_...
TARGET_LOGS_ORG_ID: tenant-1
Secrets from your secret manager
To keep the token out of Helm values, create a Secret yourself (with External Secrets, Sealed Secrets, the Secrets Store CSI driver's sync, or kubectl) and point the chart at it. Every key becomes an environment variable:
kubectl -n observability create secret generic guidely-relay \
--from-literal=GUIDELY_RELAY_TOKEN=gly_rly_... \
--from-literal=TARGET_GRAFANA_BEARER=glsa_...
helm install guidely-relay ./deploy/relay/helm/guidely-relay -n observability \
--set existingSecret=guidely-relay -f my-targets.yaml
Check it
kubectl -n observability exec deploy/guidely-relay -- node /app/dist/cli.js check
kubectl -n observability logs deploy/guidely-relay -f
Then look in Integrations → Grafana, Prometheus, Tempo, Loki: the relay shows as connected, with its targets.
Options
| Value | Default | Meaning |
|---|---|---|
token / existingSecret | The relay token, or a Secret holding GUIDELY_RELAY_TOKEN (and TARGET_* keys). | |
targets | [] | name, kind, url for each target. |
targetCredentials | {} | TARGET_<NAME>_… values added to the chart's Secret. |
guidelyUrl | https://guidelytech.com | Guidely's address. |
replicaCount | 1 | Two or more are fine: each query goes to one replica. |
concurrency | 8 | Queries per replica at once. |
healthPort | 8080 | 0 turns off the health server and the probes. |
extraEnv, extraVolumes, extraVolumeMounts | For a CA bundle: mount it and set TARGET_<NAME>_CA_FILE. | |
serviceAccount.annotations | {} | IRSA or Workload Identity annotations, if your policies require one (the relay needs no cloud permissions). |
networkPolicy.enabled | false | A NetworkPolicy that blocks ingress except the health port, with optional egress rules. |
resources | 50m CPU, 64Mi; 256Mi limit |
EKS and GKE need nothing special: the pod needs outbound HTTPS to Guidely (through a NAT gateway or Cloud NAT for private nodes) and access to the targets. On GKE Autopilot, resource requests are raised to its minimums automatically.