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

ValueDefaultMeaning
token / existingSecretThe 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.
guidelyUrlhttps://guidelytech.comGuidely's address.
replicaCount1Two or more are fine: each query goes to one replica.
concurrency8Queries per replica at once.
healthPort80800 turns off the health server and the probes.
extraEnv, extraVolumes, extraVolumeMountsFor 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.enabledfalseA NetworkPolicy that blocks ingress except the health port, with optional egress rules.
resources50m 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.