Skip to main content

Configure ingress

Ingress is used to expose the zymtrace backend services externally. The key component is the ui/gateway service, which serves both as the user interface and as the gateway that routes profiling events from the zymtrace profiler.

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

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 ui/gateway service​

To expose the ui/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:
    ui:
      enabled: true
      host: "zymtrace.example.com"  # UI service domain
      paths:
        - path: /
          pathType: Prefix

    ingest:
      enabled: true
      host: "zymtrace-ingest.example.com"  # gRPC endpoint for profiling agent
      paths:
        - path: /
          pathType: Prefix
      annotations:
       

  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.ui.host → Domain for the ui/gateway services.
  • annotations:
    • Enforces HTTPS (ssl-redirect).
    • Allows large request bodies for ingest (proxy-body-size: 0).
    • Configures gRPC support for ingest (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-ui       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: