Architecture Overview
Hoop Gateway exposes two ports by default:- Port 8009: Web interface and REST API (HTTP/1.1 and HTTP/2)
- Port 8010: gRPC service (HTTP/2)
Prerequisites
Before configuring your reverse proxy:- Ensure your proxy server supports HTTP/2
- Configure TLS certificates
- Verify network connectivity between proxy and Hoop Gateway
- Understand your specific use case requirements (single domain vs multiple domains)
AWS Application Load Balancer
AWS Application Load Balancer (ALB) can route traffic to your Hoop Gateway instance with the following configuration:-
Load Balancer Configuration:
- Enable HTTP/2 support
- Configure SSL/TLS certificates
-
Target Groups
Web/API Target Group:
- Port: 8009
- Protocol Version: HTTP1 or HTTP2
- Health Check:
- Protocol: HTTP
- Path:
GET /api/healthz
- Port: 8009
- Port: 8010
- Protocol Version: gRPC
- Health Check:
- Protocol: HTTP
- Path:
GET /
- Port: 8010
Nginx (Single Port Configuration)
This configuration demonstrates how to proxy both HTTP and gRPC protocols using a single port with Nginx:Kubernetes Ingress Nginx
For Kubernetes deployments, you can use Ingress Nginx with separate domains for Web/API and gRPC services. This configuration performs TLS termination at the proxy level.Web Interface and REST Api ingress
Web Interface and REST Api ingress
gRPC Service Ingress
gRPC Service Ingress
The gRPC ingress configuration has two importante directives to proxy the connections:
nginx.ingress.kubernetes.io/backend-protocol: GRPC
- indicates the underline backend protocolnginx.ingress.kubernetes.io/proxy-body-size: '0'
- use unlimited body size to avoid issues when proxying bi-directional connections
Istio Envoy
For Istio deployments, you can configure the Envoy proxy to handle both HTTP/2 and gRPC traffic.It’s important to not define any timeout or retry policies for gRPC connections (8010 port) to avoid issues with long-lived connections.
- Kubernetes Gateway
- Istio Gateway
This example uses Kubernetes Gateway API to route traffic to Hoop Gateway
Make sure to port forward the istio gateway service to access the Hoop Gateway.
This example doesn’t support TLS termination.
Gateway
Gateway
HTTPRoute
HTTPRoute
Troubleshooting
gRPC Logging
Enable detailed logging for HTTP/2 and gRPC connectivity by setting these environment variables:- Agent:
hoop start agent
- Client:
hoop connect myconnection
Common Issues
RST_STREAM error code INTERNAL_ERROR
If you encounter this error:- VPN client configuration issues
- Incorrect gRPC protocol forwarding in reverse proxy
- HTTP/2 protocol not enabled in reverse proxy
HTTP/2 Frame Too Large
This error typically occurs in two scenarios:-
TLS Mismatch
- Ensure clients use TLS when the gateway or proxy requires it
- Verify
HOOP_KEY
usesgrpcs://
orhttps://
scheme for agent connections - Check
grpc_url
in$HOME/.hoop/config.toml
usesgrpcs://
orhttps://
for client connections
-
HTTP/2 Protocol Issues
- Verify HTTP/2 is enabled in your reverse proxy
- Ensure proper protocol forwarding settings