google-site-verification: google61fe8ba583a51912.html
MACRO NEPAL
Modern Microservices: Implementing Kuma Service Mesh with Java Applications
awiskar acharya
November 20, 2025
9:26 am

Article

Kuma is an open-source, universal service mesh that runs on both Kubernetes and VMs. Built by Kong, Kuma provides a robust control plane that works with Envoy proxy to deliver security, reliability, and observability for microservices. For Java applications, Kuma offers seamless integration with minimal code changes while providing enterprise-grade service mesh capabilities.

In this guide, we'll explore how to integrate Java microservices with Kuma service mesh to achieve traffic management, security, observability, and resilience.

Why Kuma Service Mesh for Java?

  • Universal Deployment: Works across Kubernetes, VMs, and containers
  • Envoy-Powered: Leverages battle-tested Envoy proxy
  • Multi-Zone Support: Native multi-zone and multi-cloud capabilities
  • Zero-Trust Security: Built-in mTLS and service-to-service authentication
  • Comprehensive Observability: Metrics, tracing, and logging out of the box
  • Developer-Friendly: Easy to adopt with minimal application changes

Part 1: Kuma Architecture Overview

1.1 Kuma Components

Java Application → Kuma Data Plane (Envoy) → Kuma Control Plane → Management APIs ↓ ↓ ↓ ↓ Business Logic Traffic Routing Policies Kubernetes Spring Boot Security Configuration Docker Micronaut Observability Service Discovery VM Quarkus

1.2 Project Structure

java-kuma-mesh/ ├── user-service/ │ ├── src/main/java/com/example/user/ │ ├── Dockerfile │ └── kuma/ │ └── mesh.yaml ├── order-service/ │ ├── src/main/java/com/example/order/ │ └── Dockerfile ├── api-gateway/ │ ├── src/main/java/com/example/gateway/ │ └── Dockerfile ├── kuma-config/ │ ├── mesh.yaml │ ├── traffic-route.yaml │ └── circuit-breaker.yaml └── kubernetes/ ├── kuma-install.yaml └── services/ ├── user-service.yaml └── order-service.yaml

Part 2: Dependencies and Setup

2.1 Maven Dependencies

<!-- pom.xml --> <properties> <spring-boot.version>3.1.0</spring-boot.version> <micrometer.version>1.11.5</micrometer.version> <resilience4j.version>2.1.0</resilience4j.version> </properties> <dependencies> <!-- Spring Boot --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> <version>${spring-boot.version}</version> </dependency> <!-- Observability --> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> <version>${micrometer.version}</version> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-tracing-bridge-brave</artifactId> <version>${micrometer.version}</version> </dependency> <!-- Resilience --> <dependency> <groupId>io.github.resilience4j</groupId> <artifactId>resilience4j-spring-boot3</artifactId> <version>${resilience4j.version}</version> </dependency> <dependency> <groupId>io.github.resilience4j</groupId> <artifactId>resilience4j-circuitbreaker</artifactId> <version>${resilience4j.version}</version> </dependency> <!-- OpenTelemetry --> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.31.0</version> </dependency> <!-- HTTP Client --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> <version>${spring-boot.version}</version> </dependency> </dependencies>

Part 3: Java Service Implementation

3.1 User Service with Kuma Integration

// File: user-service/src/main/java/com/example/user/UserServiceApplication.java package com.example.user; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.context.properties.EnableConfigurationProperties; @SpringBootApplication @EnableConfigurationProperties(UserServiceProperties.class) public class UserServiceApplication { public static void main(String[] args) { SpringApplication.run(UserServiceApplication.class, args); } } // File: user-service/src/main/java/com/example/user/UserServiceProperties.java package com.example.user; import org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties(prefix = "user.service") public record UserServiceProperties( String name, String version, String environment, MeshProperties mesh ) { public record MeshProperties( boolean enabled, String zone, String serviceAccount, int proxyPort ) {} } // File: user-service/src/main/java/com/example/user/UserController.java package com.example.user; import io.micrometer.core.annotation.Timed; import io.micrometer.observation.annotation.Observed; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import java.util.List; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; @RestController @RequestMapping("/api/v1/users") public class UserController { private static final Logger logger = LoggerFactory.getLogger(UserController.class); private final Map<String, User> users = new ConcurrentHashMap<>(); private final UserServiceProperties properties; public UserController(UserServiceProperties properties) { this.properties = properties; // Initialize with sample data users.put("1", new User("1", "[email protected]", "John Doe", "ACTIVE")); users.put("2", new User("2", "[email protected]", "Jane Smith", "ACTIVE")); } @GetMapping @Timed(value = "user.service.get.all", description = "Get all users") @Observed(name = "user.get.all", contextualName = "user-service.get-all-users") public ResponseEntity<List<User>> getAllUsers() { logger.info("Fetching all users - Service: {}, Zone: {}", properties.name(), properties.mesh().zone()); return ResponseEntity.ok(List.copyOf(users.values())); } @GetMapping("/{userId}") @Timed(value = "user.service.get.by.id", description = "Get user by ID") public ResponseEntity<User> getUserById(@PathVariable String userId) { logger.info("Fetching user by ID: {} - Service: {}", userId, properties.name()); User user = users.get(userId); if (user == null) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok(user); } @PostMapping @Timed(value = "user.service.create", description = "Create user") public ResponseEntity<User> createUser(@RequestBody CreateUserRequest request) { logger.info("Creating user: {} - Service: {}", request.email(), properties.name()); String userId = String.valueOf(users.size() + 1); User user = new User(userId, request.email(), request.name(), "ACTIVE"); users.put(userId, user); return ResponseEntity.ok(user); } @GetMapping("/health") public ResponseEntity<Map<String, String>> health() { return ResponseEntity.ok(Map.of( "status", "healthy", "service", properties.name(), "version", properties.version(), "zone", properties.mesh().zone(), "meshEnabled", String.valueOf(properties.mesh().enabled()) )); } @GetMapping("/metrics/info") public ResponseEntity<Map<String, Object>> metricsInfo() { return ResponseEntity.ok(Map.of( "service", properties.name(), "totalUsers", users.size(), "mesh", Map.of( "enabled", properties.mesh().enabled(), "zone", properties.mesh().zone(), "proxyPort", properties.mesh().proxyPort() ) )); } } // File: user-service/src/main/java/com/example/user/User.java package com.example.user; public record User( String id, String email, String name, String status ) {} // File: user-service/src/main/java/com/example/user/CreateUserRequest.java package com.example.user; public record CreateUserRequest( String email, String name ) {}

3.2 Order Service with Resilient Communication

// File: order-service/src/main/java/com/example/order/OrderServiceApplication.java package com.example.order; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; @SpringBootApplication @EnableConfigurationProperties(OrderServiceProperties.class) public class OrderServiceApplication { public static void main(String[] args) { SpringApplication.run(OrderServiceApplication.class, args); } } // File: order-service/src/main/java/com/example/order/OrderController.java package com.example.order; import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker; import io.github.resilience4j.retry.annotation.Retry; import io.github.resilience4j.timelimiter.annotation.TimeLimiter; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import org.springframework.web.reactive.function.client.WebClient; import reactor.core.publisher.Mono; import java.util.List; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; @RestController @RequestMapping("/api/v1/orders") public class OrderController { private static final Logger logger = LoggerFactory.getLogger(OrderController.class); private final Map<String, Order> orders = new ConcurrentHashMap<>(); private final OrderServiceProperties properties; private final WebClient webClient; public OrderController(OrderServiceProperties properties, WebClient.Builder webClientBuilder) { this.properties = properties; this.webClient = webClientBuilder.baseUrl("http://user-service:8080").build(); } @PostMapping @CircuitBreaker(name = "orderService", fallbackMethod = "createOrderFallback") @Retry(name = "orderService") @TimeLimiter(name = "orderService") public Mono<ResponseEntity<Order>> createOrder(@RequestBody CreateOrderRequest request) { logger.info("Creating order for user: {} - Service: {}", request.userId(), properties.name()); // Validate user exists via user service (through Kuma mesh) return validateUser(request.userId()) .flatMap(userValid -> { if (!userValid) { return Mono.just(ResponseEntity.badRequest() .body(new Order("invalid", "USER_NOT_FOUND", null, "FAILED"))); } String orderId = String.valueOf(orders.size() + 1); Order order = new Order(orderId, request.userId(), request.items(), "CREATED"); orders.put(orderId, order); logger.info("Order created successfully: {} - Service: {}", orderId, properties.name()); return Mono.just(ResponseEntity.ok(order)); }); } @GetMapping("/{orderId}") public ResponseEntity<Order> getOrder(@PathVariable String orderId) { logger.info("Fetching order: {} - Service: {}", orderId, properties.name()); Order order = orders.get(orderId); if (order == null) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok(order); } @GetMapping public ResponseEntity<List<Order>> getAllOrders() { logger.info("Fetching all orders - Service: {}", properties.name()); return ResponseEntity.ok(List.copyOf(orders.values())); } @GetMapping("/health") public ResponseEntity<Map<String, String>> health() { return ResponseEntity.ok(Map.of( "status", "healthy", "service", properties.name(), "version", properties.version(), "zone", properties.mesh().zone() )); } private Mono<Boolean> validateUser(String userId) { return webClient.get() .uri("/api/v1/users/{userId}", userId) .retrieve() .toBodilessEntity() .map(response -> response.getStatusCode().is2xxSuccessful()) .doOnError(error -> logger.warn("User validation failed for {}: {}", userId, error.getMessage())) .onErrorReturn(false); } // Fallback method for circuit breaker public Mono<ResponseEntity<Order>> createOrderFallback(CreateOrderRequest request, Exception ex) { logger.warn("Order creation fallback triggered for user: {}, error: {}", request.userId(), ex.getMessage()); Order fallbackOrder = new Order("fallback", request.userId(), request.items(), "PENDING_VALIDATION"); return Mono.just(ResponseEntity.accepted().body(fallbackOrder)); } } // File: order-service/src/main/java/com/example/order/Order.java package com.example.order; import java.util.List; public record Order( String id, String userId, List<OrderItem> items, String status ) {} // File: order-service/src/main/java/com/example/order/CreateOrderRequest.java package com.example.order; import java.util.List; public record CreateOrderRequest( String userId, List<OrderItem> items ) {} // File: order-service/src/main/java/com/example/order/OrderItem.java package com.example.order; public record OrderItem( String productId, int quantity, double price ) {} // File: order-service/src/main/java/com/example/order/OrderServiceProperties.java package com.example.order; import org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties(prefix = "order.service") public record OrderServiceProperties( String name, String version, String environment, MeshProperties mesh ) { public record MeshProperties( boolean enabled, String zone, String serviceAccount, int proxyPort ) {} }

Part 4: Kuma Configuration

4.1 Mesh Configuration

# kuma-config/mesh.yaml apiVersion: kuma.io/v1alpha1 kind: Mesh metadata: name: default spec: mtls: backends: - name: ca-1 type: builtin enabledBackend: ca-1 logging: backends: - name: file-backend type: file format: '{"start_time": "%START_TIME%", "method": "%REQ(:METHOD)%", "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%", "protocol": "%PROTOCOL%", "response_code": "%RESPONSE_CODE%", "response_flags": "%RESPONSE_FLAGS%", "bytes_received": "%BYTES_RECEIVED%", "bytes_sent": "%BYTES_SENT%", "duration": "%DURATION%", "upstream_service": "%UPSTREAM_CLUSTER%", "upstream_host": "%UPSTREAM_HOST%", "x_forwarded_for": "%REQ(X-FORWARDED-FOR)%", "user_agent": "%REQ(USER-AGENT)%", "request_id": "%REQ(X-REQUEST-ID)%", "authority": "%REQ(:AUTHORITY)%", "upstream_local_address": "%UPSTREAM_LOCAL_ADDRESS%"}' file: path: /tmp/access.log tracing: backends: - name: jaeger-collector type: jaeger sampling: 100.0 conf: collectorEndpoint: http://jaeger-collector:14268/api/traces metrics: enabledBackend: prometheus-1 backends: - name: prometheus-1 type: prometheus conf: port: 5670 path: /metrics tags: kuma.io/service: dataplane_metrics

4.2 Traffic Route Configuration

# kuma-config/traffic-route.yaml apiVersion: kuma.io/v1alpha1 kind: TrafficRoute mesh: default metadata: name: route-all-traffic spec: sources: - match: kuma.io/service: '*' destinations: - match: kuma.io/service: '*' conf: http: - match: path: prefix: / destination: kuma.io/service: '*' --- apiVersion: kuma.io/v1alpha1 kind: TrafficRoute mesh: default metadata: name: canary-user-service spec: sources: - match: kuma.io/service: 'order-service' destinations: - match: kuma.io/service: 'user-service' conf: http: - match: headers: x-canary: 'true' split: - weight: 10 destination: kuma.io/service: 'user-service-v2' - weight: 90 destination: kuma.io/service: 'user-service' - match: path: prefix: '/api/v1/users' split: - weight: 100 destination: kuma.io/service: 'user-service'

4.3 Circuit Breaker Configuration

# kuma-config/circuit-breaker.yaml apiVersion: kuma.io/v1alpha1 kind: CircuitBreaker mesh: default metadata: name: order-service-cb spec: sources: - match: kuma.io/service: 'order-service' destinations: - match: kuma.io/service: 'user-service' conf: interval: 30s baseEjectionTime: 30s maxEjectionPercent: 50 thresholds: maxConnections: 100 maxRequests: 100 maxRetries: 3 maxPendingRequests: 50 detectors: totalErrors: consecutive: 5 gatewayErrors: consecutive: 10 localOriginErrors: consecutive: 7

4.4 Retry Policy

# kuma-config/retry-policy.yaml apiVersion: kuma.io/v1alpha1 kind: RetryPolicy mesh: default metadata: name: order-service-retries spec: sources: - match: kuma.io/service: 'order-service' destinations: - match: kuma.io/service: 'user-service' conf: http: numRetries: 3 perTryTimeout: 2s backOff: baseInterval: 0.1s maxInterval: 3s retryOn: - gateway-error - connect-failure - refused-stream - retriable-4xx - reset

4.5 Fault Injection for Testing

# kuma-config/fault-injection.yaml apiVersion: kuma.io/v1alpha1 kind: FaultInjection mesh: default metadata: name: user-service-delay spec: sources: - match: kuma.io/service: 'test-client' destinations: - match: kuma.io/service: 'user-service' conf: delay: percentage: 50 value: 5s abort: percentage: 10 httpStatus: 503

