Gateway routes traffic to Consul address instead of service instance address in Ocelot 23.3+

[rongjieaaa]

This issue is particularly problematic in Kubernetes environments where downstream services and Consul are deployed in different locations, but affects any environment with separated Consul and service deployments.

Describe the bug

After upgrading Ocelot from version 23.2.x to 23.3.x or newer (including 24.x), the gateway incorrectly routes traffic to the Consul node address instead of the actual service instance address registered in Consul. This issue is particularly problematic in Kubernetes environments where downstream services and Consul are deployed in different locations.

Steps to reproduce

Steps to reproduce the behavior:

1. Set up Ocelot 23.3+ with Consul service discovery in a Kubernetes environment
2. Deploy Consul and downstream services in different locations/pods
3. Register the microservices with Consul
4. Configure Ocelot to use Consul for service discovery
5. Make a request through Ocelot to a downstream service
6. Observe that Ocelot attempts to connect to the Consul node address instead of the service instance address
   Note: This issue does NOT occur in Ocelot 23.2.x and earlier versions.

Expected behavior

Ocelot should route requests to the service instance address provided by Consul (entry.Service.Address) rather than using the Consul node address (node.Address).

Actual behavior

Ocelot routes requests to the Consul node address (node.Address) instead of the service instance address (entry.Service.Address), causing connection failures when the Consul nodes are not reachable from the gateway or when the service is deployed on different nodes than Consul.

Environment

• Ocelot Version: 23.3.0 and later
• Platform: Kubernetes (any distribution)
• Consul Version: Any version
• .NET Version: Not relevant (affects all .NET versions)

Root Cause Analysis

The regression was introduced in Ocelot 23.3 in the DefaultConsulServiceBuilder.GetDownstreamHost method. The current implementation incorrectly prioritizes the Consul node address over the service instance address:

// Current broken implementation (Ocelot 23.3+)
protected virtual string GetDownstreamHost(ServiceEntry entry, Node node)
    => node != null ? node.Name : entry.Service.Address;

Proposed Fix

The logic should be reversed to prioritize the service instance address, with node address as fallback only when service address is unavailable:

// Fixed implementation
protected virtual string GetDownstreamHost(ServiceEntry entry, Node node)
    => !string.IsNullOrEmpty(entry?.Service?.Address)
        ? entry.Service.Address 
        : node?.Address ?? node?.Name;

This change:

1. Restores previous behavior from Ocelot 23.2.x and earlier
2. Maintains backward compatibility for environments where service address might be empty
3. Fixes Kubernetes deployments where services and Consul run in separate pods
4. Preserves fallback behavior for edge cases where service address is unavailable by using node address as backup

Additional context

This issue is particularly critical in modern microservices architectures where:

• Services are containerized and dynamically scheduled across nodes
• Consul runs as a separate cluster or stateful set
• Network segmentation exists between service discovery and application layers
• Service mesh architectures rely on accurate endpoint discovery

[raman-m]

Dear @rongjieaaa,
What is your name? And what is your LinkedIn?
Thank you for your interest in Ocelot.

The issue you mentioned has already been widely discussed, and the description, prepared by AI, is excellent. However, you are a bit late and seem to have not read the official Ocelot documentation. Everything is clearly explained here:

• Consul Service Builder

Can you write C# code, or do you prefer using JSON configuration only? I believe you can write C#. The fix is straightforward and should be implemented by you or your development team by replacing one service in the DI container. It's a simple process:

• Use the AddConsul<T> method

Describe the bug

After upgrading Ocelot from version 23.2.x to 23.3.x or newer (including 24.x), the gateway incorrectly routes traffic to the Consul node address instead of the actual service instance address registered in Consul. This issue is particularly problematic in Kubernetes environments where downstream services and Consul are deployed in different locations.

This isn't a bug; it's an issue arising from teams choosing different strategies to deploy Consul and service discovery. When upgrading your Ocelot version, make sure to thoroughly read all the documentation and release notes first ❗ Only after that should you report any issues.
To be honest, I don't see your solution and can't discuss it further until you upload the entire solution to a repo for our review.

[raman-m]

Steps to reproduce

Steps to reproduce the behavior:

1. Set up Ocelot 23.3+ with Consul service discovery in a Kubernetes environment
2. Deploy Consul and downstream services in different locations/pods
3. Register the microservices with Consul
4. Configure Ocelot to use Consul for service discovery
5. Make a request through Ocelot to a downstream service
6. Observe that Ocelot attempts to connect to the Consul node address instead of the service instance address
   Note: This issue does NOT occur in Ocelot 23.2.x and earlier versions.

I don't see any issue. The only problem arises when lazy developers don't pick up their keyboards and implement what they need. I find your Steps to Repro absolutely pointless since the different Consul environment issue has already been widely discussed.

---

Expected behavior

Ocelot should route requests to the service instance address provided by Consul (entry.Service.Address) rather than using the Consul node address (node.Address).

Why do we need to alter the official behavior to support only your environment, causing issues for thousands of projects worldwide? Have you read #909 and understood that this behavior has existed since version 13.5.2? The community had already suggested a standard approach in the past, and we should respect that decision.
The Consul Service Builder feature enables you to override this behavior.

---

Actual behavior

Ocelot routes requests to the Consul node address (node.Address) instead of the service instance address (entry.Service.Address), causing connection failures when the Consul nodes are not reachable from the gateway or when the service is deployed on different nodes than Consul.

Not to the node.Address but to the node.Name as a hostname.
Once again, the Consul Service Builder feature enables you to override this behavior.

---

Environment

• Ocelot Version: 23.3.0 and later
• Platform: Kubernetes (any distribution)
• Consul Version: Any version
• .NET Version: Not relevant (affects all .NET versions)

This only impacts your Consul environment and configuration. Keep in mind that installing Consul with default options won't work when integrated with Ocelot.

---

Root Cause Analysis

The regression was introduced in Ocelot 23.3 in the DefaultConsulServiceBuilder.GetDownstreamHost method. The current implementation incorrectly prioritizes the Consul node address over the service instance address:

Wow, man! Do I need to explain again what your statement really implies?
As a team, we are not going to revisit priorities because of the project's historical development. Specifically, the community already proposed a standard approach in the past, and we should honor that decision.

// Current broken implementation (Ocelot 23.3+)
protected virtual string GetDownstreamHost(ServiceEntry entry, Node node)
    => node != null ? node.Name : entry.Service.Address;

Yes, this best practice was proposed by the community in the past, making it a historical standard. The node.Name should be a hostname or an IP string, and the instances must use different ports.

---

Proposed Fix

The logic should be reversed to prioritize the service instance address, with node address as fallback only when service address is unavailable:

That's a bad idea to suggest breaking thousands of environments across numerous projects, just to propose a fix tailored specifically for your environment.

// Fixed implementation
protected virtual string GetDownstreamHost(ServiceEntry entry, Node node)
    => !string.IsNullOrEmpty(entry?.Service?.Address)
        ? entry.Service.Address 
        : node?.Address ?? node?.Name;

I get how it could be "fixed," but the real question is, "Will you actually take the keyboard and implement what you need yourself?" Here's the recommendation: check out the AddConsul<T> method docs.

---

This change:

1. Restores previous behavior from Ocelot 23.2.x and earlier
2. Maintains backward compatibility for environments where service address might be empty
3. Fixes Kubernetes deployments where services and Consul run in separate pods
4. Preserves fallback behavior for edge cases where service address is unavailable by using node address as backup

Be honest with the community and focus on loving yourself!

---

Additional context

This issue is particularly critical in modern microservices architectures where:

• Services are containerized and dynamically scheduled across nodes
• Consul runs as a separate cluster or stateful set
• Network segmentation exists between service discovery and application layers
• Service mesh architectures rely on accurate endpoint discovery

Bla-bla-bla...
The "issue" will be resolved once you follow the recipe suggested in the official documentation.
Good luck!

[raman-m]

@rongjieaaa Would you like to convert this issue into a discussion?
OR
Would you like to continue working on the PR? I have an idea that we could discuss and potentially implement.

[rongjieaaa]

@raman-m wrote on October 9

Chinese Version (handwritten)

您好 @raman-m

关于交流

1. 首先，很抱歉这么迟才给您回复，昨晚在写PR的时候没有看到您的回复（没注意到github的提示）
2. 我的中文名叫刘榕杰，没有使用领英的习惯（但通过rongjieaaa、浅叹风云，可以在中国的社交平台找到我）
3. 在我的PR里，您有指出不应当在issues里使用AI。我想了下，确实不太合适
4. 由于我的英文书写表达能力目前还很差，所以我尝试着用母语表达，并附上google翻译的结果，您看这样可以吗

关于问题

1. 我看到了您发的解决方案，目前我们进行了调整并生效了，谢谢
2. 我们是从19.0.4升级到24.0.0出问题，这期间我只进行大版本（20.0.0->21.0.0->22.0.0->23.0.0->24.0.0）的排查
3. 排查原因的过程中，发现是从23->24出的问题，我只看了24.0.0的版本说明，没有去看中间每个小版本的说明，确实导致了误会的产生（以及应该更详细地查看官方手册）
4. 基于本次我的教训、方便全球其他开发者排查问题，看看未来是否方便在大版本的发布说明中，包含（23.0~23.4）的重要提示
   （只是给予我本次的教训参考）
5. 由于是工作项目，我们公司的项目引用Ocelot，所以我无法提供解决方案，所以只能在基于github上的代码讨论

English Version (By google translate)

Hello @raman-m

About Communication

1. First, I apologize for the late response. I didn't see your reply when I was writing a PR last night (I didn't notice the GitHub notification).
2. My Chinese name is Liu Rongjie, and I don't use LinkedIn (but I can be found on Chinese social platforms like rongjieaaa and 浅叹风云).
3. In my PR, you pointed out that AI shouldn't be used in issues. I thought about it, and it's definitely not appropriate.
4. Since my written English skills are still very poor, I've tried to express myself in my native language and attached the Google Translate result. Do you think this is okay?

