Configuring the management mode for network load balancer target groups

Target group management is configured in Kubernetes's LoadBalancer type Service resource. Based on the service configuration, the Managed Service for Kubernetes controller automatically creates a Network Load Balancer that routes traffic to the cluster nodes.

By default, load balancers use a shared target group that includes all the cluster nodes. The load balancer checks all the cluster nodes for availability, even if the pods of the application it send traffic to are deployed only on some of them.

To reduce the number of nodes to check, you can configure the v2 target group management mode for your service with externalTrafficPolicy: Local. The controller will create for the network load balancer a separate target group with nodes hosting the application pods and will update it as needed. You can set the mode when creating a new service or configure it for an already existing one.

To configure the target group management mode:

1. Get ready to work.
2. Create a service of the LoadBalancer type or enable the v2 mode and the Local policy for an existing service.
3. Check the target group composition and application availability.

Getting startedGetting started

1. Make sure the cluster uses the RAPID release channel. This is currently the only channel supporting the v2 mode with the Local policy.

2. Contact support. Specify the cloud ID and cluster ID. Request connecting the v2 mode and wait for the confirmation.

3. Install kubectl and configure it to work with the new Managed Service for Kubernetes cluster.

4. Check Network Load Balancer quotas and limits: in v2 mode, a separate target group is created for each service that uses the Local policy. Request a quota increase if needed.

5. Check the cluster service account permissions and security group as described in this infrastructure setup guide.

6. Set up your application. The examples below use an application in the default namespace, whose pods have the app: demo label and accept TCP traffic on port 8080. Replace these placeholders with your actual values.

7. Verify that your pods are ready and check their placement:

   kubectl -n default get pods -l app=demo -o wide
   

Create a LoadBalancer type serviceCreate a LoadBalancer type service

To create a LoadBalancer type service for which the controller will automatically create a network load balancer with a dedicated target group:

1. Save the service specification to app-lb.yaml:

   apiVersion: v1
   kind: Service
   metadata:
     name: app-lb
     namespace: default
     annotations:
       yandex.cloud/controller-reconcile-mode: "v2"
   spec:
     type: LoadBalancer
     externalTrafficPolicy: Local
     selector:
       app: demo
     ports:
       - name: http
         port: 80
         targetPort: 8080
         protocol: TCP
   

   Where:

   • type: LoadBalancer under spec: Service type for which the controller automatically creates a network load balancer.
   • yandex.cloud/controller-reconcile-mode: "v2" under metadata.annotations: Annotation that enables the v2 target group management mode.
   • externalTrafficPolicy: Local under spec: Policy routing external traffic only to application pods residing on the same node. Combined with the v2 mode, the target group only includes nodes with pods chosen by the service selector.

   For additional properties, see the Service reference.

2. Create a service:

   kubectl apply -f app-lb.yaml
   

3. Wait for the NLB IP address to appear in the EXTERNAL-IP field of the service:

   kubectl -n default get service app-lb --watch
   

   The fact that the address appears does not confirm the application is ready. Check the result.

Enable the v2 mode for an existing LoadBalancer serviceEnable the v2 mode for an existing LoadBalancer service

Migration of an existing LoadBalancer service to v2 is supported without downtime. To enable the v2 management mode for an existing service:

1. Save the service configuration:

   kubectl -n default get service app-lb -o yaml > app-lb-backup.yaml
   

   Write down the load balancer address, target group composition, and results of availability checks. Make sure the application is available via the load balancer.

2. Check the traffic policy in the service settings:

   kubectl -n default get service app-lb -o jsonpath='{.spec.externalTrafficPolicy}'
   

   To make the target group smaller, you need the Local policy. If it is set to Cluster, check whether the Local policy is compatible with your application. To change the policy, update spec.externalTrafficPolicy in your source service manifest and apply the configuration. The v2 mode does not reduce the target list if using the Cluster policy.

3. Add the annotation to the Service object:

   kubectl -n default annotate service app-lb \
     yandex.cloud/controller-reconcile-mode=v2 --overwrite
   

   The command does not change externalTrafficPolicy. The controller will update cloud resources and delete resources of the previous mode in case they are no longer used.

   If the service is managed via Helm or GitOps, save the annotation in the source configuration. Otherwise, subsequent syncs may revert it to the previous value.

4. Check the result. When migrating multiple services, enable the v2 mode for them one by one.

Check the resultCheck the result

After creating the service or changing its target group management mode, complete the following steps:

1. View the service configuration and events:

   kubectl -n default get service app-lb -o yaml
   kubectl -n default describe service app-lb
   

2. Check the placement of your application pods, pod details in the EndpointSlice objects associated with the service, and node addresses:

   kubectl -n default get pods -l app=demo -o wide
   kubectl -n default get endpointslices \
     -l kubernetes.io/service-name=app-lb -o yaml
   kubectl get nodes -o wide
   

3. Find the network load balancer created for the service and check the targets in the attached target group. For the v2 and Local combination, targets must match the nodes with application pods chosen by the service selector. Compare the specific nodes rather than the number of pods or EndpointSlice records.

4. Check the target health and send a request to the application using the network load balancer address. If your application uses HTTP, run this command:

   curl http://<load_balancer_IP_address>/
   

Group changes and availability check results are updated asynchronously. To run a check on a test application, change the number of replicas or pod placement and make sure the group has updated.

Switch back to legacy modeSwitch back to legacy mode

For the network load balancer to use the shared target group containing all cluster nodes again, set the annotation value to legacy in the Service object:

kubectl -n default annotate service app-lb \
  yandex.cloud/controller-reconcile-mode=legacy --overwrite

If the service is managed via Helm or GitOps, make sure to save the changes in the source configuration as well. Check the result.

TroubleshootingTroubleshooting

If you fail to get the expected result, check the following conditions:

If the group composition does not match the pod placement after operations are completed, save the service YAML description, events, and update time to submit them to support. Do not manually delete system records in the metadata.finalizers field or remove shared target groups.

Useful linksUseful links

• Load balancer target groups
• Granting access to an application running in a Kubernetes cluster
• Fields and annotations of the Service resource