Skip to content

Commit ed8d2b1

Browse files
bene2k1bene2k1
authored
docs(k8s): update documentation (#5133)
1 parent 5a717c9 commit ed8d2b1

File tree

2 files changed

+367
-179
lines changed

2 files changed

+367
-179
lines changed

‎pages/kubernetes/reference-content/lb-ingress-controller.mdx

Lines changed: 167 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,217 @@
11
---
22
meta:
3-
title: Exposing a Kubernetes Kapsule ingress controller service with a Load Balancer
3+
title: Deploying an NGINX ingress controller on Scaleway Kubernetes Kapsule with a Load Balancer
44
description: This page explains how to expose an application via an ingress object, and using a Load Balancer to make the IP persistent.
55
content:
66
h1: Exposing a Kubernetes Kapsule ingress controller service with a Load Balancer
77
paragraph: This page explains how to expose an application via an ingress object, and using a Load Balancer to make the IP persistent.
88
categories:
9-
- network
109
- kubernetes
11-
- storage
1210
- load-balancer
1311
tags: compute kapsule kubernetes ingress-controller k8s Load-balancer wildcard
1412
dates:
15-
validation: 2025-04-22
16-
posted: 2020-05-05
13+
validation: 2025-06-17
14+
posted: 2025-06-17
1715
---
1816

19-
This document will guide you through deploying a test application on a Kubernetes cluster, exposing it via an ingress object, and using a Scaleway Load Balancer to ensure persistent IP addressing.
17+
This page walks you through the process of deploying an NGINX ingress controller on Scaleway's Kubernetes Kapsule service.
18+
We will configure a Load Balancer that uses a persistent IP address, which is essential for maintaining consistent routing. Additionally, we will enable the PROXY protocol to preserve client information such as the original IP address and port, which is recommended for applications that need to log or act on this data.
19+
20+
We will explore the differences between ephemeral and persistent IP addresses, helping you understand when and why to use each type, and guide you through deploying a demo application that illustrates the entire setup.
21+
22+
By the end of this guide, you should have a robust and well-configured NGINX ingress controller running on Scaleway's Kubernetes platform.
2023

2124
<Macro id="requirements" />
2225

2326
- A Scaleway account logged into the [console](https://console.scaleway.com)
2427
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
2528
- Set up a [Kubernetes Kapsule cluster](/kubernetes/how-to/create-cluster/), deploying a TRAEFIK2 ingress controller via the application library using the [Easy Deploy function](/kubernetes/how-to/enable-easy-deploy/)
2629
- Obtained the [kubeconfig](/kubernetes/how-to/edit-cluster/) file for the cluster
27-
- Installed [kubectl](/kubernetes/how-to/connect-cluster-kubectl/) on your local machine
30+
- Helm installed on your local machine
31+
- Installed [kubectl](/kubernetes/how-to/connect-cluster-kubectl/) and the Scaleway CLI on your local machine
32+
33+
## Overview of key concepts
34+
35+
### Ingress controller
36+
An ingress controller manages external HTTP/HTTPS traffic to services within a Kubernetes cluster. The NGINX ingress controller routes traffic based on ingress resource rules.
37+
38+
### LoadBalancer service
39+
On Scaleway Kapsule, the LoadBalancer service provisions a Scaleway Load Balancer with an external IP, exposing the ingress controller via the Scaleway Cloud Controller Manager (CCM).
40+
41+
### Ephemeral vs. persistent IPs
42+
- Ephemeral IP: Dynamically assigned by Scaleway when a LoadBalancer service is created. It may change if the service is deleted and recreated, requiring DNS updates.
43+
- Persistent IP: A flexible IP reserved via the Scaleway API, CLI or console, ensuring consistency across service recreations. This is recommended for production to maintain stable DNS records.
2844

29-
## Exposing the ingress controller using a Scaleway Load Balancer
45+
### PROXY protocol
46+
The PROXY protocol allows the LoadBalancer to forward the client's original IP address to the ingress controller, preserving source information for logging and security.
3047

31-
By default, ingress controllers on Kapsule are deployed using a [hostPort](https://kubernetes.io/docs/concepts/services-networking/service/). This ensures accessibility on all cluster nodes via ports 80 and 443. However, for production readiness, you might prefer using a Load Balancer to expose your services to the internet.
48+
## Deploying the ingress controller
3249

33-
<Message type="important">
34-
By default, a new security group that blocks all incoming traffic on the nodes for security purposes is created during cluster configuration. To allow incoming HTTP/80 and HTTPS/443 traffic, you need to modify the security group.
50+
## Installation prework
51+
Kapsule clusters use a default security group (`kubernetes-<cluster-id>`) that blocks incoming traffic. To allow HTTP/HTTPS connections to the cluster:
52+
1. Go to the Scaleway console and navigate to **Compute > CPU & GPU Instances > Security Groups**.
53+
2. Locate the security group `kubernetes-<cluster-id>`.
54+
3. Add rules to allow:
55+
- TCP port 80 (HTTP) from `0.0.0.0/0`.
56+
- TCP port 443 (HTTPS) from `0.0.0.0/0`.
3557

36-
1. In the [Scaleway console](https://console.scaleway.com/instance/security-groups), navigate to the **Compute** > **Security groups** section and find the security group named `kubernetes <cluster-id>`.
37-
2. Modify the security group rules to allow incoming traffic on ports 80 (HTTP) and 443 (HTTPS).
38-
- Allow TCP traffic on port 80 from all sources (0.0.0.0/0) for HTTP.
39-
- Allow TCP traffic on port 443 from all sources (0.0.0.0/0) for HTTPS.
40-
</Message>
58+
## Reserve a flexible IP
59+
To use a persistent IP with the ingress controller:
60+
1. Create a flexible IP using the Scaleway CLI:
61+
```bash
62+
scw lb ip create
63+
```
64+
2. Note the IP address (e.g., `195.154.72.226`) and IP ID for use in the LoadBalancer service.
4165

42-
### Deploying a test application
66+
## Installing the NGINX ingress controller
4367

44-
1. Deploy the `cafe-ingress` test application:
68+
Use Helm to deploy the NGINX ingress controller with Scaleway-specific configurations.
4569

70+
1. Add the NGINX ingress Helm repository:
4671
```bash
47-
kubectl create -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/main/examples/ingress-resources/basic-auth/cafe.yaml
72+
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
73+
helm repo update
4874
```
4975

50-
2. Create the ingress object (`coffee-ingress.yaml`) using the DNS wildcard provided by Scaleway:
51-
76+
2. Create a file named `ingress-values.yaml` with and edit the `loadBalancerIP` to your flexible IP:
5277
```yaml
53-
apiVersion: networking.k8s.io/v1
54-
kind: Ingress
55-
metadata:
56-
name: coffee-ingress
57-
spec:
58-
rules:
59-
- host: YOUR_SCALEWAY_DNS_WILDCARD
60-
http:
61-
paths:
62-
- path: /tea
63-
pathType: Prefix
64-
backend:
65-
service:
66-
name: tea-svc
67-
port:
68-
number: 80
69-
- path: /coffee
70-
pathType: Prefix
71-
backend:
72-
service:
73-
name: coffee-svc
74-
port:
75-
number: 80
78+
controller:
79+
service:
80+
type: LoadBalancer
81+
# Specify reserved flexible IP
82+
loadBalancerIP: "195.154.72.226"
83+
annotations:
84+
# Enable PROXY protocol v2
85+
service.beta.kubernetes.io/scw-loadbalancer-proxy-protocol-v2: "true"
86+
# Use hostname for cert-manager compatibility
87+
service.beta.kubernetes.io/scw-loadbalancer-use-hostname: "true"
88+
config:
89+
# Enable PROXY protocol in NGINX
90+
use-proxy-protocol: "true"
91+
use-forwarded-headers: "true"
92+
compute-full-forwarded-for: "true"
7693
```
77-
7894
<Message type="note">
79-
Your DNS wildcard is composed of your cluster ID (e.g., `68362d3b-57c8-4bea-905a-aeb7f9ab95dc`) followed by `.nodes.k8s.<SCW_REGION>.scw.cloud`. For a cluster located in the Paris region, your DNS wildcard could be, for example: `hotdrinks.68362d3b-57c8-4bea-905a-aeb7f9ab95dc.nodes.k8s.fr-par.scw.cloud`.
95+
- Replace `195.154.72.226` with your reserved flexible IP. Omitting `loadBalancerIP` results in an ephemeral IP.
96+
- The `service.beta.kubernetes.io/scw-loadbalancer-proxy-protocol-v2` annotation enables PROXY protocol v2.
97+
- The `service.beta.kubernetes.io/scw-loadbalancer-use-hostname` annotation supports cert-manager HTTP01 challenges.
8098
</Message>
8199

82-
3. Apply the configuration:
83-
100+
3. Deploy the ingress controller:
84101
```bash
85-
kubectl create -f coffee-ingress.yaml
102+
helm install ingress-nginx ingress-nginx/ingress-nginx -f ingress-values.yaml --namespace ingress-nginx --create-namespace
86103
```
87104

88-
4. Test the ingress:
89-
105+
4. Verify the LoadBalancer IP using `kubectl`:
90106
```bash
91-
curl http://YOUR_SCALEWAY_DNS_WILDCARD/coffee
107+
kubectl get svc -n ingress-nginx ingress-nginx-controller
92108
```
93109

94-
## Using a reserved IP with a Load Balancer
95-
96-
Reserve a flexible Load Balancer IP address [through the Scaleway API](/kubernetes/reference-content/managing-load-balancer-ips/#reserve-a-load-balancer-flexible-ip-address-via-the-api). Take note of the IP address, referred to as `RESERVED_IP` from now on.
110+
You will see an output similar to the following example:
111+
```
112+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
113+
ingress-nginx-controller LoadBalancer 10.100.0.1 195.154.72.226 80/TCP,443/TCP 5m
114+
```
115+
<Message type="note">
116+
- The `EXTERNAL-IP` should match your reserved flexible IP (e.g., `195.154.72.226`).
117+
- If an ephemeral IP appears, verify that the `loadBalancerIP` field is correctly set and matches a valid Load Balancer flexible IP attached to your Scaleway Project.
118+
- Confirm the LoadBalancer in the Scaleway console under **Network > Load Balancers**.
119+
</Message>
97120

98-
### Using the reserved IP in Kubernetes
121+
5. Configure DNS by setting the A-Record of your domain (e.g., `demo.example.com`) to the flexible IP via Scaleway's Domains & DNS product or your DNS provider. Persistent IPs ensure stability and will not change as long as they are reserved.
99122

100-
1. Patch `tea-svc` to use the reserved IP with a `LoadBalancer` service:
123+
### Deploying a demo application
101124

102-
```bash
103-
kubectl patch svc tea-svc --type merge --patch '{"spec":{"loadBalancerIP": "RESERVED_IP","type":"LoadBalancer"}}'
104-
```
125+
1. Create a file named `demo-app.yaml` and copy the following content into it to deploy a simple web application to test the ingress controller:
105126

106-
2. Delete `tea-svc`:
127+
```yaml
128+
apiVersion: apps/v1
129+
kind: Deployment
130+
metadata:
131+
name: demo-app
132+
namespace: default
133+
spec:
134+
replicas: 2
135+
selector:
136+
matchLabels:
137+
app: demo-app
138+
template:
139+
metadata:
140+
labels:
141+
app: demo-app
142+
spec:
143+
containers:
144+
- name: demo-app
145+
image: nginx:1.21
146+
ports:
147+
- containerPort: 80
148+
---
149+
apiVersion: v1
150+
kind: Service
151+
metadata:
152+
name: demo-app
153+
namespace: default
154+
spec:
155+
selector:
156+
app: demo-app
157+
ports:
158+
- protocol: TCP
159+
port: 80
160+
targetPort: 80
161+
---
162+
apiVersion: networking.k8s.io/v1
163+
kind: Ingress
164+
metadata:
165+
name: demo-app-ingress
166+
namespace: default
167+
annotations:
168+
nginx.ingress.kubernetes.io/rewrite-target: /
169+
spec:
170+
ingressClassName: nginx
171+
rules:
172+
- host: demo.example.com
173+
http:
174+
paths:
175+
- path: /
176+
pathType: Prefix
177+
backend:
178+
service:
179+
name: demo-app
180+
port:
181+
number: 80
182+
```
107183

108-
```bash
109-
kubectl delete svc tea-svc
110-
```
184+
<Message type="note">
185+
- Replace `demo.example.com` with your domain name.
186+
</Message>
111187

112-
3. Patch `coffee-svc` to use the reserved IP:
188+
2. Apply the configuration:
189+
```bash
190+
kubectl apply -f demo-app.yaml
191+
```
113192

114-
```bash
115-
kubectl patch svc coffee-svc --type merge --patch '{"spec":{"loadBalancerIP": "RESERVED_IP","type":"LoadBalancer"}}'
116-
```
193+
## Test the setup
194+
1. Access the demo application:
195+
```bash
196+
curl http://demo.example.com
197+
# or
198+
curl http://195.154.72.226/
199+
```
117200

118-
## Related tutorials
201+
2. You should see the NGINX welcome page. Verify the PROXY protocol by checking logs for the client's real IP:
202+
```bash
203+
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
204+
```
119205

120-
- [Loki monitoring on Kubernetes](/tutorials/manage-k8s-logging-loki/)
121-
- [Monitoring a Kubernetes Kapsule cluster](/tutorials/monitor-k8s-grafana/)
122-
- [Deploy an image from a private registry](/kubernetes/how-to/deploy-image-from-container-registry/)
206+
## Cleanup (optional)
207+
Once finished, you can remove the demo application and ingress controller from your cluster:
208+
```bash
209+
kubectl delete -f demo-app.yaml
210+
helm uninstall ingress-nginx -n ingress-nginx
211+
kubectl delete namespace ingress-nginx
212+
```
213+
214+
To release the flexible IP:
215+
```bash
216+
scw lb ip delete <IP-ID>
217+
```

0 commit comments

Comments
 (0)