Skip to main content

Configure the Ask AI provider key

Turn on Ask AI with an OpenRouter key or keep it off, limit questions per reader, also behind Cloudflare, and read the logs of a failed answer.

Ask AI answers questions in the documentation once the documentation pod holds an OpenRouter API key. This page covers supplying or disabling that key in the dalp Helm chart, configuring per-reader rate limits, applying cluster-level Envoy Gateway resources behind Cloudflare, and diagnosing failed answers. See Configure values and secrets for other Helm values.

Ask AI provider key

Ask AI is the question-and-answer chat on the documentation site served under /docs on the Console hostname. The browser sends each question to the documentation server, and only the server calls OpenRouter, so the API key never reaches the browser.

Each request sends the conversation and matching documentation passages to OpenRouter on a DeepSeek model chosen by DALP. The API key does not select the model. The investor documentation site has no Ask AI and receives no key.

Share the Console assistant key or supply a separate key

The chart passes the key to the documentation pod as OPENROUTER_API_KEY, read from a Kubernetes Secret named by docs.openRouter.existingSecret and docs.openRouter.existingSecretKeys.apiKey.

By default, those fields point at the release's shared environment Secret and its ASSISTANT_OPENROUTER_API_KEY entry (rendered from global.dalpApp.env). Setting global.dalpApp.env.ASSISTANT_OPENROUTER_API_KEY from your secret store turns on both Ask AI and the Console assistant for organisations without their own key.

Use a separate key when another team funds or caps documentation traffic in its own OpenRouter account:

  • Existing Secret: Create a Secret in the release namespace, point docs.openRouter.existingSecret at it, and set docs.openRouter.existingSecretKeys.apiKey to the entry holding the key.
  • Chart-rendered Secret: Set docs.openRouter.existingSecret to "" and supply docs.openRouter.apiKey at deploy time from your secret store. The chart renders a Secret (named docs-openrouter-key with default naming) using the entry name in docs.openRouter.existingSecretKeys.apiKey. Note that the Helm release record stores this value like any other secret in Helm values.

Validation rules enforced by helm install and helm upgrade:

  • Setting both docs.openRouter.existingSecret and docs.openRouter.apiKey fails the render. Clear existingSecret to "" whenever you pass apiKey.
  • Setting docs.openRouter.apiKey while docs.openRouter.existingSecretKeys.apiKey is empty fails the render.
  • Adding OPENROUTER_API_KEY directly in docs.env fails the render.

The documentation pod does not run summon, so a Conjur secrets.yml mapping never reaches it. Always supply the key through a Kubernetes Secret.

Keep Ask AI off

To keep Ask AI off while the Console assistant keeps its key, clear docs.openRouter.existingSecret and leave docs.openRouter.apiKey empty:

docs:
  openRouter:
    existingSecret: ""

With no key, an empty key, or a missing Secret entry, the pod starts normally, /docs/api/chat returns 404, Ask AI entry points stay hidden, and built-in documentation search continues working without contacting OpenRouter.

Verify the active state

Check /docs/api/chat-config on the Console hostname:

curl -fsS https://console.example.com/docs/api/chat-config

The endpoint returns {"enabled":true} when the pod holds a key and {"enabled":false} when it does not. This confirms key presence only: an invalid OpenRouter key still reports enabled, and each question ends with “The answer could not be completed. Try again.” Restart the documentation pods after changing a Secret unless your cluster restarts them automatically.

Rate limits and trusted proxy

Anyone who can reach /docs can ask questions and spend OpenRouter credit. The documentation server admits up to 10 questions a minute per client and 300 an hour in total, distinguishing clients by the address your routing layer forwards.

When global.dalpApp.env defines REDIS_URL, documentation pods share rate-limit counters in Redis. Without Redis, each pod enforces its own 10-per-minute and 300-per-hour limits independently.

The chart derives DOCS_CHAT_TRUSTED_PROXY automatically (envoy, nginx or openshift) only when docs.service.type is ClusterIP and exactly one of docs.ingress.enabled, docs.httpRoute.enabled and docs.openShiftRoute.enabled is true. Otherwise it sets none, so all readers share one 10-questions-per-minute allowance. Because the default dalp chart enables both Ingress and HTTPRoute for docs, the default install uses none.

To override that derivation, set DOCS_CHAT_TRUSTED_PROXY in docs.env to envoy, nginx or openshift, and only when every public path to /docs passes through that proxy. Any other value causes Ask AI, search and Model Context Protocol requests to fail.

Count readers separately behind Cloudflare

These ClientTrafficPolicy and EnvoyProxy manifests belong in your Envoy Gateway cluster configuration (the namespace that owns your Gateway), not inside the dalp Helm release values.

Behind Cloudflare, Envoy Gateway sees a Cloudflare edge IP instead of each reader's IP, causing readers routed through the same Cloudflare address to share one budget. To count each reader separately, configure Envoy Gateway to trust the hop Cloudflare appends to X-Forwarded-For, keep that entry last, strip caller-supplied x-envoy-external-address headers, and restrict the load balancer to Cloudflare IP ranges.