Part 5: Kubernetes Deployment

5.1 Kuma Installation

# kubernetes/kuma-install.yaml apiVersion: v1 kind: Namespace metadata: name: kuma-system --- apiVersion: apps/v1 kind: Deployment metadata: namespace: kuma-system name: kuma-control-plane labels: app: kuma-control-plane spec: replicas: 1 selector: matchLabels: app: kuma-control-plane template: metadata: labels: app: kuma-control-plane annotations: kuma.io/mesh: default spec: containers: - name: kuma-cp image: kong-docker-kuma-docker.bintray.io/kuma-cp:2.6.0 ports: - containerPort: 5681 - containerPort: 5682 env: - name: KUMA_MULTI_ZONE_GLOBAL_KDS_GRPC_PORT value: "5685" resources: requests: memory: "256Mi" cpu: "100m" limits: memory: "512Mi" cpu: "500m" --- apiVersion: v1 kind: Service metadata: namespace: kuma-system name: kuma-control-plane labels: app: kuma-control-plane spec: ports: - port: 5681 targetPort: 5681 name: grpc - port: 5682 targetPort: 5682 name: http selector: app: kuma-control-plane

5.2 User Service Deployment

# kubernetes/services/user-service.yaml apiVersion: apps/v1 kind: Deployment metadata: name: user-service namespace: default labels: app: user-service version: v1 spec: replicas: 3 selector: matchLabels: app: user-service version: v1 template: metadata: labels: app: user-service version: v1 annotations: kuma.io/mesh: default kuma.io/sidecar-injection: "enabled" prometheus.io/scrape: "true" prometheus.io/port: "5670" prometheus.io/path: "/metrics" spec: serviceAccountName: user-service containers: - name: user-service image: my-registry/user-service:1.0.0 ports: - containerPort: 8080 env: - name: SPRING_APPLICATION_NAME value: "user-service" - name: USER_SERVICE_NAME value: "user-service" - name: USER_SERVICE_VERSION value: "1.0.0" - name: USER_SERVICE_ENVIRONMENT value: "production" - name: USER_SERVICE_MESH_ENABLED value: "true" - name: USER_SERVICE_MESH_ZONE value: "us-west-2" resources: requests: memory: "256Mi" cpu: "100m" limits: memory: "512Mi" cpu: "300m" livenessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 5 periodSeconds: 5 --- apiVersion: v1 kind: Service metadata: name: user-service namespace: default labels: app: user-service spec: ports: - port: 80 targetPort: 8080 protocol: TCP name: http selector: app: user-service type: ClusterIP --- apiVersion: v1 kind: ServiceAccount metadata: name: user-service namespace: default

5.3 Order Service Deployment

# kubernetes/services/order-service.yaml apiVersion: apps/v1 kind: Deployment metadata: name: order-service namespace: default labels: app: order-service version: v1 spec: replicas: 2 selector: matchLabels: app: order-service version: v1 template: metadata: labels: app: order-service version: v1 annotations: kuma.io/mesh: default kuma.io/sidecar-injection: "enabled" prometheus.io/scrape: "true" prometheus.io/port: "5670" spec: serviceAccountName: order-service containers: - name: order-service image: my-registry/order-service:1.0.0 ports: - containerPort: 8080 env: - name: SPRING_APPLICATION_NAME value: "order-service" - name: ORDER_SERVICE_NAME value: "order-service" - name: ORDER_SERVICE_VERSION value: "1.0.0" - name: ORDER_SERVICE_ENVIRONMENT value: "production" - name: ORDER_SERVICE_MESH_ENABLED value: "true" - name: ORDER_SERVICE_MESH_ZONE value: "us-west-2" resources: requests: memory: "256Mi" cpu: "100m" limits: memory: "512Mi" cpu: "300m" livenessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 5 periodSeconds: 5 --- apiVersion: v1 kind: Service metadata: name: order-service namespace: default labels: app: order-service spec: ports: - port: 80 targetPort: 8080 protocol: TCP name: http selector: app: order-service type: ClusterIP --- apiVersion: v1 kind: ServiceAccount metadata: name: order-service namespace: default

Part 6: Application Configuration

6.1 User Service Configuration

# user-service/src/main/resources/application.yaml spring: application: name: user-service server: port: 8080 user: service: name: user-service version: 1.0.0 environment: ${ENVIRONMENT:development} mesh: enabled: ${MESH_ENABLED:true} zone: ${MESH_ZONE:default} service-account: user-service proxy-port: 5670 management: endpoints: web: exposure: include: health,info,metrics,prometheus endpoint: health: show-details: always metrics: enabled: true metrics: export: prometheus: enabled: true tags: application: ${spring.application.name} zone: ${user.service.mesh.zone} environment: ${user.service.environment} logging: level: com.example.user: DEBUG org.springframework.web: INFO io.kuma: DEBUG resilience4j: circuitbreaker: instances: userService: register-health-indicator: true sliding-window-size: 10 minimum-number-of-calls: 5 permitted-number-of-calls-in-half-open-state: 3 automatic-transition-from-open-to-half-open-enabled: true wait-duration-in-open-state: 10s failure-rate-threshold: 50 event-consumer-buffer-size: 10 retry: instances: userService: max-attempts: 3 wait-duration: 2s

6.2 Order Service Configuration

# order-service/src/main/resources/application.yaml spring: application: name: order-service server: port: 8080 order: service: name: order-service version: 1.0.0 environment: ${ENVIRONMENT:development} mesh: enabled: ${MESH_ENABLED:true} zone: ${MESH_ZONE:default} service-account: order-service proxy-port: 5670 management: endpoints: web: exposure: include: health,info,metrics,prometheus endpoint: health: show-details: always metrics: enabled: true metrics: export: prometheus: enabled: true tags: application: ${spring.application.name} zone: ${order.service.mesh.zone} environment: ${order.service.environment} logging: level: com.example.order: DEBUG org.springframework.web: INFO io.kuma: DEBUG resilience4j: circuitbreaker: instances: orderService: register-health-indicator: true sliding-window-size: 10 minimum-number-of-calls: 5 permitted-number-of-calls-in-half-open-state: 3 automatic-transition-from-open-to-half-open-enabled: true wait-duration-in-open-state: 10s failure-rate-threshold: 50 retry: instances: orderService: max-attempts: 3 wait-duration: 1s webclient: timeout: connect: 5s read: 10s write: 10s

Part 7: Observability and Monitoring

7.1 Custom Metrics and Health Checks

