started worl

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,6 +21,76 @@ Kubernetes Java Client Implementation
 </dependency>
 ----
 
+There are two "modes" in which load balancer works: `POD` and `SERVICE`, denoted bt the property (default being `POD`)
+
+[source]
+----
+spring.cloud.kubernetes.loadbalancer.mode=SERVICE
+----
+
+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` to find all the pods that match this name. 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
+spring.cloud.kubernetes.discovery.namespaces
+----
+
+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.cluster.local:<FOUND_PORT>
+----
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 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`
 [source]
 ----