Merge branch 'main' of https://github.com/spring-cloud/spring-cloud-k…

…ubernetes

docs/modules/ROOT/pages/load-balancer.adoc

@@ -1,7 +1,7 @@
 [[loadbalancer-for-kubernetes]]
 = LoadBalancer for Kubernetes
 
-This project includes Spring Cloud Load Balancer for load balancing based on Kubernetes Endpoints and provides implementation of load balancer based on Kubernetes Service.
+This project includes Spring Cloud Load Balancer for load balancing based on either Kubernetes Endpoints or Kubernetes Service.
 To include it to your project add the following dependency.
 Fabric8 Implementation
 [source,xml]
@@ -21,16 +21,71 @@ Kubernetes Java Client Implementation
 </dependency>
 ----
 
-To enable load balancing based on Kubernetes Service name use the following property. Then load balancer would try to call application using address, for example `service-a.default.svc.cluster.local`
+There are two "modes" in which load balancer works: `POD` and `SERVICE`, denoted by the property (default being `POD`)
+
 [source]
 ----
 spring.cloud.kubernetes.loadbalancer.mode=SERVICE
 ----
 
-To enabled load balancing across all namespaces use the following property. Property from `spring-cloud-kubernetes-discovery` module is respected.
+or
+
+[source]
+----
+spring.cloud.kubernetes.loadbalancer.mode=POD
+----
+
+In `POD` mode, we will use the `DiscoveryClient` to find all services that match your load balancer name. For example, if you have a configuration like this:
+
+[source]
+----
+@Bean
+@LoadBalanced
+WebClient.Builder client() {
+	return WebClient.builder();
+}
+----
+
+and issue a request to `http://service-a` using that `WebClient`, we will use `service-a` to call `DiscoveryClient::getInstances` with this value. Since this is using `DiscoveryClient`, all the configuration specific to it apply, which are explained in the relevant part of the documentation.
+
+On the other hand, if you use `SERVICE` mode, things are a bit different, but closely resemble discovery client settings. For example, to answer the question in which namespace(s) to look for service(s) with name `service-a`, we will use one of the settings:
+
 [source]
 ----
-spring.cloud.kubernetes.discovery.all-namespaces=true
+spring.cloud.kubernetes.discovery.all-namespaces
+spring.cloud.kubernetes.discovery.namespaces
 ----
 
-If a service needs to be accessed over HTTPS you need to add a label or annotation to your service definition with the name `secured` and the value `true` and the load balancer will then use HTTPS to make requests to the service.
+to either search in all-namespaces, or the so-called "selective namespaces". If none of the above are specified, xref:property-source-config.adoc#namespace-resolution[Namespace Resolution] kicks in.
+
+Once we find all the services, we need to know what port to call them by. If the service in question has a single port defined, that is what we will use, no matter of its name. If there are no ports defined, this service will not be considered for load balancing and will be skipped.
+
+If there are more then one ports defined, we will try to match its name to the value of the property (`http` by default):
+
+[source]
+----
+spring.cloud.kubernetes.loadbalancer.portName
+----
+
+In case such a match is found, that port number will be used. Otherwise, the "first" port from the list will be used. This last option is non-deterministic and care must be taken.
+
+Once we know the port, we know how to call that service. The URL will have the form:
+
+[source]
+----
+service-a.<SERVICE_NAMESPACE>.svc.<DOMAIN>:<FOUND_PORT>
+----
+
+
+`<SERVICE_NAMESPACE>` is the namespace where the service resides, `DOMAIN` is the value of the property (by default it is equal to `cluster.local`):
+
+[source]
+----
+spring.cloud.kubernetes.loadbalancer.clusterDomain
+----
+
+and `<FOUND_PORT>` is the port of the service that we have chosen described in the process above.
+
+If a service needs to be accessed over HTTPS, you need to explicitly configure that. The rules for that are exactly the same as for the discovery implementation and can be found in the relevant part of the documentation regarding discovery-client.
+
+

spring-cloud-kubernetes-client-loadbalancer/src/main/java/org/springframework/cloud/kubernetes/client/loadbalancer/KubernetesClientServiceInstanceMapper.java

@@ -40,6 +40,7 @@
 import org.springframework.util.StringUtils;
 
 import static java.util.Optional.ofNullable;
+import static org.springframework.cloud.kubernetes.commons.discovery.KubernetesDiscoveryConstants.NON_DETERMINISTIC_PORT_MESSAGE;
 import static org.springframework.cloud.kubernetes.commons.discovery.KubernetesDiscoveryConstants.PORT_NAME_PROPERTY;
 import static org.springframework.cloud.kubernetes.commons.discovery.ServicePortSecureResolver.Input;
 
@@ -102,9 +103,9 @@ public KubernetesServiceInstance map(V1Service service) {
 				}
 			}
 			else {
-				LOG.warn(() -> PORT_NAME_PROPERTY + " is not set, as such will not consider service with name : "
-						+ metadata.getName());
-				return null;
+				LOG.warn(() -> PORT_NAME_PROPERTY + " is not set");
+				LOG.warn(() -> NON_DETERMINISTIC_PORT_MESSAGE);
+				port = ports.get(0);
 			}
 		}
 
@@ -135,7 +136,7 @@ private boolean secure(V1ServicePort port, V1Service service) {
 
 	private void logWarning(String portNameFromProperties) {
 		LOG.warn(() -> "Did not find a port name that is equal to the value " + portNameFromProperties);
-		LOG.warn(() -> "Will return 'first' port found, which is non-deterministic");
+		LOG.warn(() -> NON_DETERMINISTIC_PORT_MESSAGE);
 	}
 
 }

spring-cloud-kubernetes-client-loadbalancer/src/test/java/org/springframework/cloud/kubernetes/client/loadbalancer/KubernetesClientServiceInstanceMapperTests.java

@@ -192,6 +192,25 @@ void multiplePortsNameDoesNotMatchProperty(CapturedOutput output) {
 		Assertions.assertTrue(serviceInstance.getPort() == 80 || serviceInstance.getPort() == 443);
 	}
 
+	@Test
+	void multiPortsEmptyPortNameProperty(CapturedOutput output) {
+		KubernetesLoadBalancerProperties loadBalancerProperties = new KubernetesLoadBalancerProperties();
+		loadBalancerProperties.setPortName("");
+		KubernetesClientServiceInstanceMapper mapper = new KubernetesClientServiceInstanceMapper(loadBalancerProperties,
+				KubernetesDiscoveryProperties.DEFAULT);
+
+		Map<String, String> annotations = Map.of("org.springframework.cloud", "true");
+		Map<String, String> labels = Map.of("beta", "true");
+		List<V1ServicePort> servicePorts = List.of(new V1ServicePortBuilder().withName("http-api").withPort(80).build(),
+				new V1ServicePortBuilder().withName("https").withPort(443).build());
+		V1Service service = createService("database", "default", annotations, labels, servicePorts);
+		KubernetesServiceInstance serviceInstance = mapper.map(service);
+		Assertions.assertNotNull(serviceInstance);
+		Assertions.assertTrue(output.getOut().contains("'spring.cloud.kubernetes.loadbalancer.portName' is not set"));
+		Assertions.assertTrue(output.getOut().contains("Will return 'first' port found, which is non-deterministic"));
+		Assertions.assertTrue(serviceInstance.getPort() == 80 || serviceInstance.getPort() == 443);
+	}
+
 	private V1Service createService(String name, String namespace, Map<String, String> annotations,
 			Map<String, String> labels, List<V1ServicePort> servicePorts) {
 		return new V1ServiceBuilder()

spring-cloud-kubernetes-commons/src/main/java/org/springframework/cloud/kubernetes/commons/discovery/KubernetesDiscoveryConstants.java

@@ -103,4 +103,9 @@ private KubernetesDiscoveryConstants() {
 	 */
 	public static final String PORT_NAME_PROPERTY = "'spring.cloud.kubernetes.loadbalancer.portName'";
 
+	/**
+	 * message for non-deterministic port.
+	 */
+	public static final String NON_DETERMINISTIC_PORT_MESSAGE = "Will return 'first' port found, which is non-deterministic";
+
 }

spring-cloud-kubernetes-fabric8-loadbalancer/src/main/java/org/springframework/cloud/kubernetes/fabric8/loadbalancer/Fabric8ServiceInstanceMapper.java

@@ -39,6 +39,7 @@
 import org.springframework.core.log.LogAccessor;
 import org.springframework.util.StringUtils;
 
+import static org.springframework.cloud.kubernetes.commons.discovery.KubernetesDiscoveryConstants.NON_DETERMINISTIC_PORT_MESSAGE;
 import static org.springframework.cloud.kubernetes.commons.discovery.KubernetesDiscoveryConstants.PORT_NAME_PROPERTY;
 import static org.springframework.cloud.kubernetes.commons.discovery.ServicePortSecureResolver.Input;
 
@@ -101,9 +102,9 @@ public KubernetesServiceInstance map(Service service) {
 				}
 			}
 			else {
-				LOG.warn(() -> PORT_NAME_PROPERTY + " is not set, as such will not consider service with name : "
-						+ metadata.getName());
-				return null;
+				LOG.warn(() -> PORT_NAME_PROPERTY + " is not set");
+				LOG.warn(() -> NON_DETERMINISTIC_PORT_MESSAGE);
+				port = ports.get(0);
 			}
 		}
 
