Skip to main content

Configure Ingress

Ingress is used to expose the zymtrace gateway service outside your cluster. The gateway service routes user requests to the UI, profiling and metrics events to the ingest service, and symbols to the symdb service.

For proper functionality, the gateway service requires an Ingress with gRPC support.

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   GPU/CPU       │    │    Symbols      │    │ User Request    │    │    Metrics      │
│   Profiling     │    │                 │    │                 │    │                 │
│   Events        │    │                 │    │                 │    │                 │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │                      │
          └──────────────────────┼──────────────────────┼──────────────────────┘
                                 │                      │
                                 └──────────┬───────────┘
                                            │
                                            ▼
                               ┌─────────────────────────┐
                               │        Ingress LB       │
                               │      (gRPC Support)     │
                               │                         │                    
                               │                         │
                               └─────────────┬───────────┘
                                             │
                                             ▼
                              ┌─────────────────────────┐
                              │    Gateway Service      │
                              │   (Powered by Envoy)    │
                              │                         │
                              │ • Routes to UI          │
                              │ • Routes to ingest      │
                              │ • Routes to symdb       │
                              └─────────────────────────┘
NodePort

The helm chart supports NodePort to enable rapid iteration in test environments. NodePort is great for PoC or to see how zymtrace works. We recommend using Ingress in production.

services:
  gateway:
    # Service type configuration: ClusterIP, NodePort, or LoadBalancer
    service:
      type: NodePort
      nodePort: "32080"

Ingress requirements​

Before setting up ingress, ensure you have:

  • A Kubernetes cluster with an Ingress controller (e.g., NGINX Ingress Controller).
  • A DNS setup for accessing services:
    • Internal DNS: You can use an internal domain (e.g., zymtrace.local) within your private network.
    • External DNS (Optional): If required, configure a registered domain (e.g., zymtrace.example.com).
  • An SSL/TLS certificate:
    • Production environment: A valid certificate from a trusted CA.
    • Development environment: Either disable TLS using --disable-tls in the agent config or use valid certificates (self-signed certificates are not supported by the agent).

1. Enabling gRPC ingress for the gateway service​

To expose the gateway service, update the custom-values.yaml as shown below:

custom-values.yaml
ingress:
  enabled: true
  className: "nginx"  # Specify your ingress controller (e.g., nginx, traefik)

  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"  # Force HTTPS
    nginx.ingress.kubernetes.io/proxy-body-size: "0"  # Allow large payloads
    nginx.ingress.kubernetes.io/client-body-buffer-size: "1M"  # Buffer size
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"  # Enable gRPC

  hosts:
    gateway:
      enabled: true
      host: "zymtrace.example.com"  # Gateway service domain
      paths:
        - path: /
          pathType: Prefix
      annotations:
        nginx.ingress.kubernetes.io/proxy-body-size: "0"  # Allow large payloads for symbol uploads
        nginx.ingress.kubernetes.io/client-body-buffer-size: "1M"  # Buffer size

  tls:
    - secretName: zymtrace-tls
      hosts:
        - "zymtrace.example.com"

Explanation of Configuration​

  • enabled: true → Enables ingress for zymtrace.
  • className: "nginx" → Specifies the ingress controller (change if using Traefik, ALB, etc.).
  • hosts.gateway.host → Domain for the gateway service.
  • annotations:
    • Enforces HTTPS (ssl-redirect).
    • Allows large request bodies (proxy-body-size: 0) for symbol uploads and profiling data.
    • Configures gRPC support (backend-protocol: "GRPC").
  • tls → Defines TLS certificates for secure communication.

2. Deploying Ingress​

Once custom-values.yaml is updated, deploy ingress using Helm:

helm upgrade --install backend zymtrace/backend -f custom-values.yaml

Verify that ingress is created:

kubectl get ingress -n zymtrace

Expected output:

NAME                CLASS   HOSTS                              ADDRESS        PORTS   AGE
zymtrace-gateway    nginx   zymtrace.example.com              192.168.1.10   80,443  5m

3. Configuring DNS​

To access zymtrace externally outside your kubernetes cluster, set A records in your DNS provider to point to the ingress external IP.

Find the external IP:

kubectl get svc -n zymtrace | grep ingress-nginx

Example output:

ingress-nginx-controller   LoadBalancer   192.168.1.10   80:32443/TCP

Create the following DNS records:

SubdomainTypeValue
zymtrace.example.comA192.168.1.10

4. Enabling Automatic TLS with Cert-Manager (Optional)​

To automatically issue Let's Encrypt certificates, add this annotation to custom-values.yaml:

custom-values.yaml
annotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"

Then, redeploy:

helm upgrade --install backend zymtrace/backend -f custom-values.yaml

Verify that TLS certificates are issued:

kubectl describe certificate -n zymtrace

5. Testing the Ingress​

Test UI Access​

Open your browser and visit:

https://zymtrace.example.com/

6. Troubleshooting​

Check Ingress Logs​

kubectl logs -n zymtrace -l app.kubernetes.io/name=ingress-nginx

Verify Ingress Configuration​

kubectl describe ingress -n zymtrace

Test Direct Connectivity​

  
 curl -v -H "Host: zymtrace.example.com" zymtrace.example.com

If issues arise, check:

  • Ingress annotations (ensure backend-protocol: "GRPC" is set).
  • TLS settings (ensure correct certificates are used).
  • DNS records (confirm they match the ingress external IP).

For additional customization, refer to: