Ingress configuration guide

Centralized guide for configuring Kubernetes ingress for FlowX.AI services

This guide provides the standard ingress configuration pattern for all FlowX.AI services that expose REST APIs or event streams to external clients.

Overview

FlowX.AI services use Kubernetes ingress with NGINX to expose APIs to the FlowX Designer and other external consumers. All services follow a consistent pattern with specific CORS headers required for multi-tenant workspace identification.

Standard ingress pattern

Common template

Most FlowX.AI services use this standard ingress configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <service-name>-admin
  annotations:
    nginx.ingress.kubernetes.io/client-body-buffer-size: "25M"
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://your-designer-domain.com,http://localhost:4200"
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "25m"
    nginx.ingress.kubernetes.io/rewrite-target: "<rewrite-pattern>"
spec:
  ingressClassName: nginx
  rules:
  - host: admin.your-domain.com
    http:
      paths:
      - path: <service-path>
        pathType: ImplementationSpecific
        backend:
          service:
            name: <service-name>
            port:
              name: http

Service-specific values

Replace the placeholders with service-specific values from this table:

Service	Ingress Name	Service Path	Rewrite Target
Admin	admin-admin	/((.*)) or `/admin(/	$)(.*)`	/$2
Application Manager	application-manager-admin	`/appmanager(/	$)(.*)`	/$2
Audit Core	audit-core-admin	`/audit(/	$)(.*)(/	$)(.*)`	/$2
Authorization System	authorization-system-admin	`/auth/api(/	$)(.*)(/	$)(.*)`	/api/$2
Integration Designer	integration-designer-admin	`/integration(/	$)(.*)`	/$2
Process Engine	process-engine-admin	`/onboarding/api(/	$)(.*)(/	$)(.*)`	/api/$2
Process Engine	process-engine-admin-instances	`/api/instances(/	$)(.*)(/	$)(.*)`	/api/instances/$2
Runtime Manager	runtime-manager-admin	`/rtm/api/runtime(/	$)(.*)`	/api/runtime/$2
Runtime Manager	runtime-manager-admin-instances	/rtm/api/(runtime|runtime-internal)/(.*)	/api/$1/$2
Task Management	task-management-plugin-admin	`/task(/	$)(.*)(/	$)(.*)`	/$2

Standard annotations explained

Required annotations

Annotation	Value	Purpose
nginx.ingress.kubernetes.io/client-body-buffer-size	25M	Buffer size for client request body
nginx.ingress.kubernetes.io/proxy-body-size	25m	Maximum size of client request body
nginx.ingress.kubernetes.io/cors-allow-credentials	true	Allow credentials in CORS requests
nginx.ingress.kubernetes.io/enable-cors	true	Enable CORS support
nginx.ingress.kubernetes.io/cors-allow-headers	Includes Fx-Workspace-Id	Headers allowed in CORS requests (workspace required)
nginx.ingress.kubernetes.io/cors-allow-origin	Designer domain(s)	Origins allowed for CORS requests
nginx.ingress.kubernetes.io/rewrite-target	Service-specific	URL rewrite pattern

Workspace identification header

The Fx-Workspace-Id header is required in the cors-allow-headers annotation for all services except Events Gateway.

The Fx-Workspace-Id header enables multi-tenant workspace identification. Include it in the CORS allowed headers:

nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"

Events Gateway exception

The Events Gateway service handles Server-Sent Events (SSE) and uses a simplified ingress configuration without the cors-allow-headers annotation:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: events-gateway-admin
  annotations:
    nginx.ingress.kubernetes.io/client-body-buffer-size: "25M"
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://your-designer-domain.com,http://localhost:4200"
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "25m"
    nginx.ingress.kubernetes.io/rewrite-target: "/api/events/$2"
spec:
  ingressClassName: nginx
  rules:
  - host: admin.your-domain.com
    http:
      paths:
      - path: /api/events(/|$)(.*)(/|$)(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: events-gateway
            port:
              name: http

Events Gateway does not require the Fx-Workspace-Id header in its ingress configuration because it handles real-time SSE connections with different security requirements.

Environment-specific customization

Required changes per environment

Update these values for your specific environment:

1. CORS Origins - Replace with your actual domains:

   nginx.ingress.kubernetes.io/cors-allow-origin: "https://designer.yourcompany.com,https://admin.yourcompany.com"
   

2. Host - Set to your ingress hostname:

   rules:
   - host: admin.yourcompany.com
   

3. TLS Configuration - Add TLS section if using HTTPS:

   tls:
   - hosts:
     - admin.yourcompany.com
     secretName: admin-tls-secret
   

Development vs Production

Development:

nginx.ingress.kubernetes.io/cors-allow-origin: "http://localhost:4200,http://localhost:4300"

Production:

nginx.ingress.kubernetes.io/cors-allow-origin: "https://designer.yourcompany.com"

Complete example

Here’s a complete, production-ready ingress configuration for the Admin service:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: admin-admin
  namespace: flowx-production
  annotations:
    nginx.ingress.kubernetes.io/client-body-buffer-size: "25M"
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://designer.yourcompany.com"
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "16m"
    nginx.ingress.kubernetes.io/rewrite-target: "/$2"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  rules:
  - host: admin.yourcompany.com
    http:
      paths:
      - path: /((.*))
        pathType: ImplementationSpecific
        backend:
          service:
            name: admin
            port:
              name: http
  tls:
  - hosts:
    - admin.yourcompany.com
    secretName: admin-tls-secret

Troubleshooting

CORS errors

Problem: Browser shows CORS policy errors

Solution: Verify that:

1. Fx-Workspace-Id is included in cors-allow-headers
2. Your origin is listed in cors-allow-origin
3. enable-cors is set to true

413 Request Entity Too Large

Problem: Large file uploads fail

Solution: Increase buffer sizes:

nginx.ingress.kubernetes.io/client-body-buffer-size: "50M"
nginx.ingress.kubernetes.io/proxy-body-size: "50m"

502 Bad Gateway

Problem: Service unreachable through ingress

Solution: Verify:

1. Service name matches the backend service
2. Port name is correct (typically http)
3. Service is running and healthy

Path routing issues

Problem: Requests return 404

Solution: Check:

1. Path pattern matches your URL structure
2. Rewrite target correctly transforms the path
3. Service expects the rewritten path format

Best practices

Security

• Use HTTPS in production
• Restrict CORS origins to known domains
• Never use wildcards in production CORS origins
• Keep buffer sizes reasonable (25M is sufficient for most use cases)

Performance

• Use appropriate buffer sizes for your workload
• Monitor ingress metrics
• Configure timeouts for long-running requests
• Consider connection limits for SSE endpoints

Maintainability

• Use consistent naming conventions
• Document any deviations from standard pattern
• Keep annotations organized alphabetically
• Use ConfigMaps for shared values

Reliability

• Always include health check paths
• Configure proper timeouts
• Use multiple replicas for high availability
• Monitor ingress logs for errors

Additional resources

NGINX Ingress Controller Documentation

Kubernetes Ingress Documentation