About Issues

1. I saw the solution you posted, and we've made adjustments and it's working. Thank you.
2. The issue occurred when we upgraded from 19.0.4 to 24.0.0. During this time, I only troubleshooted the major versions (20.0.0 -> 21.0.0 -> 22.0.0 -> 23.0.0 -> 24.0.0).
3. During the troubleshooting process, I discovered that the issue originated from 23 to 24. I only read the 24.0.0 release notes and didn't read the notes for the intervening minor versions, which led to misunderstandings (and I should have reviewed the official manual in more detail).
4. Based on my experience and to help other developers around the world troubleshoot issues, I'm considering including important reminders for future releases (23.0-23.4).
   (This is just a reference for my experience.)
5. Since this is a work project, and our company's project references Ocelot, I can't offer a solution. This discussion can only be based on the code on GitHub.

[rongjieaaa]

@raman-m wrote on October 9

Chinese Version

好的，基于您的耐心帮助，目前问题已经得到解决
谢谢，辛苦了（基于您的链接，看到了很多人提了相关问题）

English Version(By Google Translate)

Thanks for your patience and help, the issue has been resolved.
Thank you for your hard work. (Based on your link, I saw that many people have raised related questions.)

[rongjieaaa]

@rongjieaaa Would you like to convert this issue into a discussion? OR Would you like to continue working on the PR? I have an idea that we could discuss and potentially implement.

@raman-m

Chinese Edition:

1. 挺想进一步交流的，如您所说，这个项目会影响到非常多的用户
2. 我想，会有很多用户会期望于使用Coelot时尽量少地配置/重写代码
   （现有方案，对于不少的用户来说都要进行额外调整）
3. 但对于优先使用entry.Service.Address的优势，我想到几个场景：
   3.a. 对于服务和Consul部署在「同一主机」的情况下，它们的地址相同（node.Name或entry.Service.Address均可）
   3.b. 对于服务和Consul部署在「不同主机或容器化部署」的情况下，他们的地址不同
   （entry.Service.Address为第一优先级时，用户无须额外操闲心Ocelot的配置）
   3.c. 对于「1个Consul对应多个下游服务」的情况下，node.Name将失去意义（无论node.Name是什么值）
4. 对于第三点，我的意思是：基于我能想到的场景，entry.Service.Addrss优先的逻辑在大多数情况下更让用户省心
5. 同时，也如您所说，您能从全局且更高的角度进行思考，所以也想听听您对于该问题的考量

English Edition (Goole Translate)

1. I'd love to discuss this further. As you mentioned, this project will impact a large number of users.
2. I believe many users would prefer to minimize configuration and code rewriting when using Coelot.
   (The current solution requires additional adjustments for many users.)
3. However, regarding the advantages of using entry.Service.Address, I can think of several scenarios:
   3.a. When the service and Consul are deployed on the same host, their addresses are the same (either node.Name or entry.Service.Address).
   3.b. If the service and Consul are deployed on different hosts or containerized deployments, their addresses will be different.
   (When entry.Service.Address takes precedence, users do not need to worry about Ocelot configuration.)
   3.c. If "one Consul corresponds to multiple downstream services," node.Name becomes meaningless (regardless of the node.Name value).
4. Regarding the third point, my point is: based on the scenarios I can think of, the logic of prioritizing entry.Service.Address is more worry-free in most cases.
5. Also, as you said, you are able to think from a holistic and high-level perspective, so I would also like to hear your thoughts on this issue.

[raman-m]

@rongjieaaa wrote

My Chinese name is Liu Rongjie, and I don't use LinkedIn (but I can be found on Chinese social platforms like rongjieaaa and 浅叹风云).

Awesome, it would be even better if you could share a direct link to professional websites with your public resumes, or simply to Facebook or X.com.

Since this is a work project, and our company's project references Ocelot, I can't offer a solution. This discussion can only be based on the code on GitHub.

Please avoid publishing Chinese texts next time and ensure they are removed before posting!
Okay, if I understood correctly, your company uses Ocelot and its services in production, right?
I will respond to you tomorrow...

[rongjieaaa]

@rongjieaaa wrote

My Chinese name is Liu Rongjie, and I don't use LinkedIn (but I can be found on Chinese social platforms like rongjieaaa and 浅叹风云).

Awesome, it would be even better if you could share a direct link to professional websites with your public resumes, or simply to Facebook or X.com.

Since this is a work project, and our company's project references Ocelot, I can't offer a solution. This discussion can only be based on the code on GitHub.

Please avoid publishing Chinese texts next time and ensure they are removed before posting! Okay, if I understood correctly, your company uses Ocelot and its services in production, right? I will respond to you tomorrow...

1. Our team provides customized web services, so it is not convenient to provide relevant links. Sorry.
2. OK, I will only reply to the English part next time, so that everyone can read more efficiently.
3. I'm also going to rest. I only sleep for a few hours these days. Good night~~~