// File: user-service/src/main/java/com/example/user/UserServiceMetrics.java package com.example.user; import io.micrometer.core.instrument.Counter; import io.micrometer.core.instrument.MeterRegistry; import io.micrometer.core.instrument.Timer; import org.springframework.stereotype.Component; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.TimeUnit; @Component public class UserServiceMetrics { private final MeterRegistry meterRegistry; private final Counter userCreationCounter; private final Counter userQueryCounter; private final Timer userQueryTimer; private final ConcurrentHashMap<String, Counter> errorCounters; public UserServiceMetrics(MeterRegistry meterRegistry) { this.meterRegistry = meterRegistry; this.errorCounters = new ConcurrentHashMap<>(); this.userCreationCounter = Counter.builder("user.service.creation.total") .description("Total number of user creations") .tag("service", "user-service") .register(meterRegistry); this.userQueryCounter = Counter.builder("user.service.query.total") .description("Total number of user queries") .tag("service", "user-service") .register(meterRegistry); this.userQueryTimer = Timer.builder("user.service.query.duration") .description("Time taken for user queries") .tag("service", "user-service") .register(meterRegistry); } public void recordUserCreation() { userCreationCounter.increment(); } public void recordUserQuery() { userQueryCounter.increment(); } public Timer.Sample startQueryTimer() { return Timer.start(meterRegistry); } public void stopQueryTimer(Timer.Sample sample) { sample.stop(userQueryTimer); } public void recordError(String errorType) { Counter errorCounter = errorCounters.computeIfAbsent(errorType, key -> Counter.builder("user.service.errors.total") .description("Total number of errors by type") .tag("service", "user-service") .tag("error_type", errorType) .register(meterRegistry)); errorCounter.increment(); } public void recordMeshRequest(String destination, String status) { Counter.builder("user.service.mesh.requests.total") .description("Requests through service mesh") .tag("service", "user-service") .tag("destination", destination) .tag("status", status) .register(meterRegistry) .increment(); } }

7.2 Enhanced Health Indicator

// File: user-service/src/main/java/com/example/user/UserServiceHealthIndicator.java package com.example.user; import org.springframework.boot.actuate.health.Health; import org.springframework.boot.actuate.health.HealthIndicator; import org.springframework.stereotype.Component; import java.net.InetAddress; import java.util.HashMap; import java.util.Map; @Component public class UserServiceHealthIndicator implements HealthIndicator { private final UserServiceProperties properties; public UserServiceHealthIndicator(UserServiceProperties properties) { this.properties = properties; } @Override public Health health() { try { Map<String, Object> details = new HashMap<>(); details.put("service", properties.name()); details.put("version", properties.version()); details.put("environment", properties.environment()); details.put("meshEnabled", properties.mesh().enabled()); details.put("meshZone", properties.mesh().zone()); details.put("hostname", InetAddress.getLocalHost().getHostName()); details.put("timestamp", System.currentTimeMillis()); // Add mesh-specific health checks if (properties.mesh().enabled()) { details.put("meshStatus", "connected"); details.put("proxyPort", properties.mesh().proxyPort()); } return Health.up() .withDetails(details) .build(); } catch (Exception e) { return Health.down() .withDetail("error", e.getMessage()) .build(); } } }

Part 8: Testing with Kuma

8.1 Integration Tests

// File: order-service/src/test/java/com/example/order/OrderServiceIntegrationTest.java package com.example.order; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.web.client.TestRestTemplate; import org.springframework.boot.test.web.server.LocalServerPort; import org.springframework.http.ResponseEntity; import org.springframework.test.context.ActiveProfiles; import java.util.List; import static org.junit.jupiter.api.Assertions.*; @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @ActiveProfiles("test") class OrderServiceIntegrationTest { @LocalServerPort private int port; @Autowired private TestRestTemplate restTemplate; @Test void shouldCreateOrderThroughMesh() { // Given String baseUrl = "http://localhost:" + port; CreateOrderRequest request = new CreateOrderRequest( "1", List.of(new OrderItem("product-1", 2, 29.99)) ); // When ResponseEntity<Order> response = restTemplate.postForEntity( baseUrl + "/api/v1/orders", request, Order.class); // Then assertTrue(response.getStatusCode().is2xxSuccessful()); assertNotNull(response.getBody()); assertEquals("1", response.getBody().userId()); assertNotNull(response.getBody().id()); } @Test void shouldReturnHealthStatusWithMeshInfo() { // Given String baseUrl = "http://localhost:" + port; // When ResponseEntity<String> response = restTemplate.getForEntity( baseUrl + "/api/v1/orders/health", String.class); // Then assertTrue(response.getStatusCode().is2xxSuccessful()); assertTrue(response.getBody().contains("healthy")); assertTrue(response.getBody().contains("order-service")); } }

8.2 Resilience Testing

// File: order-service/src/test/java/com/example/order/OrderServiceResilienceTest.java package com.example.order; import io.github.resilience4j.circuitbreaker.CircuitBreaker; import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.context.ActiveProfiles; import static org.junit.jupiter.api.Assertions.*; @SpringBootTest @ActiveProfiles("test") class OrderServiceResilienceTest { @Autowired private CircuitBreakerRegistry circuitBreakerRegistry; @Test void shouldConfigureCircuitBreaker() { // When CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker("orderService"); // Then assertNotNull(circuitBreaker); assertEquals("orderService", circuitBreaker.getName()); assertEquals(CircuitBreaker.State.CLOSED, circuitBreaker.getState()); } }

Best Practices for Kuma with Java

  1. Gradual Adoption: Start with observability, then add security and traffic management
  2. Proper Tagging: Use consistent tags for services across the mesh
  3. Health Checks: Implement comprehensive health checks for both application and mesh
  4. Circuit Breaking: Combine application-level and mesh-level circuit breaking
  5. Observability: Leverage Kuma's built-in metrics, tracing, and logging
  6. Security: Enable mTLS for service-to-service communication
  7. Testing: Test both with and without mesh in your CI/CD pipeline
  8. Monitoring: Set up alerts for mesh-level and application-level issues

Conclusion

Integrating Kuma Service Mesh with Java applications provides a powerful foundation for building resilient, observable, and secure microservices architectures. By leveraging Kuma's capabilities alongside Java frameworks like Spring Boot, you can:

  • Automate traffic management with sophisticated routing and load balancing
  • Implement zero-trust security with automatic mTLS and service identity
  • Gain comprehensive observability with built-in metrics, tracing, and logging
  • Enhance resilience with circuit breaking, retries, and fault injection
  • Simplify operations with declarative configuration and multi-zone support

The patterns and examples in this guide demonstrate how to effectively integrate Java microservices with Kuma service mesh, creating a robust platform for modern cloud-native applications that can scale across multiple environments and deployment scenarios.

x

Article

Kuma is an open-source, universal service mesh that runs on both Kubernetes and VMs. Built by Kong, Kuma provides a robust control plane that works with Envoy proxy to deliver security, reliability, and observability for microservices. For Java applications, Kuma offers seamless integration with minimal code changes while providing enterprise-grade service mesh capabilities.

In this guide, we'll explore how to integrate Java microservices with Kuma service mesh to achieve traffic management, security, observability, and resilience.

Why Kuma Service Mesh for Java?

  • Universal Deployment: Works across Kubernetes, VMs, and containers
  • Envoy-Powered: Leverages battle-tested Envoy proxy
  • Multi-Zone Support: Native multi-zone and multi-cloud capabilities
  • Zero-Trust Security: Built-in mTLS and service-to-service authentication
  • Comprehensive Observability: Metrics, tracing, and logging out of the box
  • Developer-Friendly: Easy to adopt with minimal application changes

Part 1: Kuma Architecture Overview

1.1 Kuma Components

Java Application → Kuma Data Plane (Envoy) → Kuma Control Plane → Management APIs ↓ ↓ ↓ ↓ Business Logic Traffic Routing Policies Kubernetes Spring Boot Security Configuration Docker Micronaut Observability Service Discovery VM Quarkus

