API Gateway Registers Unreachable/Wrong Hostname in Eureka on Windows, Causing 405 and Timeout Errors

[fregayeg]

In the Spring Petclinic microservices project, the API Gateway (spring-petclinic-api-gateway) registers with Eureka using the machine’s hostname (e.g., john-desktop.myorg.us.com:8080) instead of a local IP (127.0.0.1 or localhost). On certain Windows machines, this hostname fails to resolve locally, leading to:

• 405 Method Not Allowed for routed endpoints (e.g., GET /api/customer/owners), as the Gateway cannot route to the customers-service due to discovery failures.
• Connection Timeout (HTTP 500) for direct Gateway controller calls (e.g., GET /api/gateway/owners/1), as the WebClient cannot reach customers-service at the registered hostname/port (e.g., john-desktop.myorg.com:63715).

This issue is environment-specific, occurring on some Windows setups (e.g., with corporate DNS or strict firewall rules) but not others, despite identical code and updated environments (Java, IDE, Windows). The root cause is the lack of eureka.instance.prefer-ip-address: true in the API Gateway’s configuration, which would force Eureka to register services with IPs, avoiding hostname resolution issues.

Steps to Reproduce

1. Clone the repos.
2. Run the services on a Windows machine with a non-localhost hostname (e.g., john-desktop.myorg.com):
   • Start spring-petclinic-config-server (Config Server on port 8888)
   • Start spring-petclinic-discovery-server (Eureka on port 8761).
   • Start spring-petclinic-customers-service (random port, e.g., 63715).
   • Start spring-petclinic-api-gateway (port 8080).
3. Open the Eureka dashboard at http://localhost:8761.
4. Observe that API-GATEWAY and CUSTOMERS-SERVICE register with the machine’s hostname (e.g., john-desktop.myorg.com) instead of localhost or an IP.
5. Send requests:
   • curl -v http://localhost:8080/api/customer/owners → Returns 405 Method Not Allowed.
   • curl -v http://localhost:8080/api/gateway/owners/1 → Returns 500 (Connection Timeout).
6. Check logs:
   • 405: org.springframework.web.server.MethodNotAllowedException: Request method 'GET' is not supported.
   • Timeout: org.springframework.web.reactive.function.client.WebClientRequestException: Connection timed out: no further information: john-desktop.myorg.com/192.168.10.165:63715.

Expected Behavior

• Services (API Gateway, customers-service) should register with Eureka using localhost or 127.0.0.1 to ensure local resolution across all environments.
• Requests to /api/customer/owners and /api/gateway/owners/1 should succeed without errors.

Actual Behavior

• Services register with an unreachable hostname (e.g., john-desktop.myorg.com), causing routing failures and timeouts on some Windows machines.
• The API Gateway’s configuration lacks eureka.instance.prefer-ip-address: true, leading to inconsistent behavior across environments.

Screenshot

Proposed Fix

Add the following to the API Gateway’s configuration (e.g., spring-petclinic-api-gateway/src/main/resources/application.yml or the config repo):

eureka:
  instance:
    prefer-ip-address: true  # Register with IP instead of hostname
    hostname: localhost      # Ensure consistent local registration

Optionally, apply the same to customers-service and other services to ensure consistency:

eureka:
  instance:
    prefer-ip-address: true
    hostname: localhost
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka
server:
  port: 8081  # Optional: Use fixed port to avoid random ports like 63715

This change ensures services register with 127.0.0.1 or localhost, avoiding hostname resolution issues on Windows.

Workaround

Manually update the Windows hosts file (C:\Windows\System32\drivers\etc\hosts) to map the hostname to the correct IP:

127.0.0.1 john-desktop.myorg.com

Then, flush DNS with ipconfig /flushdns. However, this is not portable and requires manual intervention per machine.

Environment

• OS: Windows (updated, specific version not provided)
• Java: [e.g., OpenJDK 17, confirm with java -version]
• Spring Boot: [e.g., 3.x, check pom.xml]
• Spring Cloud: [e.g., 2023.x, check pom.xml]
• IDE: [e.g., IntelliJ, updated]
• Project: Spring Petclinic Microservices (https://github.com/spring-petclinic/spring-petclinic-microservices)

Additional Notes

• The issue is machine-specific, likely due to Windows DNS/firewall differences or corporate network policies affecting hostname resolution.
• Adding eureka.instance.prefer-ip-address: true is a standard practice in Spring Cloud to avoid such issues, especially in local development.
• Consider documenting this in the project’s README for Windows users.

Please review and consider adding the proposed configuration to the API Gateway and other services to improve cross-platform reliability.

[arey]

Hi @fregayeg thanks for the report.
On my Macbook, Eureka is already using IP Address without setting the eureka.instance.prefer-ip-addressproperty :

On your Windows machine, did you know where the Java name resolution is looking for the john-desktop.myorg.com value? from a system variable?

The Spring Cloud Eureka documentation says that:

In some cases, it is preferable for Eureka to advertise the IP addresses of services rather than the hostname.
But it does not describe the cases.

I cannot predict what side effects such a change might cause.