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)
Internal CA (On-Prem)

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

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

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

Configuration by Provider

GCP Cloud DNS
AWS Route 53
On-Prem (RFC2136)

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.

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.

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.

​Networking

​Gateway API

​Ingress Flow

​Gateway Resource

​HTTPRoute Rules

​Gateway Controllers by Platform

​Configuration in Helm

​cert-manager

​Certificate Flow

​Installation

​ClusterIssuer Configuration

​DNS-01 Solver by Provider

​Gateway Annotation

​external-dns

​How It Works

​Configuration by Provider

​TLS Requirements

​Network Policies

​Firewall Rules

​DNS Architecture

​Troubleshooting

​Next Steps

Prerequisites

Networking

Gateway API

Ingress Flow

Gateway Resource

HTTPRoute Rules

Gateway Controllers by Platform

Configuration in Helm

cert-manager

Certificate Flow

Installation

ClusterIssuer Configuration

DNS-01 Solver by Provider

Gateway Annotation

external-dns

How It Works

Configuration by Provider

TLS Requirements

Network Policies

Firewall Rules

DNS Architecture

Troubleshooting

Next Steps