Netflix Zuul

Java-based API Gateway developed by Netflix. Provides dynamic routing, monitoring, resilience, and security features. Integration with Spring Cloud.

API GatewayJavaSpring CloudMicroservicesNetflix OSS

Server

Netflix Zuul

Overview

Netflix Zuul is a Java-based L7 application gateway developed by Netflix as part of their open-source software (OSS) portfolio, designed to provide dynamic routing, monitoring, resiliency, and security capabilities for microservices architectures. Serving as the entry point for requests to Netflix's backend services, Zuul acts as the "front door" for all requests from devices and websites to the backend of Netflix streaming application. Built on a powerful filter system that allows for flexible request and response processing, Zuul has become the de facto standard API Gateway for Java and Spring Boot environments, offering robust integration with the Spring Cloud ecosystem and Netflix's proven microservices patterns.

Details

Netflix Zuul 2025 edition continues to be a cornerstone of Java-based microservices architectures, particularly in Spring Boot and Spring Cloud environments. The platform evolved from Zuul 1 (blocking I/O) to Zuul 2 (non-blocking I/O using Netty), offering significant performance improvements for high-throughput scenarios. Zuul's filter-based architecture enables developers to implement custom logic for authentication, routing, monitoring, and error handling through PRE, ROUTE, POST, and ERROR filters. The gateway seamlessly integrates with other Netflix OSS components like Eureka (service discovery), Ribbon (load balancing), and Hystrix (circuit breaking), providing a comprehensive microservices toolkit that has been battle-tested at Netflix scale.

Key Features

Filter-Based Architecture: Flexible PRE, ROUTE, POST, and ERROR filter system
Spring Cloud Integration: Seamless integration with Spring Boot and Spring Cloud ecosystem
Dynamic Routing: Runtime routing configuration with service discovery support
Load Balancing: Integration with Ribbon for client-side load balancing
Circuit Breaking: Hystrix integration for resilience and fault tolerance
Asynchronous Processing: Zuul 2 provides non-blocking I/O for improved performance

Advantages and Disadvantages

Advantages

Mature and battle-tested solution with proven scalability at Netflix's massive scale
Excellent Spring Boot and Spring Cloud ecosystem integration with comprehensive documentation
Flexible filter architecture allowing custom business logic implementation and extensibility
Strong Java community support with extensive examples and best practices
Seamless integration with Netflix OSS stack providing complete microservices toolkit
Rich monitoring and metrics capabilities with built-in observability features

Disadvantages

Java platform dependency limiting deployment options to JVM-based environments
Higher resource consumption compared to lightweight alternatives written in Go or C++
Zuul 1 performance limitations with blocking I/O model requiring upgrade to Zuul 2
Complex configuration for advanced use cases requiring deep Spring Cloud knowledge
Netflix OSS maintenance concerns as Netflix shifts focus to other technologies
Steeper learning curve for teams unfamiliar with Java and Spring ecosystem

Reference Links

Code Examples

Spring Boot Application Setup

// Application.java - Main Spring Boot application
@SpringBootApplication
@EnableZuulProxy
@EnableEurekaClient
public class ApiGatewayApplication {
    
    public static void main(String[] args) {
        SpringApplication.run(ApiGatewayApplication.class, args);
    }
    
    @Bean
    public PreFilter preFilter() {
        return new PreFilter();
    }
    
    @Bean
    public PostFilter postFilter() {
        return new PostFilter();
    }
    
    @Bean
    public ErrorFilter errorFilter() {
        return new ErrorFilter();
    }
}

Basic Configuration

# application.properties
server.port=8080
spring.application.name=api-gateway

# Eureka client configuration
eureka.client.service-url.defaultZone=http://localhost:8761/eureka/
eureka.instance.prefer-ip-address=true