1.2 Project Structure

java-kuma-mesh/ ├── user-service/ │ ├── src/main/java/com/example/user/ │ ├── Dockerfile │ └── kuma/ │ └── mesh.yaml ├── order-service/ │ ├── src/main/java/com/example/order/ │ └── Dockerfile ├── api-gateway/ │ ├── src/main/java/com/example/gateway/ │ └── Dockerfile ├── kuma-config/ │ ├── mesh.yaml │ ├── traffic-route.yaml │ └── circuit-breaker.yaml └── kubernetes/ ├── kuma-install.yaml └── services/ ├── user-service.yaml └── order-service.yaml

Part 2: Dependencies and Setup

2.1 Maven Dependencies

<!-- pom.xml --> <properties> <spring-boot.version>3.1.0</spring-boot.version> <micrometer.version>1.11.5</micrometer.version> <resilience4j.version>2.1.0</resilience4j.version> </properties> <dependencies> <!-- Spring Boot --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> <version>${spring-boot.version}</version> </dependency> <!-- Observability --> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> <version>${micrometer.version}</version> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-tracing-bridge-brave</artifactId> <version>${micrometer.version}</version> </dependency> <!-- Resilience --> <dependency> <groupId>io.github.resilience4j</groupId> <artifactId>resilience4j-spring-boot3</artifactId> <version>${resilience4j.version}</version> </dependency> <dependency> <groupId>io.github.resilience4j</groupId> <artifactId>resilience4j-circuitbreaker</artifactId> <version>${resilience4j.version}</version> </dependency> <!-- OpenTelemetry --> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.31.0</version> </dependency> <!-- HTTP Client --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> <version>${spring-boot.version}</version> </dependency> </dependencies>

Part 3: Java Service Implementation

3.1 User Service with Kuma Integration

// File: user-service/src/main/java/com/example/user/UserServiceApplication.java package com.example.user; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.context.properties.EnableConfigurationProperties; @SpringBootApplication @EnableConfigurationProperties(UserServiceProperties.class) public class UserServiceApplication { public static void main(String[] args) { SpringApplication.run(UserServiceApplication.class, args); } } // File: user-service/src/main/java/com/example/user/UserServiceProperties.java package com.example.user; import org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties(prefix = "user.service") public record UserServiceProperties( String name, String version, String environment, MeshProperties mesh ) { public record MeshProperties( boolean enabled, String zone, String serviceAccount, int proxyPort ) {} } // File: user-service/src/main/java/com/example/user/UserController.java package com.example.user; import io.micrometer.core.annotation.Timed; import io.micrometer.observation.annotation.Observed; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import java.util.List; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; @RestController @RequestMapping("/api/v1/users") public class UserController { private static final Logger logger = LoggerFactory.getLogger(UserController.class); private final Map<String, User> users = new ConcurrentHashMap<>(); private final UserServiceProperties properties; public UserController(UserServiceProperties properties) { this.properties = properties; // Initialize with sample data users.put("1", new User("1", "[email protected]", "John Doe", "ACTIVE")); users.put("2", new User("2", "[email protected]", "Jane Smith", "ACTIVE")); } @GetMapping @Timed(value = "user.service.get.all", description = "Get all users") @Observed(name = "user.get.all", contextualName = "user-service.get-all-users") public ResponseEntity<List<User>> getAllUsers() { logger.info("Fetching all users - Service: {}, Zone: {}", properties.name(), properties.mesh().zone()); return ResponseEntity.ok(List.copyOf(users.values())); } @GetMapping("/{userId}") @Timed(value = "user.service.get.by.id", description = "Get user by ID") public ResponseEntity<User> getUserById(@PathVariable String userId) { logger.info("Fetching user by ID: {} - Service: {}", userId, properties.name()); User user = users.get(userId); if (user == null) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok(user); } @PostMapping @Timed(value = "user.service.create", description = "Create user") public ResponseEntity<User> createUser(@RequestBody CreateUserRequest request) { logger.info("Creating user: {} - Service: {}", request.email(), properties.name()); String userId = String.valueOf(users.size() + 1); User user = new User(userId, request.email(), request.name(), "ACTIVE"); users.put(userId, user); return ResponseEntity.ok(user); } @GetMapping("/health") public ResponseEntity<Map<String, String>> health() { return ResponseEntity.ok(Map.of( "status", "healthy", "service", properties.name(), "version", properties.version(), "zone", properties.mesh().zone(), "meshEnabled", String.valueOf(properties.mesh().enabled()) )); } @GetMapping("/metrics/info") public ResponseEntity<Map<String, Object>> metricsInfo() { return ResponseEntity.ok(Map.of( "service", properties.name(), "totalUsers", users.size(), "mesh", Map.of( "enabled", properties.mesh().enabled(), "zone", properties.mesh().zone(), "proxyPort", properties.mesh().proxyPort() ) )); } } // File: user-service/src/main/java/com/example/user/User.java package com.example.user; public record User( String id, String email, String name, String status ) {} // File: user-service/src/main/java/com/example/user/CreateUserRequest.java package com.example.user; public record CreateUserRequest( String email, String name ) {}

3.2 Order Service with Resilient Communication

