Skip to main content

Configure ingress

Ingress is used to expose zymtrace backend services externally. There are two key components:

  • UI Service: Where users interact with zymtrace in their browser.
  • gRPC Ingest Service: The endpoint that receives performance profiles from the profiling agent.

For proper functionality, the ingest service requires a gRPC-enabled ingress, while the UI service handles standard HTTP/S traffic.

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 Ingress for gRPC and UI​

To expose the UI and gRPC ingest services, 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

  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:
        nginx.ingress.kubernetes.io/backend-protocol: "GRPC"  # Enable gRPC

  tls:
    - secretName: zymtrace-tls
      hosts:
        - "zymtrace.example.com"
        - "zymtrace-ingest.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 & hosts.ingest.host → Domains for the UI and ingest 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
zymtrace-ingest   nginx   zymtrace-ingest.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
zymtrace-ingest.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 Ingres​

Test UI Access​

Open your browser and visit:

https://zymtrace.example.com

Test gRPC Ingest Endpoint​

Use grpcurl to send test data to the gRPC ingest service:

grpcurl -insecure -d '{}' zymtrace-ingest.example.com:443 zymtrace.ingest.Service/Method

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

Conclusion​

You’ve successfully configured ingress for zymtrace backend services! 🎉

  • Users can access the UI outside your cluster, e.g https://zymtrace.example.com.
  • The profiling agent can send profiling data to the ingest service, .e.g zymtrace-ingest.example.com:443 via gRPC.

For additional customization, refer to: