From 87b6142285b7a9bc88ab6e9a0a0d243c2ef56a24 Mon Sep 17 00:00:00 2001 From: Igor Shishkin Date: Thu, 29 Jan 2026 19:26:13 +0000 Subject: [PATCH 1/4] Add a notice about cluster level ingress annotations. --- samples/KubernetesIngress.Sample/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/samples/KubernetesIngress.Sample/README.md b/samples/KubernetesIngress.Sample/README.md index 416505bca..17a057088 100644 --- a/samples/KubernetesIngress.Sample/README.md +++ b/samples/KubernetesIngress.Sample/README.md @@ -93,18 +93,20 @@ The table below lists the available annotations. |yarp.ingress.kubernetes.io/output-cache-policy|string| |yarp.ingress.kubernetes.io/backend-protocol|string| |yarp.ingress.kubernetes.io/cors-policy|string| -|yarp.ingress.kubernetes.io/health-check|[ActivateHealthCheckConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.activehealthcheckconfig)| -|yarp.ingress.kubernetes.io/http-client|[HttpClientConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.httpclientconfig)| -|yarp.ingress.kubernetes.io/http-request|[ForwarderRequestConfig](https://learn.microsoft.com/en-us/dotnet/api/yarp.reverseproxy.forwarder.forwarderrequestconfig)| -|yarp.ingress.kubernetes.io/load-balancing|string| +|yarp.ingress.kubernetes.io/health-check|[ActivateHealthCheckConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.activehealthcheckconfig) [^1]| +|yarp.ingress.kubernetes.io/http-client|[HttpClientConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.httpclientconfig) [^1]| +|yarp.ingress.kubernetes.io/http-request|[ForwarderRequestConfig](https://learn.microsoft.com/en-us/dotnet/api/yarp.reverseproxy.forwarder.forwarderrequestconfig) [^1]| +|yarp.ingress.kubernetes.io/load-balancing|string [^1]| |yarp.ingress.kubernetes.io/route-metadata|Dictionary<string, string>| -|yarp.ingress.kubernetes.io/session-affinity|[SessionAffinityConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.sessionaffinityconfig)| +|yarp.ingress.kubernetes.io/session-affinity|[SessionAffinityConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.sessionaffinityconfig) [^1]| |yarp.ingress.kubernetes.io/transforms|List<Dictionary<string, string>>| |yarp.ingress.kubernetes.io/route-headers|List<[RouteHeader](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.routeheader)>| |yarp.ingress.kubernetes.io/route-queryparameters|List<[RouteQueryParameter](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.routequeryparameter)>| |yarp.ingress.kubernetes.io/route-order|int| |yarp.ingress.kubernetes.io/route-methods|List<string>| +[^1]: **Cluster-level annotation.** These annotations configure the YARP cluster, not the route. A cluster is identified by backend service name, namespace, and port. Multiple ingress rules targeting the same backend share the cluster, so conflicting values result in non-deterministic behavior. Ensure consistent values across all ingress rules for the same backend. + #### Authorization Policy See https://learn.microsoft.com/aspnet/core/fundamentals/servers/yarp/authn-authz for a list of available policies, or how to add your own custom policies. From 97ef64868ac6c0f8c63d627a92e0cb8e12a299e7 Mon Sep 17 00:00:00 2001 From: Igor Shishkin Date: Thu, 29 Jan 2026 19:32:11 +0000 Subject: [PATCH 2/4] Convert into NOTE block and use anchors for linking. --- samples/KubernetesIngress.Sample/README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/samples/KubernetesIngress.Sample/README.md b/samples/KubernetesIngress.Sample/README.md index 17a057088..baed80a04 100644 --- a/samples/KubernetesIngress.Sample/README.md +++ b/samples/KubernetesIngress.Sample/README.md @@ -93,19 +93,22 @@ The table below lists the available annotations. |yarp.ingress.kubernetes.io/output-cache-policy|string| |yarp.ingress.kubernetes.io/backend-protocol|string| |yarp.ingress.kubernetes.io/cors-policy|string| -|yarp.ingress.kubernetes.io/health-check|[ActivateHealthCheckConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.activehealthcheckconfig) [^1]| -|yarp.ingress.kubernetes.io/http-client|[HttpClientConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.httpclientconfig) [^1]| -|yarp.ingress.kubernetes.io/http-request|[ForwarderRequestConfig](https://learn.microsoft.com/en-us/dotnet/api/yarp.reverseproxy.forwarder.forwarderrequestconfig) [^1]| -|yarp.ingress.kubernetes.io/load-balancing|string [^1]| +|yarp.ingress.kubernetes.io/health-check|[ActivateHealthCheckConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.activehealthcheckconfig) [\*](#cluster-level-annotations)| +|yarp.ingress.kubernetes.io/http-client|[HttpClientConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.httpclientconfig) [\*](#cluster-level-annotations)| +|yarp.ingress.kubernetes.io/http-request|[ForwarderRequestConfig](https://learn.microsoft.com/en-us/dotnet/api/yarp.reverseproxy.forwarder.forwarderrequestconfig) [\*](#cluster-level-annotations)| +|yarp.ingress.kubernetes.io/load-balancing|string [\*](#cluster-level-annotations)| |yarp.ingress.kubernetes.io/route-metadata|Dictionary<string, string>| -|yarp.ingress.kubernetes.io/session-affinity|[SessionAffinityConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.sessionaffinityconfig) [^1]| +|yarp.ingress.kubernetes.io/session-affinity|[SessionAffinityConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.sessionaffinityconfig) [\*](#cluster-level-annotations)| |yarp.ingress.kubernetes.io/transforms|List<Dictionary<string, string>>| |yarp.ingress.kubernetes.io/route-headers|List<[RouteHeader](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.routeheader)>| |yarp.ingress.kubernetes.io/route-queryparameters|List<[RouteQueryParameter](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.routequeryparameter)>| |yarp.ingress.kubernetes.io/route-order|int| |yarp.ingress.kubernetes.io/route-methods|List<string>| -[^1]: **Cluster-level annotation.** These annotations configure the YARP cluster, not the route. A cluster is identified by backend service name, namespace, and port. Multiple ingress rules targeting the same backend share the cluster, so conflicting values result in non-deterministic behavior. Ensure consistent values across all ingress rules for the same backend. + + +> [!NOTE] +> **\* Cluster-level annotations:** These annotations configure the YARP cluster, not the route. A cluster is identified by backend service name, namespace, and port. Multiple ingress rules targeting the same backend share the cluster, so conflicting values result in non-deterministic behavior. Ensure consistent values across all ingress rules for the same backend. #### Authorization Policy From 4fbd72cc51b8865e0faf3e928621d255bac3aa71 Mon Sep 17 00:00:00 2001 From: Igor Shishkin Date: Thu, 29 Jan 2026 19:39:51 +0000 Subject: [PATCH 3/4] Move the annotation to the first column. --- samples/KubernetesIngress.Sample/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/samples/KubernetesIngress.Sample/README.md b/samples/KubernetesIngress.Sample/README.md index baed80a04..8aa5c0acd 100644 --- a/samples/KubernetesIngress.Sample/README.md +++ b/samples/KubernetesIngress.Sample/README.md @@ -93,12 +93,12 @@ The table below lists the available annotations. |yarp.ingress.kubernetes.io/output-cache-policy|string| |yarp.ingress.kubernetes.io/backend-protocol|string| |yarp.ingress.kubernetes.io/cors-policy|string| -|yarp.ingress.kubernetes.io/health-check|[ActivateHealthCheckConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.activehealthcheckconfig) [\*](#cluster-level-annotations)| -|yarp.ingress.kubernetes.io/http-client|[HttpClientConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.httpclientconfig) [\*](#cluster-level-annotations)| -|yarp.ingress.kubernetes.io/http-request|[ForwarderRequestConfig](https://learn.microsoft.com/en-us/dotnet/api/yarp.reverseproxy.forwarder.forwarderrequestconfig) [\*](#cluster-level-annotations)| -|yarp.ingress.kubernetes.io/load-balancing|string [\*](#cluster-level-annotations)| +|yarp.ingress.kubernetes.io/health-check [\*](#cluster-level-annotations)|[ActivateHealthCheckConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.activehealthcheckconfig)| +|yarp.ingress.kubernetes.io/http-client [\*](#cluster-level-annotations)|[HttpClientConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.httpclientconfig)| +|yarp.ingress.kubernetes.io/http-request [\*](#cluster-level-annotations)|[ForwarderRequestConfig](https://learn.microsoft.com/en-us/dotnet/api/yarp.reverseproxy.forwarder.forwarderrequestconfig)| +|yarp.ingress.kubernetes.io/load-balancing [\*](#cluster-level-annotations)|string| |yarp.ingress.kubernetes.io/route-metadata|Dictionary<string, string>| -|yarp.ingress.kubernetes.io/session-affinity|[SessionAffinityConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.sessionaffinityconfig) [\*](#cluster-level-annotations)| +|yarp.ingress.kubernetes.io/session-affinity [\*](#cluster-level-annotations)|[SessionAffinityConfig](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.sessionaffinityconfig)| |yarp.ingress.kubernetes.io/transforms|List<Dictionary<string, string>>| |yarp.ingress.kubernetes.io/route-headers|List<[RouteHeader](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.routeheader)>| |yarp.ingress.kubernetes.io/route-queryparameters|List<[RouteQueryParameter](https://learn.microsoft.com/dotnet/api/yarp.reverseproxy.configuration.routequeryparameter)>| From f9dcbcbe02f2d71067b241f4faea972eea225319 Mon Sep 17 00:00:00 2001 From: Igor Shishkin Date: Thu, 29 Jan 2026 19:48:18 +0000 Subject: [PATCH 4/4] Use a heading since cannot use inline HTML. --- samples/KubernetesIngress.Sample/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/samples/KubernetesIngress.Sample/README.md b/samples/KubernetesIngress.Sample/README.md index 8aa5c0acd..7076d5947 100644 --- a/samples/KubernetesIngress.Sample/README.md +++ b/samples/KubernetesIngress.Sample/README.md @@ -105,10 +105,10 @@ The table below lists the available annotations. |yarp.ingress.kubernetes.io/route-order|int| |yarp.ingress.kubernetes.io/route-methods|List<string>| - +#### Cluster-level annotations > [!NOTE] -> **\* Cluster-level annotations:** These annotations configure the YARP cluster, not the route. A cluster is identified by backend service name, namespace, and port. Multiple ingress rules targeting the same backend share the cluster, so conflicting values result in non-deterministic behavior. Ensure consistent values across all ingress rules for the same backend. +> Annotations marked with **\*** configure the YARP cluster, not the route. A cluster is identified by backend service name, namespace, and port. Multiple ingress rules targeting the same backend share the cluster, so conflicting values result in non-deterministic behavior. Ensure consistent values across all ingress rules for the same backend. #### Authorization Policy