Load Balancers for Kubernetes clusters should always be provisioned via the cluster’s Cloud Controller Manager. It is not correct procedure to provision the Load Balancer by creating a Scaleway Load Balancer in the console or via the API, and then attempting to use it as your cluster’s external Load Balancer. Similarly, you cannot use the Scaleway console or devtools to edit your cluster’s Load Balancer after creation, this must be done via the CCM, as detailed in this documentation.
Creating and configuring a Load Balancer service
Creating a Load Balancer for your Kubernetes cluster allows you to expose an application running inside your cluster to the internet.
In this document, we summarize when to create a Load Balancer for your cluster (as opposed to a different solution for exposing your application), and take you through the basic steps to create and configure your Load Balancer.
Does your cluster need a Load Balancer?
Before creating a Load Balancer for your cluster, ensure that this is definitely the best solution for what you want to achieve.
A single LoadBalancer Service is sufficient for exposing one service in your cluster. Each further service will need its own external Load Balancer (which should generally be set up to forward TCP traffic) and corresponding LoadBalancer
Service.
However, remember that Load Balancers are a paid-for resource. Consider whether one of the following free solutions might be appropriate if you have a relatively simple cluster:
- A ClusterIP Service is sufficient for facilitating communication between different components in a cluster.
- A NodePort Service is often sufficient for exposing a single application in a simple cluster, to the internet for testing purposes.
On the other hand, if you have multiple services running in a more complex cluster, and you want to forward traffic to the right service based on HTTP, consider the following:
- Ingress with an ingress controller and Load Balancer may be more suitable for exposing multiple services in your cluster, via a single external IP which forwards HTTP traffic to the right service in the cluster based on Ingress rules.
Read the full documentation on different ways to expose your services for full details, and links to the relevant documentation for each possibility.
Creating a Load Balancer for your cluster: overview
Here is a quick overview of how to create a Load Balancer for your cluster:
- Create a Scaleway Kubernetes Kapsule cluster with an application running inside.
- Make sure you have installed and configured kubectl
- Create a yaml manifest to describe the LoadBalancer service you want to create. You can use Load Balancer annotations to fine-tune the Load Balancer’s configuration in the manifest.
- Deploy the LoadBalancer service based on the manifest, using kubectl. The Cloud Controller Manager (CCM) will spin up the external Scaleway Load Balancer with the correct configuration to forward traffic to the LoadBalancer service within your cluster.
- Modify your Load Balancer’s configuration as necessary via the yaml manifest and Load Balancer annotations , putting any new annotations into effect via kubectl, so the CCM can carry out the modifications as necessary.
Creating a Load Balancer for your cluster: step by step
Before you start
To complete the actions presented below, you must have:
- A Scaleway account logged into the console
- Owner status or IAM permissions allowing you to perform actions in the intended Organization
- Created a Kubernetes Kapsule cluster
- Installed and configured kubectl
- An application running in your cluster
You can refer to the following example of webserver application to run.
-
Create a
.yaml
file to hold the manifest for your cluster’s Load Balancer. This will describe the resource (Load Balancer) that you want to create.Below, find an example for the content of the yaml manifest. You will need to edit it to your own specifications.
apiVersion: v1kind: Servicemetadata:name: myloadbalancerspec:type: LoadBalancerports:- port: 8000name: httptargetPort: 8000selector:app: mydeploymentapiVersion
: which version of the Kubernetes API to use to create the objectkind
: the kind of object defined in this YAML file. For a Load Balancer, specify aService
metadata
: helps uniquely identify the Service object: give it aname
(e.g.myloadbalancer
).spec
: specifies the Service:type
: the type of Service required: aLoadBalancer
Service.ports
: the ports for the Service configuration. You can define many ports if you want, here we specify just one:port
: the new service port that will be created, for connecting to the applicationname
: a name for this port, e.g.http
targetPort
: the application port to target with requests coming from the Serviceselector
: links the LoadBalancer Service with a set of pods in the cluster. Ensure that theapp
specified matches the name of the deployment of your app in the cluster (runkubectl get all
if necessary to check the name).
-
Use the command
kubectl create -f <name-of-manifest-file>.yaml
to tell the Kubernetes Cloud Controller to create the Load Balancer from the manifest in the default namespace. -
Run
kubectl get svc
to confirm that the Load Balancer Service has been created, and view its external IP. You can also check the Load Balancer section of the Scaleway console, where your Kuberenetes cluster’s Load Balancer now appears. Note that you should not attempt to edit or delete the Load Balancer via the console, only via the manifest file and kubectl.
Specifying an IP address for your Load Balancer
By default, when you create a Load Balancer for your cluster, it will be assigned a public IP address at random. When you delete the Load Balancer, the IP address will also be deleted, and cannot be retrieved to transfer to another Load Balancer service in your cluster.
However, it is possible to use flexible IP addresses with your cluster’s Load Balancer, to give you more control over the IPs being used. Flexible IP addresses can be kept in your account even if/when their associated Load Balancer is deleted. They can then be assigned to a new Load Balancer in the future.
To specify that an existing flexible IP address that you hold in your account should be used when creating your Load Balancer, add the loadBalancerIP
field to your yaml manifest, as shown in the last line here:
apiVersion: v1kind: Servicemetadata:name: myloadbalancerspec:type: LoadBalancerports:- port: 8000name: httptargetPort: 8000selector:app: mydeploymentloadBalancerIP: 51.159.24.7
For full details and further examples of how to use flexible IPs with your Kubernetes Load Balancer, see our dedicated documentation.
Defining your Load Balancer’s configuration via annotations
Your Load Balancer will be created with a default configuration unless you define configuration parameters via annotations.
With annotations, you can configure parameters such as the balancing method, health check settings, and more.
You should never try to modify the configuration of your cluster’s Load Balancer via the Scaleway console, the API, or any other devtools. Any modifications made this way will be overwritten by the cluster’s CCM. You should always use annotations as described below to configure your cluster’s Load Balancer.
Add annotations to the metadata
section of your LoadBalancer Service’s yaml manifest as shown below. In this example we include two annotations, but you can include as many as you need.
apiVersion: v1kind: Servicemetadata:name: myloadbalancerannotations:service.beta.kubernetes.io/scw-loadbalancer-forward-port-algorithm: "leastconn"service.beta.kubernetes.io/scw-loadbalancer-health-check-delay: "10s"spec:type: LoadBalancerports:- port: 8000name: httptargetPort: 8000selector:app: mydeployment
For full details on how to use Load Balancer annotations when creating your Load Balancer, or how to modify your Load Balancer’s annotations after creation, see our dedicated documentation. For a full list of Load Balancer annotations, refer to the Scaleway Cloud Controller documentation.
Troubleshooting Kubernetes Load Balancers
Load Balancer certificate error using SSL offload
If your Load Balancer is configured for SSL offload, and you have several services behind the same Load Balancer, you will encounter an SSL error when trying to reach the other services using HTTPS.
Example:
- podA
- podB (
https://serviceB.example.com
)
From podA, a curl to https://serviceB.example.com
will result in an SSL error.
To force the Load Balancer to handle all requests using the SSL offload, enable the use hostname annotations on your Load Balancer service.
Load Balancer TCP Proxy and Nginx Ingress error 400
If your Load Balancer is configured using TCP Proxy and you are using an Nginx Ingress, you might encounter an HTTP 400 error.
The Nginx Ingress must be configured with use-proxy-protocol to accept TCP Proxy requests.
Nginx Ingress Easy Deploy
The Easy Deploy Nginx Ingress can be configured to accept TCP Proxy:
controller:service:annotations:service.beta.kubernetes.io/scw-loadbalancer-proxy-protocol-v2: "true"service.beta.kubernetes.io/scw-loadbalancer-use-hostname: "true"config:use-forwarded-headers: truecompute-full-forwarded-for: trueuse-proxy-protocol: true
Further resources
For more help and support using Scaleway Load Balancers with your Kubernetes cluster, check out the following resources:
- Scaleway Load Balancers: full documentation *
- Getting Started with Kubernetes Load Balancers - Tutorial
- Getting Started with Kubernetes Load Balancers - Video Demonstration
- Configuring a Load Balancer for your Kubernetes applications - Webinar
- Managing Kubernetes Load Balancer IPs
- Using annotations for Kubernetes Load Balancers
* Though this documentation may be useful, bear in mind that it principally concerns Load Balancers outside a Kubernetes context. Remember to always create and configure Load Balancers for your Kubernetes cluster via the methods described on this page and not via the Scaleway console, API, or developer tools.