Ribbon Discovery in Kubernetes

Spring Cloud client applications that call a microservice should be interested on relying on a client load-balancing feature in order to automatically discover at which endpoint(s) it can reach a given service. This mechanism has been implemented within the spring-cloud-kubernetes-ribbon project, where a Kubernetes client populates a Ribbon ServerList that contains information about such endpoints.

The implementation is part of the following starter that you can use by adding its dependency to your pom file:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-kubernetes-ribbon</artifactId>
    <version>${latest.version}</version>
</dependency>

When the list of the endpoints is populated, the Kubernetes client searches the registered endpoints that live in the current namespace or project by matching the service name defined in the Ribbon Client annotation, as follows:

@RibbonClient(name = "name-service")

You can configure Ribbon’s behavior by providing properties in your application.properties (through your application’s dedicated ConfigMap) by using the following format: <name of your service>.ribbon.<Ribbon configuration key>, where:

  • <name of your service> corresponds to the service name you access over Ribbon, as configured by using the @RibbonClient annotation (such as name-service in the preceding example).

  • <Ribbon configuration key> is one of the Ribbon configuration keys defined by Ribbon’s CommonClientConfigKey class.

Additionally, the spring-cloud-kubernetes-ribbon project defines two additional configuration keys to further control how Ribbon interacts with Kubernetes. In particular, if an endpoint defines multiple ports, the default behavior is to use the first one found. To select more specifically which port to use in a multi-port service, you can use the PortName key. If you want to specify in which Kubernetes namespace the target service should be looked up, you can use the KubernetesNamespace key, remembering in both instances to prefix these keys with your service name and ribbon prefix, as specified earlier.

Table 1. Spring Cloud Kubernetes Ribbon Configuration
Property Key Type Default Value

spring.cloud.kubernetes.ribbon.enabled

boolean

true

spring.cloud.kubernetes.ribbon.mode

KubernetesRibbonMode

POD

spring.cloud.kubernetes.ribbon.cluster-domain

string

cluster.local

  • spring.cloud.kubernetes.ribbon.mode supports POD and SERVICE modes.

    • The POD mode is to achieve load balancing by obtaining the Pod IP address of Kubernetes and using Ribbon. POD mode uses the load balancing of the Ribbon Does not support Kubernetes load balancing, The traffic policy of Istio is not supported.

    • the SERVICE mode is directly based on the service name of the Ribbon. Get The Kubernetes service is concatenated into service-name.{namespace}.svc.{cluster.domain}:{port} such as: demo1.default.svc.cluster.local:8080. the SERVICE mode uses load balancing of the Kubernetes service to support Istio’s traffic policy.

  • spring.cloud.kubernetes.ribbon.cluster-domain Set the custom Kubernetes cluster domain suffix. The default value is: 'cluster.local'

The following examples use this module for ribbon discovery:

You can disable the Ribbon discovery client by setting the spring.cloud.kubernetes.ribbon.enabled=false key within the application properties file.