// File: order-service/src/main/java/com/example/order/OrderServiceApplication.java package com.example.order; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; @SpringBootApplication @EnableConfigurationProperties(OrderServiceProperties.class) public class OrderServiceApplication { public static void main(String[] args) { SpringApplication.run(OrderServiceApplication.class, args); } } // File: order-service/src/main/java/com/example/order/OrderController.java package com.example.order; import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker; import io.github.resilience4j.retry.annotation.Retry; import io.github.resilience4j.timelimiter.annotation.TimeLimiter; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import org.springframework.web.reactive.function.client.WebClient; import reactor.core.publisher.Mono; import java.util.List; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; @RestController @RequestMapping("/api/v1/orders") public class OrderController { private static final Logger logger = LoggerFactory.getLogger(OrderController.class); private final Map<String, Order> orders = new ConcurrentHashMap<>(); private final OrderServiceProperties properties; private final WebClient webClient; public OrderController(OrderServiceProperties properties, WebClient.Builder webClientBuilder) { this.properties = properties; this.webClient = webClientBuilder.baseUrl("http://user-service:8080").build(); } @PostMapping @CircuitBreaker(name = "orderService", fallbackMethod = "createOrderFallback") @Retry(name = "orderService") @TimeLimiter(name = "orderService") public Mono<ResponseEntity<Order>> createOrder(@RequestBody CreateOrderRequest request) { logger.info("Creating order for user: {} - Service: {}", request.userId(), properties.name()); // Validate user exists via user service (through Kuma mesh) return validateUser(request.userId()) .flatMap(userValid -> { if (!userValid) { return Mono.just(ResponseEntity.badRequest() .body(new Order("invalid", "USER_NOT_FOUND", null, "FAILED"))); } String orderId = String.valueOf(orders.size() + 1); Order order = new Order(orderId, request.userId(), request.items(), "CREATED"); orders.put(orderId, order); logger.info("Order created successfully: {} - Service: {}", orderId, properties.name()); return Mono.just(ResponseEntity.ok(order)); }); } @GetMapping("/{orderId}") public ResponseEntity<Order> getOrder(@PathVariable String orderId) { logger.info("Fetching order: {} - Service: {}", orderId, properties.name()); Order order = orders.get(orderId); if (order == null) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok(order); } @GetMapping public ResponseEntity<List<Order>> getAllOrders() { logger.info("Fetching all orders - Service: {}", properties.name()); return ResponseEntity.ok(List.copyOf(orders.values())); } @GetMapping("/health") public ResponseEntity<Map<String, String>> health() { return ResponseEntity.ok(Map.of( "status", "healthy", "service", properties.name(), "version", properties.version(), "zone", properties.mesh().zone() )); } private Mono<Boolean> validateUser(String userId) { return webClient.get() .uri("/api/v1/users/{userId}", userId) .retrieve() .toBodilessEntity() .map(response -> response.getStatusCode().is2xxSuccessful()) .doOnError(error -> logger.warn("User validation failed for {}: {}", userId, error.getMessage())) .onErrorReturn(false); } // Fallback method for circuit breaker public Mono<ResponseEntity<Order>> createOrderFallback(CreateOrderRequest request, Exception ex) { logger.warn("Order creation fallback triggered for user: {}, error: {}", request.userId(), ex.getMessage()); Order fallbackOrder = new Order("fallback", request.userId(), request.items(), "PENDING_VALIDATION"); return Mono.just(ResponseEntity.accepted().body(fallbackOrder)); } } // File: order-service/src/main/java/com/example/order/Order.java package com.example.order; import java.util.List; public record Order( String id, String userId, List<OrderItem> items, String status ) {} // File: order-service/src/main/java/com/example/order/CreateOrderRequest.java package com.example.order; import java.util.List; public record CreateOrderRequest( String userId, List<OrderItem> items ) {} // File: order-service/src/main/java/com/example/order/OrderItem.java package com.example.order; public record OrderItem( String productId, int quantity, double price ) {} // File: order-service/src/main/java/com/example/order/OrderServiceProperties.java package com.example.order; import org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties(prefix = "order.service") public record OrderServiceProperties( String name, String version, String environment, MeshProperties mesh ) { public record MeshProperties( boolean enabled, String zone, String serviceAccount, int proxyPort ) {} }

Part 4: Kuma Configuration

4.1 Mesh Configuration

# kuma-config/mesh.yaml apiVersion: kuma.io/v1alpha1 kind: Mesh metadata: name: default spec: mtls: backends: - name: ca-1 type: builtin enabledBackend: ca-1 logging: backends: - name: file-backend type: file format: '{"start_time": "%START_TIME%", "method": "%REQ(:METHOD)%", "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%", "protocol": "%PROTOCOL%", "response_code": "%RESPONSE_CODE%", "response_flags": "%RESPONSE_FLAGS%", "bytes_received": "%BYTES_RECEIVED%", "bytes_sent": "%BYTES_SENT%", "duration": "%DURATION%", "upstream_service": "%UPSTREAM_CLUSTER%", "upstream_host": "%UPSTREAM_HOST%", "x_forwarded_for": "%REQ(X-FORWARDED-FOR)%", "user_agent": "%REQ(USER-AGENT)%", "request_id": "%REQ(X-REQUEST-ID)%", "authority": "%REQ(:AUTHORITY)%", "upstream_local_address": "%UPSTREAM_LOCAL_ADDRESS%"}' file: path: /tmp/access.log tracing: backends: - name: jaeger-collector type: jaeger sampling: 100.0 conf: collectorEndpoint: http://jaeger-collector:14268/api/traces metrics: enabledBackend: prometheus-1 backends: - name: prometheus-1 type: prometheus conf: port: 5670 path: /metrics tags: kuma.io/service: dataplane_metrics

4.2 Traffic Route Configuration

# kuma-config/traffic-route.yaml apiVersion: kuma.io/v1alpha1 kind: TrafficRoute mesh: default metadata: name: route-all-traffic spec: sources: - match: kuma.io/service: '*' destinations: - match: kuma.io/service: '*' conf: http: - match: path: prefix: / destination: kuma.io/service: '*' --- apiVersion: kuma.io/v1alpha1 kind: TrafficRoute mesh: default metadata: name: canary-user-service spec: sources: - match: kuma.io/service: 'order-service' destinations: - match: kuma.io/service: 'user-service' conf: http: - match: headers: x-canary: 'true' split: - weight: 10 destination: kuma.io/service: 'user-service-v2' - weight: 90 destination: kuma.io/service: 'user-service' - match: path: prefix: '/api/v1/users' split: - weight: 100 destination: kuma.io/service: 'user-service'

4.3 Circuit Breaker Configuration

# kuma-config/circuit-breaker.yaml apiVersion: kuma.io/v1alpha1 kind: CircuitBreaker mesh: default metadata: name: order-service-cb spec: sources: - match: kuma.io/service: 'order-service' destinations: - match: kuma.io/service: 'user-service' conf: interval: 30s baseEjectionTime: 30s maxEjectionPercent: 50 thresholds: maxConnections: 100 maxRequests: 100 maxRetries: 3 maxPendingRequests: 50 detectors: totalErrors: consecutive: 5 gatewayErrors: consecutive: 10 localOriginErrors: consecutive: 7

4.4 Retry Policy

# kuma-config/retry-policy.yaml apiVersion: kuma.io/v1alpha1 kind: RetryPolicy mesh: default metadata: name: order-service-retries spec: sources: - match: kuma.io/service: 'order-service' destinations: - match: kuma.io/service: 'user-service' conf: http: numRetries: 3 perTryTimeout: 2s backOff: baseInterval: 0.1s maxInterval: 3s retryOn: - gateway-error - connect-failure - refused-stream - retriable-4xx - reset

4.5 Fault Injection for Testing

# kuma-config/fault-injection.yaml apiVersion: kuma.io/v1alpha1 kind: FaultInjection mesh: default metadata: name: user-service-delay spec: sources: - match: kuma.io/service: 'test-client' destinations: - match: kuma.io/service: 'user-service' conf: delay: percentage: 50 value: 5s abort: percentage: 10 httpStatus: 503

Part 5: Kubernetes Deployment

5.1 Kuma Installation

# kubernetes/kuma-install.yaml apiVersion: v1 kind: Namespace metadata: name: kuma-system --- apiVersion: apps/v1 kind: Deployment metadata: namespace: kuma-system name: kuma-control-plane labels: app: kuma-control-plane spec: replicas: 1 selector: matchLabels: app: kuma-control-plane template: metadata: labels: app: kuma-control-plane annotations: kuma.io/mesh: default spec: containers: - name: kuma-cp image: kong-docker-kuma-docker.bintray.io/kuma-cp:2.6.0 ports: - containerPort: 5681 - containerPort: 5682 env: - name: KUMA_MULTI_ZONE_GLOBAL_KDS_GRPC_PORT value: "5685" resources: requests: memory: "256Mi" cpu: "100m" limits: memory: "512Mi" cpu: "500m" --- apiVersion: v1 kind: Service metadata: namespace: kuma-system name: kuma-control-plane labels: app: kuma-control-plane spec: ports: - port: 5681 targetPort: 5681 name: grpc - port: 5682 targetPort: 5682 name: http selector: app: kuma-control-plane

5.2 User Service Deployment

