From 173fad838d0380d784956232f6bf84e9b02101e1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 7 May 2026 11:34:52 +0000 Subject: [PATCH] Clarify env vars for ACCOUNT_ID, SIGNING_KEY, and UI token Users frequently get confused about which Robusta credentials belong on the runner vs HolmesGPT, where to set them, and which env vars each component reads. The existing docs only showed plain-text values in the GitOps examples and a partial Holmes-only secret example, so users had to read source code to figure out the rest. - Expand configuration-secrets.rst with a complete walkthrough that loads account_id, signing_key, and the UI/sink token from a single Kubernetes Secret, covering both the runner and Holmes pods plus the globalConfig and sinksConfig wiring. Add a non-default-region (EU) block alongside it. - Add env-vars.rst as a reference for the user-facing env vars on the runner and Holmes, with a table mapping each credential to the component(s) that need it. - Strengthen the GitOps (Flux/ArgoCD) admonitions so users see a direct pointer to the secrets walkthrough instead of just a generic link. https://claude.ai/code/session_01YC1JKRVtkdzUJvLHRcGank --- docs/setup-robusta/configuration-secrets.rst | 129 +++++++++++- docs/setup-robusta/env-vars.rst | 208 +++++++++++++++++++ docs/setup-robusta/gitops/argocd.rst | 11 +- docs/setup-robusta/gitops/flux.rst | 11 +- docs/setup-robusta/index.rst | 1 + 5 files changed, 351 insertions(+), 9 deletions(-) create mode 100644 docs/setup-robusta/env-vars.rst diff --git a/docs/setup-robusta/configuration-secrets.rst b/docs/setup-robusta/configuration-secrets.rst index 1985f89c8..937d34d38 100644 --- a/docs/setup-robusta/configuration-secrets.rst +++ b/docs/setup-robusta/configuration-secrets.rst @@ -64,12 +64,135 @@ You can now reference the environment variable elsewhere in your configuration u This setup keeps sensitive values out of your Helm files and version control, while still allowing them to be dynamically injected at runtime. +.. _Loading Robusta credentials from secrets: + +Loading ``account_id``, ``signing_key``, and the UI token from secrets +------------------------------------------------------------------------------ + +After signing up, the Robusta install wizard generates a ``generated_values.yaml`` file with three +sensitive credentials that are normally written in plain text: + +* ``globalConfig.account_id`` — your Robusta account ID +* ``globalConfig.signing_key`` — used to verify signatures on data sent to the runner +* ``sinksConfig[].robusta_sink.token`` — the token the Robusta UI sink uses to send findings to the backend; HolmesGPT also uses this token to talk to the backend + +To load these from a Kubernetes Secret (or an external secret manager that injects values as env vars, +e.g. SealedSecrets, External Secrets, Vault, Azure Key Vault), use the steps below. + +.. admonition:: Where each value is needed + :class: note + + * ``account_id`` and ``signing_key`` are read by the **runner** (via ``globalConfig``). + * The UI / sink token is read by the **runner** (via ``sinksConfig`` for the ``robusta_sink``) **and** by **HolmesGPT** (to authenticate to the Robusta backend). The same value must therefore be available as an env var on both pods. + +**1. Create a Kubernetes Secret with all three values** + +.. code-block:: bash + + kubectl create secret generic my-robusta-secrets \ + --from-literal=account-id=YOUR_ACCOUNT_ID \ + --from-literal=signing-key=YOUR_SIGNING_KEY \ + --from-literal=ui-token=YOUR_UI_TOKEN + +**2. Reference the secret on both the runner and Holmes** + +The token needs to be exposed as an env var on **both** the runner pod and the Holmes pod. The +``account_id`` and ``signing_key`` only need to be exposed on the runner. + +.. code-block:: yaml + + runner: + additional_env_vars: + - name: ACCOUNT_ID + valueFrom: + secretKeyRef: + name: my-robusta-secrets + key: account-id + - name: SIGNING_KEY + valueFrom: + secretKeyRef: + name: my-robusta-secrets + key: signing-key + - name: ROBUSTA_UI_TOKEN + valueFrom: + secretKeyRef: + name: my-robusta-secrets + key: ui-token + + # Only required if HolmesGPT is enabled (enableHolmesGPT: true) + holmes: + additionalEnvVars: + - name: ROBUSTA_UI_TOKEN + valueFrom: + secretKeyRef: + name: my-robusta-secrets + key: ui-token + +**3. Reference the env vars from globalConfig and sinksConfig** + +.. code-block:: yaml + + globalConfig: + account_id: "{{ env.ACCOUNT_ID }}" + signing_key: "{{ env.SIGNING_KEY }}" + + sinksConfig: + - robusta_sink: + name: robusta_ui_sink + token: "{{ env.ROBUSTA_UI_TOKEN }}" + +After applying these values, the runner and Holmes both pick up the credentials from the secret +without storing them in plain text anywhere in your Helm values or Git repository. + +.. admonition:: Using an external secret manager + :class: note + + Any system that injects secrets as environment variables on the pod will work the same way — + just use that system's mechanism in place of ``secretKeyRef``. For example, with Azure Key Vault + you might write ``value: ui-token@azurekeyvault`` in ``additional_env_vars`` / ``additionalEnvVars``, + and the rest of the config (``globalConfig``, ``sinksConfig``) stays identical. + +.. admonition:: Non-default API regions (e.g. EU) + :class: tip + + If your account is hosted in a non-default region, you also need to point the runner and Holmes at + the correct endpoints. Add these to ``runner.additional_env_vars`` and ``holmes.additionalEnvVars``: + + .. code-block:: yaml + + runner: + additional_env_vars: + - name: ROBUSTA_API_ENDPOINT + value: https://api.eu.robusta.dev + - name: ROBUSTA_UI_DOMAIN + value: https://platform.eu.robusta.dev + - name: ROBUSTA_TELEMETRY_ENDPOINT + value: https://api.eu.robusta.dev/telemetry + - name: RELAY_EXTERNAL_ACTIONS_URL + value: https://api.eu.robusta.dev/integrations/generic/actions + - name: WEBSOCKET_RELAY_ADDRESS + value: wss://relay.eu.robusta.dev + + holmes: + additionalEnvVars: + - name: ROBUSTA_AI + value: "true" + - name: ROBUSTA_API_ENDPOINT + value: https://api.eu.robusta.dev + - name: ROBUSTA_UI_DOMAIN + value: https://platform.eu.robusta.dev + + See :ref:`Robusta env var reference` for the full list. + .. _Reading the Robusta UI Token from a secret in HolmesGPT: -Using an Existing Secret for the Robusta UI Token --------------------------------------------------------- +Using an Existing Secret for the Robusta UI Token (HolmesGPT only) +--------------------------------------------------------------------------- -If you store the Robusta UI token in a Kubernetes secret (instead of directly in Helm values), you need to pass it to HolmesGPT: +If you only need to inject the UI token into HolmesGPT (for example, the runner already has it via a +different mechanism), use the snippet below. For the full setup that also covers ``account_id``, +``signing_key``, and the sink token on the runner, see +:ref:`Loading Robusta credentials from secrets` above. .. code-block:: yaml diff --git a/docs/setup-robusta/env-vars.rst b/docs/setup-robusta/env-vars.rst new file mode 100644 index 000000000..a75f4be40 --- /dev/null +++ b/docs/setup-robusta/env-vars.rst @@ -0,0 +1,208 @@ +.. _Robusta env var reference: + +Environment Variable Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This page lists the environment variables most commonly set when deploying Robusta. It's intended as a +quick lookup so you don't have to read the source code to understand what each variable does or which +component reads it. + +These variables are set in your Helm values file: + +* On the runner, via ``runner.additional_env_vars`` +* On HolmesGPT (when installed via the Robusta Helm chart with ``enableHolmesGPT: true``), via ``holmes.additionalEnvVars`` + +Both fields accept the standard Kubernetes env var format, so values can be hardcoded or pulled from +``secretKeyRef`` / ``configMapKeyRef``. See :ref:`Managing Secrets` for examples. + +.. note:: + + The lists below cover variables a Robusta user typically needs to set. The runner and Holmes both + read additional internal/tuning variables that are not listed here. If a variable you need isn't + listed, check ``src/robusta/core/model/env_vars.py`` (runner) or ``holmes/common/env_vars.py`` + (Holmes) in the respective repositories. + +Runner (``runner.additional_env_vars``) +--------------------------------------------- + +Connecting to the Robusta backend +========================================== + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Variable + - Purpose + - Default + * - ``ROBUSTA_API_ENDPOINT`` + - Robusta SaaS API endpoint. Override for non-default regions (e.g. EU). + - ``https://api.robusta.dev`` + * - ``ROBUSTA_UI_DOMAIN`` + - Robusta UI domain used to build links in notifications. + - ``https://platform.robusta.dev`` + * - ``ROBUSTA_TELEMETRY_ENDPOINT`` + - Endpoint that receives telemetry pings. + - ``https://api.robusta.dev/telemetry`` + * - ``RELAY_EXTERNAL_ACTIONS_URL`` + - Endpoint that the runner posts external action requests to. + - ``https://api.robusta.dev/integrations/generic/actions`` + * - ``WEBSOCKET_RELAY_ADDRESS`` + - WebSocket relay address used for action callbacks from the UI. + - ``wss://relay.robusta.dev`` + * - ``ENABLE_TELEMETRY`` + - Set to ``false`` to disable telemetry. + - ``true`` + +Credentials (typically referenced from secrets) +===================================================== + +These are usually defined as env vars on the runner pod and then referenced from ``globalConfig`` / +``sinksConfig`` using the ``{{ env.X }}`` syntax. See +:ref:`Loading Robusta credentials from secrets` for the full pattern. + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Variable + - Purpose + * - ``ACCOUNT_ID`` + - Convention for an env var that holds your Robusta account ID. Referenced from ``globalConfig.account_id`` as ``{{ env.ACCOUNT_ID }}``. + * - ``SIGNING_KEY`` + - Convention for an env var that holds your runner signing key. Referenced from ``globalConfig.signing_key`` as ``{{ env.SIGNING_KEY }}``. + * - ``ROBUSTA_UI_TOKEN`` + - Convention for an env var that holds the Robusta UI sink token. Referenced from ``sinksConfig[].robusta_sink.token`` as ``{{ env.ROBUSTA_UI_TOKEN }}``. The same env var should also be set on Holmes (see below). + +.. note:: + + The names ``ACCOUNT_ID``, ``SIGNING_KEY``, and ``ROBUSTA_UI_TOKEN`` are conventions — you can pick + any env var names you like, as long as the names you set on the pod match the names you reference + from ``globalConfig`` / ``sinksConfig``. + +Other commonly set runner variables +========================================= + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Variable + - Purpose + - Default + * - ``HTTP_PROXY`` / ``HTTPS_PROXY`` + - Forward outbound traffic through an HTTP proxy. See :ref:`Deploying Behind Proxies`. + - unset + * - ``CERTIFICATE`` + - Additional CA certificate (base64-encoded). Useful for self-signed corporate proxies. + - unset + * - ``IS_OPENSHIFT`` + - Set to ``true`` when running on OpenShift. See :ref:`OpenShift`. + - ``false`` + * - ``CLUSTER_DOMAIN`` + - Override the cluster's DNS domain. + - ``cluster.local`` + +HolmesGPT (``holmes.additionalEnvVars``) +----------------------------------------------- + +Variables read by HolmesGPT when installed via the Robusta Helm chart (``enableHolmesGPT: true``). + +Connecting to the Robusta backend +========================================== + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Variable + - Purpose + - Default + * - ``ROBUSTA_AI`` + - Set to ``"true"`` to enable the Robusta-hosted AI integration. Required for users who want Holmes to talk to the Robusta backend. + - unset + * - ``ROBUSTA_UI_TOKEN`` + - Robusta UI sink token. Required for Holmes to authenticate to the Robusta backend; should be set to the same token as the runner's ``robusta_sink``. + - unset + * - ``ROBUSTA_ACCOUNT_ID`` + - Your Robusta account ID. Usually derived from ``ROBUSTA_UI_TOKEN`` automatically; only set explicitly if instructed by support. + - unset + * - ``ROBUSTA_API_ENDPOINT`` + - Robusta SaaS API endpoint. Override for non-default regions. + - ``https://api.robusta.dev`` + * - ``ROBUSTA_UI_DOMAIN`` + - Robusta UI domain. + - ``https://platform.robusta.dev`` + +LLM and runtime +======================== + +.. list-table:: + :widths: 25 50 25 + :header-rows: 1 + + * - Variable + - Purpose + - Default + * - ``MODEL`` + - LLM model identifier when using a single-model setup (e.g. ``gpt-4o``). For multi-model setups, configure ``modelList`` in Helm instead. + - unset + * - ``OPENAI_API_KEY`` / ``AZURE_OPENAI_ENDPOINT`` / ``ANTHROPIC_API_KEY`` / etc. + - LLM provider credentials. Set the ones your model requires. + - unset + * - ``LOG_LEVEL`` + - Log verbosity (``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``). + - ``INFO`` + * - ``HTTP_PROXY`` / ``HTTPS_PROXY`` + - Forward outbound traffic through an HTTP proxy. + - unset + * - ``CERTIFICATE`` + - Additional CA certificate (base64-encoded). + - unset + * - ``ENABLE_TELEMETRY`` + - Set to ``false`` to disable telemetry. + - ``false`` + +Quick reference: which component needs which credential? +----------------------------------------------------------------- + +.. list-table:: + :widths: 35 25 25 15 + :header-rows: 1 + + * - Setting + - Runner + - Holmes + - Set in + * - ``account_id`` + - ✅ + - — + - ``globalConfig`` + * - ``signing_key`` + - ✅ + - — + - ``globalConfig`` + * - Robusta UI / sink token + - ✅ + - ✅ + - ``sinksConfig`` (runner) + ``additionalEnvVars`` (Holmes) + * - ``ROBUSTA_API_ENDPOINT`` (non-default region) + - ✅ + - ✅ + - ``additional_env_vars`` / ``additionalEnvVars`` + * - ``ROBUSTA_UI_DOMAIN`` (non-default region) + - ✅ + - ✅ + - ``additional_env_vars`` / ``additionalEnvVars`` + * - ``ROBUSTA_AI=true`` + - — + - ✅ + - ``additionalEnvVars`` + +See also +----------- + +* :ref:`Managing Secrets` — how to keep these values out of plain text Helm values +* :ref:`Deploying Behind Proxies` — proxy-related env vars +* `Runner env vars in source `_ +* `HolmesGPT env vars in source `_ diff --git a/docs/setup-robusta/gitops/argocd.rst b/docs/setup-robusta/gitops/argocd.rst index 5f25d8bf4..8e8d08c30 100644 --- a/docs/setup-robusta/gitops/argocd.rst +++ b/docs/setup-robusta/gitops/argocd.rst @@ -49,10 +49,15 @@ Example ``generated_values.yaml``: .. - Requires more advanced ArgoCD functions to combine the robusta helm chart with the external ``generated_value.yaml`` file .. We'll describe the simpler option here. We're currently working on a guide for the more advanced option, contact us if you have questions. -.. admonition:: Secrets handling - :class: note +.. admonition:: Don't commit secrets in plain text + :class: warning + + The ``signing_key``, ``account_id``, and the ``robusta_sink`` ``token`` shown above are + sensitive. When using GitOps you typically don't want them in your Git repo as plain text. - Read this guide about :ref:`Managing Secrets`. + See :ref:`Loading Robusta credentials from secrets` for a complete example that loads all three + from a Kubernetes Secret (compatible with SealedSecrets, External Secrets, Vault, etc.). For + other sensitive Helm values, see :ref:`Managing Secrets`. Configure ArgoCD in the UI diff --git a/docs/setup-robusta/gitops/flux.rst b/docs/setup-robusta/gitops/flux.rst index 17b040272..cbf29e19f 100644 --- a/docs/setup-robusta/gitops/flux.rst +++ b/docs/setup-robusta/gitops/flux.rst @@ -36,10 +36,15 @@ Example ``generated_values.yaml``: runner: sendAdditionalTelemetry: true -.. admonition:: Secrets handling - :class: note +.. admonition:: Don't commit secrets in plain text + :class: warning + + The ``signing_key``, ``account_id``, and the ``robusta_sink`` ``token`` shown above are + sensitive. When using GitOps you typically don't want them in your Git repo as plain text. - Read this guide about :ref:`Managing Secrets`. + See :ref:`Loading Robusta credentials from secrets` for a complete example that loads all three + from a Kubernetes Secret (compatible with SealedSecrets, External Secrets, Vault, etc.). For + other sensitive Helm values, see :ref:`Managing Secrets`. Creating a ``HelmRepository`` diff --git a/docs/setup-robusta/index.rst b/docs/setup-robusta/index.rst index 777bf902e..aecbb9a61 100644 --- a/docs/setup-robusta/index.rst +++ b/docs/setup-robusta/index.rst @@ -17,6 +17,7 @@ upgrade tuning-performance configuration-secrets + env-vars openshift node-selector proxies