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