Kubernetes-Native Service Discovery Migration Guide

Overview

This guide provides step-by-step instructions to enable Kubernetes-native service discovery in your existing InfraNotes API Gateway without disrupting current operations.

Migration Strategy

The gateway now automatically detects the best service discovery approach:

1. Kubernetes-native - When running in Kubernetes with NATS disabled
2. Standard - When NATS service discovery is enabled or not in Kubernetes
3. Environment Override - Via K8S_DISCOVERY_ENABLED=true

Quick Migration (Recommended)

Option 1: Environment Variable (Zero-Config)

Simply set an environment variable in your deployment:

# Update your deployment
kubectl set env deployment/infranotes-gateway K8S_DISCOVERY_ENABLED=true

# Verify the change
kubectl rollout status deployment/infranotes-gateway

Option 2: Configuration Update

Update your Helm values or ConfigMap:

# In your values.yaml or ConfigMap
env:
  K8S_DISCOVERY_ENABLED: "true"
  
# OR add to config.yaml
k8s_discovery:
  enabled: true
  strategy: "kubernetes-native"
  health_check_enabled: true
  load_balancing_strategy: "health_aware"

Verification Steps

1. Check Gateway Health

# Basic health check
curl http://your-gateway:8080/health

# Detailed health with service discovery info
curl http://your-gateway:8080/health/detailed

Expected response:

{
  "status": "healthy",
  "components": {
    "service_discovery": {
      "type": "kubernetes-native",
      "enabled": true,
      "status": "healthy",
      "namespace": "preprod-1",
      "strategy": "health_aware"
    }
  }
}

2. Verify Service Discovery

# Check service discovery endpoints
curl http://your-gateway:8080/service-discovery/health
curl http://your-gateway:8080/service-discovery/status
curl http://your-gateway:8080/service-discovery/routes

3. Test Route Resolution

# Test a specific route (URL encode the path)
curl "http://your-gateway:8080/service-discovery/route-resolution/api%2Fauth"

# Check discovered services
curl http://your-gateway:8080/service-discovery/services

Rollback Plan

If you need to rollback:

# Option 1: Remove environment variable
kubectl set env deployment/infranotes-gateway K8S_DISCOVERY_ENABLED-

# Option 2: Re-enable NATS (if previously configured)
kubectl set env deployment/infranotes-gateway SERVICE_DISCOVERY_ENABLED=true

# Verify rollback
kubectl rollout status deployment/infranotes-gateway

Configuration Options

Basic Configuration

k8s_discovery:
  enabled: true
  strategy: "kubernetes-native"
  health_check_enabled: true
  load_balancing_strategy: "health_aware"

Advanced Configuration

k8s_discovery:
  enabled: true
  strategy: "kubernetes-native"
  
  # Performance tuning
  route_cache_enabled: true
  route_cache_ttl: "30s"
  informer_resync_period: "30s"
  
  # Service filtering
  service_labels:
    app.kubernetes.io/part-of: "infranotes"
  exclude_namespaces:
    - "kube-system"
    - "kube-public"
  
  # Load balancing
  load_balancing_strategy: "health_aware"
  prefer_local_zone: true

RBAC Requirements

Ensure your gateway has the necessary permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: infranotes-gateway-discovery
rules:
- apiGroups: [""]
  resources: ["services"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["discovery.k8s.io"]
  resources: ["endpointslices"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: infranotes-gateway-discovery
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: infranotes-gateway-discovery
subjects:
- kind: ServiceAccount
  name: infranotes-gateway
  namespace: preprod-1

Monitoring and Troubleshooting

Key Metrics to Monitor

1. Service Discovery Health: /service-discovery/health
2. Route Resolution: /service-discovery/routes
3. Endpoint Health: /service-discovery/status

Common Issues

1. Permission Denied

# Check RBAC permissions
kubectl auth can-i list endpointslices --as=system:serviceaccount:preprod-1:infranotes-gateway
kubectl auth can-i list services --as=system:serviceaccount:preprod-1:infranotes-gateway

2. No Services Discovered

# Check EndpointSlices exist
kubectl get endpointslices -n preprod-1

# Check service discovery debug
curl http://your-gateway:8080/service-discovery/debug

3. Routes Not Resolving

# Check gateway logs
kubectl logs deployment/infranotes-gateway | grep -i "service discovery"

# Verify route configuration
curl http://your-gateway:8080/service-discovery/routes

Benefits After Migration

Performance Improvements

• Faster Route Resolution: <1ms with caching
• Real-time Updates: EndpointSlices-based
• Reduced Dependencies: No external NATS infrastructure

Enhanced Observability

• New Endpoints: 6 service discovery management endpoints
• Better Monitoring: Detailed metrics and health checks
• Debug Capability: Route resolution troubleshooting

2025 Standards Compliance

• Modern APIs: EndpointSlices instead of legacy Endpoints
• Cloud-Native: Platform-native service discovery
• Security: Minimal RBAC requirements

Support

Logs to Check

# Gateway startup logs
kubectl logs deployment/infranotes-gateway | grep -E "(Kubernetes-native|service discovery)"

# Service discovery specific logs
kubectl logs deployment/infranotes-gateway | grep -i "k8s.*discovery"

Health Checks

# Quick status check
curl -s http://your-gateway:8080/health/detailed | jq '.components.service_discovery'

# Full service discovery status
curl -s http://your-gateway:8080/service-discovery/status | jq '.'

The migration is designed to be zero-downtime and automatically detected. Your existing features (JWT auth, caching, metrics, etc.) remain fully intact while gaining the benefits of Kubernetes-native service discovery.