# Zuul routing configuration
zuul.routes.user-service.path=/users/**
zuul.routes.user-service.service-id=user-service
zuul.routes.user-service.strip-prefix=false

zuul.routes.order-service.path=/orders/**
zuul.routes.order-service.service-id=order-service

zuul.routes.product-service.path=/products/**
zuul.routes.product-service.url=http://product-service.example.com

# Ribbon configuration
ribbon.ReadTimeout=10000
ribbon.ConnectTimeout=5000

# Hystrix configuration
hystrix.command.default.execution.isolation.thread.timeoutInMilliseconds=10000

YAML Configuration Alternative

# application.yml
server:
  port: 8080

spring:
  application:
    name: api-gateway

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true

zuul:
  routes:
    user-service:
      path: /users/**
      service-id: user-service
      strip-prefix: false
    order-service:
      path: /orders/**
      service-id: order-service
    product-service:
      path: /products/**
      url: http://product-service.example.com
  host:
    socket-timeout-millis: 10000
    connect-timeout-millis: 5000
  
  # Ignore certain paths
  ignored-patterns:
    - /health/**
    - /actuator/**
  
  # Add prefix to all routes
  prefix: /api/v1
  
  # Strip prefix when forwarding to services
  strip-prefix: true

ribbon:
  ReadTimeout: 10000
  ConnectTimeout: 5000

hystrix:
  command:
    default:
      execution:
        isolation:
          thread:
            timeoutInMilliseconds: 10000

Custom Pre Filter Implementation

// PreFilter.java - Authentication and validation
@Component
public class PreFilter extends ZuulFilter {
    
    private static final Logger logger = LoggerFactory.getLogger(PreFilter.class);
    
    @Override
    public String filterType() {
        return "pre";
    }
    
    @Override
    public int filterOrder() {
        return 1;
    }
    
    @Override
    public boolean shouldFilter() {
        return true;
    }
    
    @Override
    public Object run() throws ZuulException {
        RequestContext ctx = RequestContext.getCurrentContext();
        HttpServletRequest request = ctx.getRequest();
        
        logger.info("Request Method: {}, URL: {}", 
                   request.getMethod(), request.getRequestURL().toString());
        
        // Authentication check
        String authToken = request.getHeader("Authorization");
        if (authToken == null || !isValidToken(authToken)) {
            logger.warn("Invalid or missing auth token");
            ctx.setSendZuulResponse(false);
            ctx.setResponseStatusCode(401);
            ctx.setResponseBody("{\"error\":\"Unauthorized\"}");
            return null;
        }
        
        // Add custom headers
        ctx.addZuulRequestHeader("X-User-ID", extractUserIdFromToken(authToken));
        ctx.addZuulRequestHeader("X-Gateway", "Zuul");
        
        // Rate limiting
        String clientId = request.getHeader("X-Client-ID");
        if (!checkRateLimit(clientId)) {
            logger.warn("Rate limit exceeded for client: {}", clientId);
            ctx.setSendZuulResponse(false);
            ctx.setResponseStatusCode(429);
            ctx.setResponseBody("{\"error\":\"Rate limit exceeded\"}");
            return null;
        }
        
        return null;
    }
    
    private boolean isValidToken(String token) {
        // Implement JWT validation logic
        try {
            // Validate JWT token
            String jwt = token.replace("Bearer ", "");
            // JWT validation logic here
            return true;
        } catch (Exception e) {
            return false;
        }
    }
    
    private String extractUserIdFromToken(String token) {
        // Extract user ID from JWT token
        return "user123"; // Simplified
    }
    
    private boolean checkRateLimit(String clientId) {
        // Implement rate limiting logic (Redis, in-memory, etc.)
        return true; // Simplified
    }
}

Custom Post Filter Implementation

// PostFilter.java - Response processing and monitoring
@Component
public class PostFilter extends ZuulFilter {
    
    private static final Logger logger = LoggerFactory.getLogger(PostFilter.class);
    
    @Override
    public String filterType() {
        return "post";
    }
    
    @Override
    public int filterOrder() {
        return 1;
    }
    
    @Override
    public boolean shouldFilter() {
        return true;
    }
    
    @Override
    public Object run() throws ZuulException {
        RequestContext ctx = RequestContext.getCurrentContext();
        HttpServletRequest request = ctx.getRequest();
        
        // Add security headers
        ctx.getResponse().addHeader("X-Content-Type-Options", "nosniff");
        ctx.getResponse().addHeader("X-Frame-Options", "DENY");
        ctx.getResponse().addHeader("X-XSS-Protection", "1; mode=block");
        
        // Add custom response headers
        ctx.getResponse().addHeader("X-Response-Time", 
                                   String.valueOf(System.currentTimeMillis()));
        ctx.getResponse().addHeader("X-Service-Version", "1.0");
        
        // Log response metrics
        int statusCode = ctx.getResponse().getStatus();
        long responseTime = (Long) ctx.get("startTime") != null ? 
            System.currentTimeMillis() - (Long) ctx.get("startTime") : 0;
        
        logger.info("Response Status: {}, Response Time: {}ms, Path: {}", 
                   statusCode, responseTime, request.getRequestURI());
        
        // Response transformation (if needed)
        if (shouldTransformResponse(request)) {
            transformResponse(ctx);
        }
        
        return null;
    }
    
    private boolean shouldTransformResponse(HttpServletRequest request) {
        return request.getRequestURI().contains("/api/v1/legacy");
    }
    
    private void transformResponse(RequestContext ctx) {
        try {
            InputStream responseDataStream = ctx.getResponseDataStream();
            String responseData = StreamUtils.copyToString(responseDataStream, 
                                                          StandardCharsets.UTF_8);
            
            // Transform response (e.g., format conversion)
            ObjectMapper mapper = new ObjectMapper();
            JsonNode jsonNode = mapper.readTree(responseData);
            
            // Add metadata
            ObjectNode response = mapper.createObjectNode();
            response.put("version", "v2");
            response.put("timestamp", Instant.now().toString());
            response.set("data", jsonNode);
            
            String transformedResponse = mapper.writeValueAsString(response);
            ctx.setResponseBody(transformedResponse);
            
        } catch (Exception e) {
            logger.error("Error transforming response", e);
        }
    }
}

Error Filter Implementation

// ErrorFilter.java - Error handling and logging
@Component
public class ErrorFilter extends ZuulFilter {
    
    private static final Logger logger = LoggerFactory.getLogger(ErrorFilter.class);
    
    @Override
    public String filterType() {
        return "error";
    }
    
    @Override
    public int filterOrder() {
        return 1;
    }
    
    @Override
    public boolean shouldFilter() {
        return true;
    }
    
    @Override
    public Object run() throws ZuulException {
        RequestContext ctx = RequestContext.getCurrentContext();
        Throwable throwable = ctx.getThrowable();
        
        logger.error("Error during request processing", throwable);
        
        // Create error response
        ErrorResponse errorResponse = new ErrorResponse();
        errorResponse.setTimestamp(Instant.now().toString());
        errorResponse.setPath(ctx.getRequest().getRequestURI());
        errorResponse.setError("Internal Server Error");
        errorResponse.setMessage("An error occurred while processing the request");
        errorResponse.setStatus(500);
        
        // Customize error response based on exception type
        if (throwable.getCause() instanceof ConnectTimeoutException) {
            errorResponse.setError("Service Unavailable");
            errorResponse.setMessage("Service is temporarily unavailable");
            errorResponse.setStatus(503);
            ctx.setResponseStatusCode(503);
        } else if (throwable.getCause() instanceof SocketTimeoutException) {
            errorResponse.setError("Gateway Timeout");
            errorResponse.setMessage("Request timeout");
            errorResponse.setStatus(504);
            ctx.setResponseStatusCode(504);
        }
        
        try {
            ObjectMapper mapper = new ObjectMapper();
            String errorJson = mapper.writeValueAsString(errorResponse);
            ctx.setResponseBody(errorJson);
            ctx.getResponse().setContentType("application/json");
        } catch (Exception e) {
            logger.error("Error creating error response", e);
        }
        
        return null;
    }
    
    public static class ErrorResponse {
        private String timestamp;
        private int status;
        private String error;
        private String message;
        private String path;
        
        // Getters and setters
        public String getTimestamp() { return timestamp; }
        public void setTimestamp(String timestamp) { this.timestamp = timestamp; }
        
        public int getStatus() { return status; }
        public void setStatus(int status) { this.status = status; }
        
        public String getError() { return error; }
        public void setError(String error) { this.error = error; }
        
        public String getMessage() { return message; }
        public void setMessage(String message) { this.message = message; }
        
        public String getPath() { return path; }
        public void setPath(String path) { this.path = path; }
    }
}

Advanced Configuration with Hystrix

// Configuration class for Hystrix and Ribbon
@Configuration
public class GatewayConfiguration {
    
    @Bean
    public HystrixCommandAspect hystrixAspect() {
        return new HystrixCommandAspect();
    }
    
    @Bean
    @LoadBalanced
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
    
    // Custom Hystrix configuration
    @Bean
    public HystrixCommandProperties.Setter hystrixProperties() {
        return HystrixCommandProperties.Setter()
            .withExecutionTimeoutInMilliseconds(5000)
            .withCircuitBreakerRequestVolumeThreshold(10)
            .withCircuitBreakerErrorThresholdPercentage(50)
            .withCircuitBreakerSleepWindowInMilliseconds(5000);
    }
    
    // Custom Ribbon configuration
    @Bean
    public IRule ribbonRule() {
        return new WeightedResponseTimeRule();
    }
}

Fallback Provider Implementation

// FallbackProvider.java - Circuit breaker fallback
@Component
public class UserServiceFallbackProvider implements FallbackProvider {
    
    @Override
    public String getRoute() {
        return "user-service";
    }
    
    @Override
    public ClientHttpResponse fallbackResponse(String route, Throwable cause) {
        return new ClientHttpResponse() {
            
            @Override
            public HttpStatus getStatusCode() throws IOException {
                return HttpStatus.SERVICE_UNAVAILABLE;
            }
            
            @Override
            public int getRawStatusCode() throws IOException {
                return 503;
            }
            
            @Override
            public String getStatusText() throws IOException {
                return "Service Unavailable";
            }
            
            @Override
            public void close() {}
            
            @Override
            public InputStream getBody() throws IOException {
                String fallbackResponse = "{" +
                    "\"error\": \"User service is temporarily unavailable\"," +
                    "\"message\": \"Please try again later\"," +
                    "\"timestamp\": \"" + Instant.now().toString() + "\"" +
                    "}";
                return new ByteArrayInputStream(fallbackResponse.getBytes());
            }
            
            @Override
            public HttpHeaders getHeaders() {
                HttpHeaders headers = new HttpHeaders();
                headers.setContentType(MediaType.APPLICATION_JSON);
                return headers;
            }
        };
    }
}

Docker and Production Deployment

# Dockerfile
FROM openjdk:11-jre-slim

VOLUME /tmp

COPY target/api-gateway-1.0.0.jar app.jar

EXPOSE 8080

ENV JAVA_OPTS=""

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -Djava.security.egd=file:/dev/./urandom -jar /app.jar"]

# docker-compose.yml
version: '3.8'
services:
  eureka-server:
    image: springcloud/eureka
    ports:
      - "8761:8761"
    environment:
      - EUREKA_CLIENT_REGISTER_WITH_EUREKA=false
      - EUREKA_CLIENT_FETCH_REGISTRY=false

  api-gateway:
    build: .
    ports:
      - "8080:8080"
    environment:
      - EUREKA_CLIENT_SERVICE_URL_DEFAULTZONE=http://eureka-server:8761/eureka/
      - SPRING_PROFILES_ACTIVE=docker
    depends_on:
      - eureka-server
    
  user-service:
    image: user-service:latest
    environment:
      - EUREKA_CLIENT_SERVICE_URL_DEFAULTZONE=http://eureka-server:8761/eureka/
    depends_on:
      - eureka-server