Set the dalp chart proxy profile

When DOCS_CHAT_TRUSTED_PROXY is envoy, the documentation server reads x-envoy-external-address first and falls back to the last entry of X-Forwarded-For when that header is absent or invalid. It never reads earlier entries, which callers can spoof.

To have the chart set DOCS_CHAT_TRUSTED_PROXY=envoy automatically, keep docs.service.type: ClusterIP and docs.httpRoute.enabled: true, and set docs.ingress.enabled: false and docs.openShiftRoute.enabled: false. Also set global.dalpApp.config.trustedProxy.profile: envoy so the Console, Investor portal and Platform API apply the same rule and record real client addresses in the audit trail.

Apply Envoy Gateway policies to your Gateway

Cloudflare appends the reader's IP as the final entry of X-Forwarded-For. When Envoy Gateway enables xForwardedFor, it stops setting x-envoy-external-address (so an untrusted caller header would pass through) and appends Cloudflare's IP unless disableXForwardedForAppend: true is set (requires Envoy Gateway 1.9 or later).

Apply both ClientTrafficPolicy and EnvoyProxy together. If the load balancer still accepts direct connections from arbitrary IPs, callers can spoof X-Forwarded-For and bypass rate limits. Ensure no extra proxy sits between Cloudflare and your load balancer.

Add clientIPDetection and headers.earlyRequestHeaders.remove to the existing ClientTrafficPolicy targeting your Gateway (Envoy Gateway honours only the oldest policy per Gateway, and listener-scoped policies using sectionName override Gateway-wide ones). If none exists, create one:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: client-ip
  namespace: <gateway-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: <gateway-name>
  clientIPDetection:
    xForwardedFor:
      numTrustedHops: 1
      disableXForwardedForAppend: true
  headers:
    earlyRequestHeaders:
      remove:
        - x-envoy-external-address

Restrict the load balancer Service in the EnvoyProxy referenced by your Gateway or GatewayClass (parametersRef). If other Gateways must remain reachable without Cloudflare, attach a dedicated EnvoyProxy to this Gateway. Compare the IPv4 and IPv6 ranges below against https://www.cloudflare.com/ips-v4 and https://www.cloudflare.com/ips-v6 before applying (published November 2026):

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: <proxy-name>
  namespace: <gateway-namespace>
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
        externalTrafficPolicy: Local
        loadBalancerSourceRanges:
          - 173.245.48.0/20
          - 103.21.244.0/22
          - 103.22.200.0/22
          - 103.31.4.0/22
          - 141.101.64.0/18
          - 108.162.192.0/18
          - 190.93.240.0/20
          - 188.114.96.0/20
          - 197.234.240.0/22
          - 198.41.128.0/17
          - 162.158.0.0/15
          - 104.16.0.0/13
          - 104.24.0.0/14
          - 172.64.0.0/13
          - 131.0.72.0/22
          - 2400:cb00::/32
          - 2606:4700::/32
          - 2803:f800::/32
          - 2405:b500::/32
          - 2405:8100::/32
          - 2a06:98c0::/29
          - 2c0f:f248::/32

Verify that your cloud provider enforces loadBalancerSourceRanges, and block the Service's node ports from external traffic.

Diagnose failed answers

When an answer fails, read the documentation pod logs for Ask AI provider call failed:

Field or stage value
Meaning
Next check
stage=no-response
No HTTP response arrived from OpenRouter (error_code shows the network error).
Check DNS, egress rules and the host probe lines below.
stage=first-chunk or between-chunks
OpenRouter responded but sent no text in time.
Check OpenRouter status and outbound proxy buffering.
stage=total
The response ran past the 30-second total budget.
Check OpenRouter latency or retry.
stage=response
OpenRouter returned an HTTP error (provider_status holds the status, such as 401 or 429).
Verify the API key (401) or OpenRouter account limits (429).

After a no-response failure, the pod runs direct connectivity probes against openrouter.ai and logs Ask AI provider host probe within 20 seconds (info on success, error on failure):

  • stage=provider-host-lookup: records whether openrouter.ai resolved.
  • stage=provider-host-connect (address_family ipv4 or ipv6): opens and immediately closes TCP port 443 to the first resolved address. Each line reports elapsed_ms, timed_out (true past 10 seconds) and error_code (no_address if that family has no record).

These probes connect directly and ignore pod HTTP proxy variables, so failed provider-host-connect lines are expected behind an outbound proxy. Without a proxy, failures on both families indicate blocked egress on port 443. A passing ipv4 probe with a failing ipv6 probe is normal because the HTTP client falls back to IPv4, though TLS or HTTP inspection can still block the call.

If logs show Docs client address unavailable when DOCS_CHAT_TRUSTED_PROXY is envoy, nginx or openshift, requests arrived without a usable forwarded IP and fell back to the shared rate-limit bucket. Inspect envoy_external_address_present and forwarded_for_present (true or false) and confirm every public route to /docs passes through the configured proxy (Envoy Gateway for envoy, NGINX Ingress for nginx or the OpenShift router for openshift).