HTTP Proxy
Enable and configure HTTP proxy in a cluster
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:
- Set up the Redis/Valkey-based cache storage.
- Configure the HTTP proxy with a client certificate.
- 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
- (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)
- For TLS with authentication, prepare Kubernetes secrets containing:
- (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:
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:
hydrolixcluster:
spec:
http_proxy:
enabled: true
cache:
mode: file_system
dir: /mnt/cache
max_size: 500M
expire: 2m
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:
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 thehttp-proxy
pod - If disabled, that traffic goes directly to the query heads
To test routing, run the following command:
curl -i https://<your-domain>:9444/query?query=SELECT%201
Look for this header:
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:
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)'" }]'
Updated 9 days ago