> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-docs-improve-idp-sso-pages.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Reverse Proxy

> Deploying Hoop Behind a Reverse Proxy

Hoop Gateway can be deployed behind a reverse proxy to enhance security, enable load balancing, and optimize production performance.
This guide covers configuration steps for reverse proxy setups.

## 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)

When setting up a reverse proxy, both ports need to be properly configured to ensure all functionality works correctly.

## 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:

1. Load Balancer Configuration:

   * Enable HTTP/2 support
   * Configure SSL/TLS certificates

2. Target Groups

   **Web/API Target Group:**

   * Port: 8009
   * Protocol Version: HTTP1 or HTTP2
   * Health Check:
     * Protocol: HTTP
     * Path: `GET /api/healthz`
     * Port: 8009

   **gRPC Target Group:**

   * 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:

```nginx theme={null}
events {
    worker_connections  1024;
}

http {
    server {
        listen       443 ssl http2;
        server_name  hoop-gateway.domain.tld;

        # SSL Configuration
        ssl_certificate /path/to/server.pem;
        ssl_certificate_key /path/to/privatekey.pem;

        # gRPC Protocol Handler
        location /protobuf.Transport/Connect {
            client_max_body_size 0;
            grpc_pass grpc://127.0.0.1:8010;
            break;
        }

        # Web Interface and REST API Handler
        location / {
            proxy_pass http://127.0.0.1:8009;
        }
    }
}
```

## 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.

<AccordionGroup>
  <Accordion title="Web Interface and REST Api ingress">
    ```yaml theme={null}
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: hoopgateway-web
    spec:
      ingressClassName: nginx
      rules:
      - host: hoopgateway-web.domain.tld
        http:
          paths:
          - backend:
              service:
                name: hoopgateway
                port:
                  number: 8009
            pathType: ImplementationSpecific
      tls:
      - hosts:
          - hoop-gateway-web.domain.tld
          secretName: hoopdev-tls
    ```
  </Accordion>

  <Accordion title="gRPC Service Ingress">
    ```yaml theme={null}
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      annotations:
        nginx.ingress.kubernetes.io/backend-protocol: GRPC
        nginx.ingress.kubernetes.io/proxy-body-size: '0'
      name: hoopgateway-grpc
    spec:
      ingressClassName: nginx
      rules:
      - host: hoopgateway-grpc.domain.tld
        http:
          paths:
          - backend:
              service:
                name: hoopgateway
                port:
                  number: 8010
            pathType: ImplementationSpecific
      tls:
      - hosts:
          - hoop-gateway-grpc.domain.tld
        secretName: hoopdev-tls
    ```

    <Info>
      The gRPC ingress configuration has two importante directives to proxy the connections:

      * `nginx.ingress.kubernetes.io/backend-protocol: GRPC` - indicates the underline backend protocol
      * `nginx.ingress.kubernetes.io/proxy-body-size: '0'` - use unlimited body size to avoid issues when proxying bi-directional connections
    </Info>
  </Accordion>
</AccordionGroup>

## Istio Envoy

For [Istio deployments](http://istio.io/docs/), you can configure the Envoy proxy to handle both HTTP/2 and gRPC traffic.

<Tip>
  It's important to not define any timeout or retry policies for gRPC connections (8010 port) to avoid issues with long-lived connections.
</Tip>

Below is an example of how to set up the Envoy configuration:

<Tabs>
  <Tab title="Kubernetes Gateway">
    This example uses Kubernetes Gateway API to route traffic to Hoop Gateway

    <Note>
      Make sure to port forward the istio gateway service to access the Hoop Gateway.
      This example doesn't support TLS termination.
    </Note>

    <AccordionGroup>
      <Accordion title="Gateway">
        ```yaml theme={null}
        apiVersion: gateway.networking.k8s.io/v1
        kind: Gateway
        metadata:
          name: hoopgateway
        spec:
          gatewayClassName: istio
          listeners:
          - name: http
            hostname: "hoop.yourdomain.org"
            port: 80
            protocol: HTTP
            allowedRoutes:
              namespaces:
                from: Same
        ```
      </Accordion>

      <Accordion title="HTTPRoute">
        ```yaml theme={null}
        apiVersion: gateway.networking.k8s.io/v1
        kind: HTTPRoute
        metadata:
          name: hoopgateway-route
        spec:
          parentRefs:
          - name: hoopgateway
          hostnames: ["hoop.yourdomain.org"]
          rules:
          - matches:
            - path:
                type: PathPrefix
                value: /protobuf.Transport
            backendRefs:
            - name: hoopgateway
              port: 8010
          - matches:
            - path:
                type: PathPrefix
                value: /
            backendRefs:
            - name: hoopgateway
              port: 8009
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Istio Gateway">
    This example uses Istio's Gateway and VirtualService to route traffic to Hoop Gateway

    <Note>
      Make sure to port forward the istio gateway service to access the Hoop Gateway.
    </Note>

    <AccordionGroup>
      <Accordion title="Istio Gateway">
        ```yaml theme={null}
        apiVersion: networking.istio.io/v1beta1
        kind: Gateway
        metadata:
          name: hoopgateway
        spec:
          selector:
            # The selector matches the istio ingress gateway. It may vary based on your Istio installation.
            istio: ingress
          servers:
          - port:
              number: 80
              name: http
              protocol: HTTP
            hosts:
            - hoop.yourdomain.org
          - port:
              number: 443
              name: https
              protocol: HTTPS
            tls:
              mode: SIMPLE
              credentialName: hoopgateway-tls # Name of the TLS secret in Kubernetes
            hosts:
            - hoop.yourdomain.org
        ```

        <Tip>
          To create a secret with a self signed TLS certificate for the Istio Gateway, you can use the following command:

          ```sh theme={null}
          kubectl create secret tls hoopdev-tls  -n istio-ingress \
            --key server.key \
            --cert server-bundle.crt
          ```

          * `server.key`: Private key of the TLS certificate
          * `server-bundle.crt`: Bundle of the TLS certificate and CA certificate
        </Tip>
      </Accordion>

      <Accordion title="Virtual Service">
        ```yaml theme={null}
        apiVersion: networking.istio.io/v1beta1
        kind: VirtualService
        metadata:
          name: hoopgateway
        spec:
          hosts:
          - hoop.yourdomain.org
          gateways:
          - hoopgateway
          http:
          - match:
            - uri:
                prefix: /protobuf.Transport
            route:
            - destination:
                host: hoopgateway
                port:
                  number: 8010
          - match:
            - uri:
                prefix: /
            route:
            - destination:
                host: hoopgateway
                port:
                  number: 8009
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

# Troubleshooting

### gRPC Logging

Enable detailed logging for HTTP/2 and gRPC connectivity by setting these environment variables:

```sh theme={null}
export GODEBUG=http2debug=2
export LOG_GRPC=1
```

Test connectivity using:

* Agent: `hoop start agent`
* Client: `hoop connect myconnection`

## Common Issues

### RST\_STREAM error code INTERNAL\_ERROR

If you encounter this error:

```
rpc error: code = Internal desc = stream terminated by RST_STREAM
with error code: INTERNAL_ERROR
```

Check these common causes:

* 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:

1. **TLS Mismatch**

   * Ensure clients use TLS when the gateway or proxy requires it
   * Verify `HOOP_KEY` uses `grpcs://` or `https://` scheme for agent connections
   * Check `grpc_url` in `$HOME/.hoop/config.toml` uses `grpcs://` or `https://` for client connections

2. **HTTP/2 Protocol Issues**

   * Verify HTTP/2 is enabled in your reverse proxy
   * Ensure proper protocol forwarding settings