OpenFaaS Integration & Serverless Functions

Aevum Encyclopedia utilizes OpenFaaS to orchestrate event-driven, stateless microservices across our global infrastructure. This architecture enables horizontal scaling for compute-intensive workloads such as citation validation, media transcoding, search indexing, and real-time content moderation.

System Architecture

The serverless layer sits between the API gateway and persistent storage. Incoming requests are routed through the faas-gateway, which handles authentication, rate limiting, and request forwarding to the appropriate function pod.

Architecture Flow
Copy
Client → CDN → API Gateway → faas-gateway
       ├── auth-validator (gRPC)
       ├── content-indexer (HTTP)
       ├── citation-parser (HTTP)
       └── media-transcoder (HTTP + S3 Trigger)

Functions → Redis Cache / PostgreSQL / NATS Queue

Core Function Registry

Deployment Configuration

Service Definition

Functions are deployed using stack.yml. Below is a production-ready template for the citation parser:

stack.yml
Copy
version: 1.0
provider:
  name: faas
  gateway: https://faas.aevum-enc.edu
  functions:
    citation-parser:
      lang: python3.11
      handler: ./handlers/citation
      image: registry.aevum.io/encyclopedia/citation-parser:latest
      environment:
        REDIS_HOST: cache.internal
        ELASTIC_HOST: search.internal
        CONCURRENCY: 8
      limits:
        memory: 256M
        requests: 1000
      annotations:
        prometheus.io/scrape: "true"

CLI Deployment

bash
Copy
# Build and push container
faas-cli build -f stack.yml
faas-cli publish -f stack.yml

# Deploy to cluster
faas-cli deploy -f stack.yml --gateway=https://faas.aevum-enc.edu

# Verify rollout
faas-cli list --gateway=https://faas.aevum-enc.edu

Autoscaling Policies

OpenFaaS uses metric-driven autoscaling. Functions scale based on pending requests, CPU utilization, or custom Prometheus metrics.

To configure scaling, add annotations to your function definition:

YAML Annotations
Copy
  annotations:
    com.openfaas.scale.min: "3"
    com.openfaas.scale.max: "50"
    com.openfaas.scale.factor: "20"  # 20 pending requests

Monitoring & Observability

Every function exposes Prometheus-compatible metrics at /system/metrics. Key metrics include:

• http_requests_total{function="name"} - Total requests by status
• http_request_duration_seconds - Latency histogram
• faas_function_pending_requests - Queue depth
• faas_function_memory_usage_bytes - RSS memory consumption

Logs are shipped to Loki via the Fluent Bit daemonset. Use the following query to trace function invocations:

LogQL
Copy
{app="faas-provider", function="citation-parser"} |= "error" | json | request_id != ""

Grafana dashboards are available at grafana.aevum-enc.edu/d/openfaas with read-only access for partners.

CLI Reference

The faas-cli is the primary tool for function lifecycle management. Ensure you're running v0.14.0+ for full Kubernetes provider support.

Common Commands
Copy
faas-cli up -f stack.yml          # Build, publish, deploy
faas-cli invoke          # Local/test invocation
faas-cli logs            # Stream stdout/stderr
faas-cli secret create       # Push to K8s secrets
faas-cli rollout         # Rolling update without downtime

Troubleshooting

Common Issues

• 504 Gateway Timeout: Function cold start exceeded gateway timeout (default 60s). Increase read_timeout or optimize init logic.
• OOMKilled: Memory limit too low. Check heap profiling and adjust limits.memory.
• Pod CrashLoopBackOff: Missing environment variables or invalid handler path. Run faas-cli build --no-cache locally first.

For cluster-level diagnostics, inspect the provider logs:

bash
Copy
kubectl logs -n openfaas-fn -l app=faas-provider --tail=100