Networking

Configure Gateway API for traffic routing, cert-manager for TLS certificates, and external-dns for automated DNS record management.

Networking

CRAFT uses Gateway API for traffic routing, cert-manager for TLS certificate lifecycle, and external-dns for automatic DNS record management. This guide covers the networking stack across cloud and on-premises environments.

Gateway API

EM-Runtime uses the Kubernetes Gateway API (v1) for all external traffic routing. Gateway API replaces traditional Ingress with a more expressive, role-oriented model.

Ingress Flow

Gateway Resource

The Gateway resource defines the load balancer and listeners. It must exist before the em-runtime chart deploys HTTPRoutes.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: em-runtime-gateway
  namespace: gateway
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  gatewayClassName: nginx    # or gke-l7-global-external-managed
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - name: platform-tls
    allowedRoutes:
      namespaces:
        from: All
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All

HTTPRoute Rules

The em-runtime Helm chart creates an HTTPRoute with these default rules:

Path Prefix	Backend Service	Port	URL Rewrite
/keycloak	keycloak	8080	None (pass-through)
/api/governance	em-runtime-governance	8000	/governance
/api/assets	em-runtime-assets	8000	/assets
/api/utils	em-runtime-utils	8000	/utils

Gateway Controllers by Platform

Platform	Controller	GatewayClassName
GKE	GKE Gateway Controller (built-in)	gke-l7-global-external-managed
EKS	AWS Load Balancer Controller	aws-application-load-balancer
AKS	Azure Application Gateway	azure-application-gateway
On-Prem	NGINX Gateway Fabric	nginx
On-Prem	Envoy Gateway	eg

Configuration in Helm

# Chart values for Gateway reference
gatewayName: "em-runtime-gateway"
gatewayNamespace: "gateway"
hostname: "api.example.com"

httpRoute:
  enabled: true
  rules:
    - pathPrefix: "/keycloak"
      serviceName: keycloak
      servicePort: 8080
    - pathPrefix: "/api/governance"
      rewritePrefix: "/governance"
      serviceName: em-runtime-governance
      servicePort: 8000

cert-manager

cert-manager automates TLS certificate provisioning and renewal. It supports ACME (Let’s Encrypt) and internal CA issuers.

Certificate Flow

Installation

Install cert-manager with Gateway API support:

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set config.enableGatewayAPI=true \
  --set crds.enabled=true

ClusterIssuer Configuration

Let's Encrypt (Production)

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v2.api.letsencrypt.org/directory
    email: [e-mail]
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
    - dns01:
        cloudDNS:                    # GCP
          project: your-project-id
        # route53:                   # AWS
        #   region: us-east-1
        # azureDNS:                  # Azure
        #   subscriptionID: ...

Internal CA (On-Prem)

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: internal-ca
spec:
  ca:
    secretName: internal-ca-key-pair
---
# Create the CA key pair first
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: internal-ca
  namespace: cert-manager
spec:
  isCA: true
  commonName: "CRAFT Internal CA"
  secretName: internal-ca-key-pair
  issuerRef:
    name: selfsigned
    kind: ClusterIssuer

DNS-01 Solver by Provider

Provider	Solver	IAM Requirement
GCP Cloud DNS	dns01.cloudDNS	Workload Identity service account
AWS Route 53	dns01.route53	IRSA role with Route 53 permissions
Azure DNS	dns01.azureDNS	Workload Identity managed identity
On-Prem (BIND)	dns01.rfc2136	TSIG key for dynamic DNS updates

Gateway Annotation

Annotate the Gateway to trigger automatic certificate provisioning:

metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod

cert-manager watches for Gateway resources with this annotation and provisions TLS certificates for each HTTPS listener.

external-dns

external-dns synchronizes Kubernetes resources (Gateway, Service, Ingress) with DNS providers, automatically creating A/CNAME records.

How It Works

1. external-dns watches Gateway and Service resources for hostname annotations
2. When a Gateway gets an external IP, external-dns creates a DNS A record
3. Records are updated or removed as resources change

Configuration by Provider

GCP Cloud DNS

provider: google
google:
  project: your-project-id
domainFilters:
  - runtime.dev.emergence.ai
policy: sync
sources:
  - gateway-httproute
  - service

Requires a Workload Identity service account with dns.admin role.

AWS Route 53

provider: aws
aws:
  region: us-east-1
domainFilters:
  - runtime.dev.emergence.ai
policy: sync
sources:
  - gateway-httproute
  - service

Requires an IRSA role with Route 53 ChangeResourceRecordSets permission.

On-Prem (RFC2136)

provider: rfc2136
rfc2136:
  host: dns.example.com
  port: 53
  zone: example.com
  tsigKeyname: external-dns
  tsigSecretAlg: hmac-sha256
policy: sync
sources:
  - gateway-httproute
  - service

Requires a TSIG key configured on the BIND DNS server.

TLS Requirements

Boundary	Requirement
Client to load balancer	TLS 1.2+ (certificate required)
Load balancer to pods	HTTP (in-cluster; TLS optional)
Services to PostgreSQL	SSL recommended (private network)
Services to Redis	TLS supported (rediss:// scheme)

Network Policies

For on-premises deployments, configure Kubernetes NetworkPolicies for defense in depth:

# Restrict data-insights egress to LLM API endpoints
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: talk2data-egress
  namespace: em-runtime
spec:
  podSelector:
    matchLabels:
      app: data-insights
  policyTypes:
  - Egress
  egress:
  - to:
    - ipBlock:
        cidr: 0.0.0.0/0
    ports:
    - port: 443
      protocol: TCP

Restrict data-insights egress to allowlisted LLM API endpoints (OpenAI, Anthropic, Vertex AI) for SSRF mitigation.

Firewall Rules

Ensure the following traffic is permitted:

Direction	Port	Protocol	Purpose
Inbound	443	TCP	HTTPS from clients
Inbound	80	TCP	HTTP redirect to HTTPS
Cluster to DB	5432	TCP	PostgreSQL
Cluster to Cache	6379	TCP	Redis
Cluster to S3	443	TCP	Object storage
Cluster to LLM	443	TCP	LLM API endpoints (data-insights)

DNS Architecture

One DNS A record pointing the platform hostname to the load balancer IP/CNAME:

api.example.com  →  A  →  <load-balancer-ip>

For GKE deployments, external-dns creates this automatically when the Gateway receives an IP address. For on-prem, configure the DNS record manually or use external-dns with RFC2136.

Troubleshooting

Certificate not provisioning

# Check cert-manager logs
kubectl logs -n cert-manager -l app=cert-manager

# Check certificate and challenge status
kubectl describe certificate -n gateway-system
kubectl get challenges -n gateway-system

Gateway not getting external IP

# Check Gateway status
kubectl describe gateway em-runtime-gateway -n gateway

# Verify the gateway controller is running
kubectl get pods -n gateway-system

DNS records not created

# Check external-dns logs
kubectl logs -l app.kubernetes.io/name=external-dns

# Verify IAM / Workload Identity
kubectl describe sa external-dns -n external-dns

Next Steps

Prerequisites

Complete networking prerequisites and firewall rules.