# kubernetes/services/user-service.yaml apiVersion: apps/v1 kind: Deployment metadata: name: user-service namespace: default labels: app: user-service version: v1 spec: replicas: 3 selector: matchLabels: app: user-service version: v1 template: metadata: labels: app: user-service version: v1 annotations: kuma.io/mesh: default kuma.io/sidecar-injection: "enabled" prometheus.io/scrape: "true" prometheus.io/port: "5670" prometheus.io/path: "/metrics" spec: serviceAccountName: user-service containers: - name: user-service image: my-registry/user-service:1.0.0 ports: - containerPort: 8080 env: - name: SPRING_APPLICATION_NAME value: "user-service" - name: USER_SERVICE_NAME value: "user-service" - name: USER_SERVICE_VERSION value: "1.0.0" - name: USER_SERVICE_ENVIRONMENT value: "production" - name: USER_SERVICE_MESH_ENABLED value: "true" - name: USER_SERVICE_MESH_ZONE value: "us-west-2" resources: requests: memory: "256Mi" cpu: "100m" limits: memory: "512Mi" cpu: "300m" livenessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 5 periodSeconds: 5 --- apiVersion: v1 kind: Service metadata: name: user-service namespace: default labels: app: user-service spec: ports: - port: 80 targetPort: 8080 protocol: TCP name: http selector: app: user-service type: ClusterIP --- apiVersion: v1 kind: ServiceAccount metadata: name: user-service namespace: default

5.3 Order Service Deployment

# kubernetes/services/order-service.yaml apiVersion: apps/v1 kind: Deployment metadata: name: order-service namespace: default labels: app: order-service version: v1 spec: replicas: 2 selector: matchLabels: app: order-service version: v1 template: metadata: labels: app: order-service version: v1 annotations: kuma.io/mesh: default kuma.io/sidecar-injection: "enabled" prometheus.io/scrape: "true" prometheus.io/port: "5670" spec: serviceAccountName: order-service containers: - name: order-service image: my-registry/order-service:1.0.0 ports: - containerPort: 8080 env: - name: SPRING_APPLICATION_NAME value: "order-service" - name: ORDER_SERVICE_NAME value: "order-service" - name: ORDER_SERVICE_VERSION value: "1.0.0" - name: ORDER_SERVICE_ENVIRONMENT value: "production" - name: ORDER_SERVICE_MESH_ENABLED value: "true" - name: ORDER_SERVICE_MESH_ZONE value: "us-west-2" resources: requests: memory: "256Mi" cpu: "100m" limits: memory: "512Mi" cpu: "300m" livenessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 5 periodSeconds: 5 --- apiVersion: v1 kind: Service metadata: name: order-service namespace: default labels: app: order-service spec: ports: - port: 80 targetPort: 8080 protocol: TCP name: http selector: app: order-service type: ClusterIP --- apiVersion: v1 kind: ServiceAccount metadata: name: order-service namespace: default

Part 6: Application Configuration

6.1 User Service Configuration

# user-service/src/main/resources/application.yaml spring: application: name: user-service server: port: 8080 user: service: name: user-service version: 1.0.0 environment: ${ENVIRONMENT:development} mesh: enabled: ${MESH_ENABLED:true} zone: ${MESH_ZONE:default} service-account: user-service proxy-port: 5670 management: endpoints: web: exposure: include: health,info,metrics,prometheus endpoint: health: show-details: always metrics: enabled: true metrics: export: prometheus: enabled: true tags: application: ${spring.application.name} zone: ${user.service.mesh.zone} environment: ${user.service.environment} logging: level: com.example.user: DEBUG org.springframework.web: INFO io.kuma: DEBUG resilience4j: circuitbreaker: instances: userService: register-health-indicator: true sliding-window-size: 10 minimum-number-of-calls: 5 permitted-number-of-calls-in-half-open-state: 3 automatic-transition-from-open-to-half-open-enabled: true wait-duration-in-open-state: 10s failure-rate-threshold: 50 event-consumer-buffer-size: 10 retry: instances: userService: max-attempts: 3 wait-duration: 2s

6.2 Order Service Configuration

# order-service/src/main/resources/application.yaml spring: application: name: order-service server: port: 8080 order: service: name: order-service version: 1.0.0 environment: ${ENVIRONMENT:development} mesh: enabled: ${MESH_ENABLED:true} zone: ${MESH_ZONE:default} service-account: order-service proxy-port: 5670 management: endpoints: web: exposure: include: health,info,metrics,prometheus endpoint: health: show-details: always metrics: enabled: true metrics: export: prometheus: enabled: true tags: application: ${spring.application.name} zone: ${order.service.mesh.zone} environment: ${order.service.environment} logging: level: com.example.order: DEBUG org.springframework.web: INFO io.kuma: DEBUG resilience4j: circuitbreaker: instances: orderService: register-health-indicator: true sliding-window-size: 10 minimum-number-of-calls: 5 permitted-number-of-calls-in-half-open-state: 3 automatic-transition-from-open-to-half-open-enabled: true wait-duration-in-open-state: 10s failure-rate-threshold: 50 retry: instances: orderService: max-attempts: 3 wait-duration: 1s webclient: timeout: connect: 5s read: 10s write: 10s

Part 7: Observability and Monitoring

7.1 Custom Metrics and Health Checks

// File: user-service/src/main/java/com/example/user/UserServiceMetrics.java package com.example.user; import io.micrometer.core.instrument.Counter; import io.micrometer.core.instrument.MeterRegistry; import io.micrometer.core.instrument.Timer; import org.springframework.stereotype.Component; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.TimeUnit; @Component public class UserServiceMetrics { private final MeterRegistry meterRegistry; private final Counter userCreationCounter; private final Counter userQueryCounter; private final Timer userQueryTimer; private final ConcurrentHashMap<String, Counter> errorCounters; public UserServiceMetrics(MeterRegistry meterRegistry) { this.meterRegistry = meterRegistry; this.errorCounters = new ConcurrentHashMap<>(); this.userCreationCounter = Counter.builder("user.service.creation.total") .description("Total number of user creations") .tag("service", "user-service") .register(meterRegistry); this.userQueryCounter = Counter.builder("user.service.query.total") .description("Total number of user queries") .tag("service", "user-service") .register(meterRegistry); this.userQueryTimer = Timer.builder("user.service.query.duration") .description("Time taken for user queries") .tag("service", "user-service") .register(meterRegistry); } public void recordUserCreation() { userCreationCounter.increment(); } public void recordUserQuery() { userQueryCounter.increment(); } public Timer.Sample startQueryTimer() { return Timer.start(meterRegistry); } public void stopQueryTimer(Timer.Sample sample) { sample.stop(userQueryTimer); } public void recordError(String errorType) { Counter errorCounter = errorCounters.computeIfAbsent(errorType, key -> Counter.builder("user.service.errors.total") .description("Total number of errors by type") .tag("service", "user-service") .tag("error_type", errorType) .register(meterRegistry)); errorCounter.increment(); } public void recordMeshRequest(String destination, String status) { Counter.builder("user.service.mesh.requests.total") .description("Requests through service mesh") .tag("service", "user-service") .tag("destination", destination) .tag("status", status) .register(meterRegistry) .increment(); } }

7.2 Enhanced Health Indicator