@@ -130,7 +131,7 @@ private boolean secure(ServicePort port, Service service) {
 
 	private void logWarning(String portNameFromProperties) {
 		LOG.warn(() -> "Did not find a port name that is equal to the value " + portNameFromProperties);
-		LOG.warn(() -> "Will return 'first' port found, which is non-deterministic");
+		LOG.warn(() -> NON_DETERMINISTIC_PORT_MESSAGE);
 	}
 
 }

spring-cloud-kubernetes-fabric8-loadbalancer/src/test/java/org/springframework/cloud/kubernetes/fabric8/loadbalancer/Fabric8ServiceInstanceMapperTests.java

@@ -217,7 +217,7 @@ void testSinglePortDoesNotMatchProperty(CapturedOutput output) {
 	/**
 	 * <pre>
 	 *     service has multiple ServicePorts, and 'spring.cloud.kubernetes.loadbalancer.portName' is empty.
-	 *     in this case, service will be skipped.
+	 *     in this case, a single, 'first', port will be returned.
 	 * </pre>
 	 */
 	@Test
@@ -234,16 +234,15 @@ void testMultiplePortsWithoutPortNameProperty(CapturedOutput output) {
 		KubernetesServiceInstance result = new Fabric8ServiceInstanceMapper(loadBalancerProperties, discoveryProperties)
 				.map(service);
 
-		Assertions.assertNull(result);
-		Assertions.assertTrue(output.getOut().contains(
-				"'spring.cloud.kubernetes.loadbalancer.portName' is not set, as such will not consider service with name : test"));
+		Assertions.assertNotNull(result);
+		Assertions.assertTrue(output.getOut().contains("'spring.cloud.kubernetes.loadbalancer.portName' is not set"));
+		Assertions.assertTrue(output.getOut().contains("Will return 'first' port found, which is non-deterministic"));
 
 	}
 
 	/**
 	 * <pre>
-	 *     service has multiple ServicePorts, and 'spring.cloud.kubernetes.loadbalancer.portName' is empty.
-	 *     in this case, service will be skipped.
+	 *     service has multiple ServicePorts, and 'spring.cloud.kubernetes.loadbalancer.portName' is not empty.
 	 * </pre>
 	 */
 	@Test
@@ -267,8 +266,8 @@ void testMultiplePortsWithPortNamePropertyMatch(CapturedOutput output) {
 
 	/**
 	 * <pre>
-	 *     service has multiple ServicePorts, and 'spring.cloud.kubernetes.loadbalancer.portName' is empty.
-	 *     in this case, service will be skipped.
+	 *     service has multiple ServicePorts, and 'spring.cloud.kubernetes.loadbalancer.portName' is not empty.
+	 *     property name also does not match 'potName'
 	 * </pre>
 	 */
 	@Test