Skip to content

HTTP Proxy

Overview⚓︎

The HTTP proxy improves performance and stability by caching SELECT queries and routing traffic through a dedicated service pod. It's optional, and disabled by default.

The HTTP proxy feature was introduced in Hydrolix v5.4.0.

Routing behavior⚓︎

HTTP proxy uses port 9444 which always accepts query traffic.

  • If the proxy is enabled, traffic goes to the http-proxy pod
  • If the proxy is disabled, it routes directly to query heads

Grafana configuration⚓︎

To configure Grafana, set the Hydrolix Grafana plugin to use the HTTP connection to port 9444.

Authentication and TLS⚓︎

Credentials from the Grafana client pass through unchanged during authentication to the query head.

To enable mutual TLS authentication:⚓︎

  1. Set up the Redis/Valkey-based cache storage.
  2. Configure the HTTP proxy with a client certificate.
  3. Set use_tls=true.

TLS termination is done outside the proxy pod, and the proxy communicates over plain HTTP internally.

Cache options⚓︎

The HTTP proxy supports two cache backends: file-system and Redis/Valkey.

File-system cache⚓︎

In file_system mode, this cache type is best for:

  • Local development
  • Single-replica clusters
  • Simple setups without external dependencies

Cached responses are stored on the local disk of the proxy pod. Only the pod that served the query can return the cached result.

The cache is ephemeral; restarting the pod clears the cache.

Redis or Valkey cache⚓︎

Use redis mode for either Redis or Valkey. This cache type is best for:

  • Production environments
  • Multi-replica or distributed clusters
  • Scenarios that need a consistent shared cache

Cached responses are stored in an external Redis/Valkey service. All proxy replicas share the same cache data.

Prerequisites⚓︎

  • HTTP proxy requires Hydrolix v5.4.0 or newer
  • (Optional) To use Redis or Valkey for caching, you must provision an instance and provide the endpoint during configuration
  • Install Redis
  • Install Valkey
  • (Optional) TLS support requires a terminating proxy in front of Redis, Valkey, or valid certificates.
  • For TLS with authentication, prepare Kubernetes secrets containing:
    • HTTP_PROXY_REDIS_USERNAME
    • HTTP_PROXY_REDIS_PASSWORD
    • HTTP_PROXY_REDIS_TLS_CERT (client cert required when use_tls=true)
    • HTTP_PROXY_REDIS_TLS_KEY (client cert key required when use_tls=true)
  • (Optional) For Prometheus metrics, ensure Prometheus is installed and can scrape pod metrics.

Enable HTTP proxy⚓︎

To enable HTTP proxy, edit the hydrolixcluster.yaml configuration file and add this line to the spec: section:

1
2
3
4
hydrolixcluster:
  spec:
    http_proxy:
      enabled: true

Configure cache options⚓︎

To configure the cache option, select either File-System or Redis/Valkey cache setup and modify it to match your settings:

1
2
3
4
5
6
7
8
9
hydrolixcluster:
  spec:
    http_proxy:
      enabled: true
      cache:
        mode: file_system
        dir: /mnt/cache
        max_size: 500M
        expire: 2m

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
hydrolixcluster:
  spec:
    http_proxy:
      enabled: true
      cache:
        mode: redis
        addresses:
          - valkey-primary:6379
        pool_size: 20
        db_index: 0
        use_tls: true
        insecure_skip_verify: false
        expire: 1m

Verify pod creation⚓︎

After enabling HTTP proxy, verify the new pod is running in your cluster:

1
kubectl get pods -n <your-namespace> | grep http-proxy

You should see a pod named http-proxy-xxxxx with a Running status.

If the pod doesn't appear, check the operator logs or restart the operator pod.

Confirm routing behavior⚓︎

The cluster automatically routes traffic to the proxy when enabled.

  • Traffic to port 9444 goes through the http-proxy pod
  • If disabled, that traffic goes directly to the query heads

To test routing, run the following command:

1
curl -i https://<your-domain>:9444/query?query=SELECT%201

Look for this header:

1
X-Cache: HIT | MISS | N/A

Check cache behavior⚓︎

Run the same query twice.

  • The first response should return X-Cache: MISS.
  • The second response should return X-Cache: HIT if caching is working.

Add secrets for authentication (Redis mode only)⚓︎

These secrets are only required if your Redis/Valkey deployment uses authentication or TLS.

To use Redis/Valkey with TLS and authentication, modify this command to add your secrets:

1
2
3
4
5
6
7
8
kubectl -n <namespace> patch secret curated --type='json' \
  -p='[{"op": "add", "path": "/data/HTTP_PROXY_REDIS_USERNAME", "value": "'$(echo -n "youruser" | base64)'" }]'

kubectl -n <namespace> patch secret curated --type='json' \
  -p='[{"op": "add", "path": "/data/HTTP_PROXY_REDIS_PASSWORD", "value": "'$(echo -n "yourpass" | base64)'" }]'

kubectl -n <namespace> patch secret curated --type='json' -p='[{"op": "add", "path": "/data/HTTP_PROXY_REDIS_TLS_CERT", "value": "'$(cat ./ca.crt | base64)'" }]'
kubectl -n <namespace> patch secret curated --type='json' -p='[{"op": "add", "path": "/data/HTTP_PROXY_REDIS_TLS_KEY", "value": "'$(cat ./ca.key | base64)'" }]'