// File: user-service/src/main/java/com/example/user/UserServiceHealthIndicator.java package com.example.user; import org.springframework.boot.actuate.health.Health; import org.springframework.boot.actuate.health.HealthIndicator; import org.springframework.stereotype.Component; import java.net.InetAddress; import java.util.HashMap; import java.util.Map; @Component public class UserServiceHealthIndicator implements HealthIndicator { private final UserServiceProperties properties; public UserServiceHealthIndicator(UserServiceProperties properties) { this.properties = properties; } @Override public Health health() { try { Map<String, Object> details = new HashMap<>(); details.put("service", properties.name()); details.put("version", properties.version()); details.put("environment", properties.environment()); details.put("meshEnabled", properties.mesh().enabled()); details.put("meshZone", properties.mesh().zone()); details.put("hostname", InetAddress.getLocalHost().getHostName()); details.put("timestamp", System.currentTimeMillis()); // Add mesh-specific health checks if (properties.mesh().enabled()) { details.put("meshStatus", "connected"); details.put("proxyPort", properties.mesh().proxyPort()); } return Health.up() .withDetails(details) .build(); } catch (Exception e) { return Health.down() .withDetail("error", e.getMessage()) .build(); } } }

Part 8: Testing with Kuma

8.1 Integration Tests

// File: order-service/src/test/java/com/example/order/OrderServiceIntegrationTest.java package com.example.order; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.web.client.TestRestTemplate; import org.springframework.boot.test.web.server.LocalServerPort; import org.springframework.http.ResponseEntity; import org.springframework.test.context.ActiveProfiles; import java.util.List; import static org.junit.jupiter.api.Assertions.*; @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @ActiveProfiles("test") class OrderServiceIntegrationTest { @LocalServerPort private int port; @Autowired private TestRestTemplate restTemplate; @Test void shouldCreateOrderThroughMesh() { // Given String baseUrl = "http://localhost:" + port; CreateOrderRequest request = new CreateOrderRequest( "1", List.of(new OrderItem("product-1", 2, 29.99)) ); // When ResponseEntity<Order> response = restTemplate.postForEntity( baseUrl + "/api/v1/orders", request, Order.class); // Then assertTrue(response.getStatusCode().is2xxSuccessful()); assertNotNull(response.getBody()); assertEquals("1", response.getBody().userId()); assertNotNull(response.getBody().id()); } @Test void shouldReturnHealthStatusWithMeshInfo() { // Given String baseUrl = "http://localhost:" + port; // When ResponseEntity<String> response = restTemplate.getForEntity( baseUrl + "/api/v1/orders/health", String.class); // Then assertTrue(response.getStatusCode().is2xxSuccessful()); assertTrue(response.getBody().contains("healthy")); assertTrue(response.getBody().contains("order-service")); } }

8.2 Resilience Testing

// File: order-service/src/test/java/com/example/order/OrderServiceResilienceTest.java package com.example.order; import io.github.resilience4j.circuitbreaker.CircuitBreaker; import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.context.ActiveProfiles; import static org.junit.jupiter.api.Assertions.*; @SpringBootTest @ActiveProfiles("test") class OrderServiceResilienceTest { @Autowired private CircuitBreakerRegistry circuitBreakerRegistry; @Test void shouldConfigureCircuitBreaker() { // When CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker("orderService"); // Then assertNotNull(circuitBreaker); assertEquals("orderService", circuitBreaker.getName()); assertEquals(CircuitBreaker.State.CLOSED, circuitBreaker.getState()); } }

Best Practices for Kuma with Java

  1. Gradual Adoption: Start with observability, then add security and traffic management
  2. Proper Tagging: Use consistent tags for services across the mesh
  3. Health Checks: Implement comprehensive health checks for both application and mesh
  4. Circuit Breaking: Combine application-level and mesh-level circuit breaking
  5. Observability: Leverage Kuma's built-in metrics, tracing, and logging
  6. Security: Enable mTLS for service-to-service communication
  7. Testing: Test both with and without mesh in your CI/CD pipeline
  8. Monitoring: Set up alerts for mesh-level and application-level issues

Conclusion

Integrating Kuma Service Mesh with Java applications provides a powerful foundation for building resilient, observable, and secure microservices architectures. By leveraging Kuma's capabilities alongside Java frameworks like Spring Boot, you can:

  • Automate traffic management with sophisticated routing and load balancing
  • Implement zero-trust security with automatic mTLS and service identity
  • Gain comprehensive observability with built-in metrics, tracing, and logging
  • Enhance resilience with circuit breaking, retries, and fault injection
  • Simplify operations with declarative configuration and multi-zone support

The patterns and examples in this guide demonstrate how to effectively integrate Java microservices with Kuma service mesh, creating a robust platform for modern cloud-native applications that can scale across multiple environments and deployment scenarios.

Pyroscope Profiling in Java
Explains how to use Pyroscope for continuous profiling in Java applications, helping developers analyze CPU and memory usage patterns to improve performance and identify bottlenecks.
https://macronepal.com/blog/pyroscope-profiling-in-java/

OpenTelemetry Metrics in Java: Comprehensive Guide
Provides a complete guide to collecting and exporting metrics in Java using OpenTelemetry, including counters, histograms, gauges, and integration with monitoring tools. (MACRO NEPAL)
https://macronepal.com/blog/opentelemetry-metrics-in-java-comprehensive-guide/

OTLP Exporter in Java: Complete Guide for OpenTelemetry
Explains how to configure OTLP exporters in Java to send telemetry data such as traces, metrics, and logs to monitoring systems using HTTP or gRPC protocols. (MACRO NEPAL)
https://macronepal.com/blog/otlp-exporter-in-java-complete-guide-for-opentelemetry/

Thanos Integration in Java: Global View of Metrics
Explains how to integrate Thanos with Java monitoring systems to create a scalable global metrics view across multiple Prometheus instances.

https://macronepal.com/blog/thanos-integration-in-java-global-view-of-metrics

Time Series with InfluxDB in Java: Complete Guide (Version 2)
Explains how to manage time-series data using InfluxDB in Java applications, including storing, querying, and analyzing metrics data.

https://macronepal.com/blog/time-series-with-influxdb-in-java-complete-guide-2

Time Series with InfluxDB in Java: Complete Guide
Provides an overview of integrating InfluxDB with Java for time-series data handling, including monitoring applications and managing performance metrics.

https://macronepal.com/blog/time-series-with-influxdb-in-java-complete-guide

Implementing Prometheus Remote Write in Java (Version 2)
Explains how to configure Java applications to send metrics data to Prometheus-compatible systems using the remote write feature for scalable monitoring.

https://macronepal.com/blog/implementing-prometheus-remote-write-in-java-a-complete-guide-2

Implementing Prometheus Remote Write in Java: Complete Guide
Provides instructions for sending metrics from Java services to Prometheus servers, enabling centralized monitoring and real-time analytics.

https://macronepal.com/blog/implementing-prometheus-remote-write-in-java-a-complete-guide

Building a TileServer GL in Java: Vector and Raster Tile Server
Explains how to build a TileServer GL in Java for serving vector and raster map tiles, useful for geographic visualization and mapping applications.

https://macronepal.com/blog/building-a-tileserver-gl-in-java-vector-and-raster-tile-server

Indoor Mapping in Java
Explains how to create indoor mapping systems in Java, including navigation inside buildings, spatial data handling, and visualization techniques.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper