diff --git a/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.en-gb.md b/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.en-gb.md index 3d5f9c9b2f2..8d8915327a1 100644 --- a/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.en-gb.md +++ b/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.en-gb.md @@ -254,7 +254,25 @@ Authorized values: 'octavia' = Public Cloud Load Balancer, 'iolb' = Loadbalancer - `loadbalancer.openstack.org/flavor-id` (MKS Standard only) - The UUID of the flavor used to create the loadbalancer. To get the flavors UUIDs, see the following guides: + The UUID of the flavor used to create the loadbalancer. To get the flavors UUIDs, install the [OVHcloud CLI](https://github.com/ovh/ovhcloud-cli) and run: + + ```bash + ovhcloud cloud reference loadbalancer list-flavors + ``` + + ```console + $ ovhcloud cloud reference loadbalancer list-flavors EU-WEST-PAR + ┌──────────────────────────────────────┬────────┬─────────────┐ + │ id │ name │ region │ + ├──────────────────────────────────────┼────────┼─────────────┤ + │ 222a6297-9d0b-42df-82a7-dcc83168868e │ medium │ EU-WEST-PAR │ + │ 472650bd-610d-40ed-9bb3-80e419a9fdcb │ large │ EU-WEST-PAR │ + │ 472f72ea-3e6a-4633-bf23-0591bef5c553 │ small │ EU-WEST-PAR │ + │ b753626b-12a2-4163-b277-208b4044e979 │ xl │ EU-WEST-PAR │ + └──────────────────────────────────────┴────────┴─────────────┘ + ``` + + Alternatively, you can use the OpenStack CLI: - [Prepare the environment to use the OpenStack API](/pages/public_cloud/public_cloud_cross_functional/prepare_the_environment_for_using_the_openstack_api); - [Load the OpenStack environment variables](/pages/public_cloud/public_cloud_cross_functional/loading_openstack_environment_variables). - Run `openstack loadbalancer flavor list` to get the list of flavors and their UUIDs. diff --git a/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.fr-fr.md b/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.fr-fr.md index ba1798ca6e7..f2975bf478c 100644 --- a/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.fr-fr.md +++ b/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer/guide.fr-fr.md @@ -254,7 +254,25 @@ Authorized values: 'octavia' = Public Cloud Load Balancer, 'iolb' = Loadbalancer - `loadbalancer.openstack.org/flavor-id` (MKS Standard only) - The UUID of the flavor used to create the loadbalancer. To get the flavors UUIDs, see the following guides: + The UUID of the flavor used to create the loadbalancer. To get the flavors UUIDs, install the [OVHcloud CLI](https://github.com/ovh/ovhcloud-cli) and run: + + ```bash + ovhcloud cloud reference loadbalancer list-flavors + ``` + + ```console + $ ovhcloud cloud reference loadbalancer list-flavors EU-WEST-PAR + ┌──────────────────────────────────────┬────────┬─────────────┐ + │ id │ name │ region │ + ├──────────────────────────────────────┼────────┼─────────────┤ + │ 222a6297-9d0b-42df-82a7-dcc83168868e │ medium │ EU-WEST-PAR │ + │ 472650bd-610d-40ed-9bb3-80e419a9fdcb │ large │ EU-WEST-PAR │ + │ 472f72ea-3e6a-4633-bf23-0591bef5c553 │ small │ EU-WEST-PAR │ + │ b753626b-12a2-4163-b277-208b4044e979 │ xl │ EU-WEST-PAR │ + └──────────────────────────────────────┴────────┴─────────────┘ + ``` + + Alternatively, you can use the OpenStack CLI: - [Prepare the environment to use the OpenStack API](/pages/public_cloud/public_cloud_cross_functional/prepare_the_environment_for_using_the_openstack_api); - [Load the OpenStack environment variables](/pages/public_cloud/public_cloud_cross_functional/loading_openstack_environment_variables). - Run `openstack loadbalancer flavor list` to get the list of flavors and their UUIDs. diff --git a/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/guide.en-gb.md b/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/guide.en-gb.md new file mode 100644 index 00000000000..21223f3abc5 --- /dev/null +++ b/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/guide.en-gb.md @@ -0,0 +1,410 @@ +--- +title: Migrating from NGINX Ingress Controller to Traefik on OVHcloud Managed Kubernetes +excerpt: "Learn how to migrate from NGINX Ingress Controller to Traefik on your OVHcloud MKS cluster with zero downtime" +updated: 2026-03-04 +--- + +## Objective + +The [Kubernetes NGINX Ingress Controller](https://github.com/kubernetes/ingress-nginx) project has announced its retirement in **March 2026**. This guide helps OVHcloud Managed Kubernetes Service (MKS) users migrate from NGINX Ingress Controller to [Traefik](https://traefik.io/traefik/) with zero downtime, covering OVHcloud-specific considerations. + +Traefik v3.6.2+ includes a [Kubernetes Ingress NGINX provider](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/) that automatically translates NGINX annotations into native Traefik configuration. This means your existing Ingress manifests with `ingressClassName: nginx` work immediately, without modification. + +> [!primary] +> +> This guide focuses on **OVHcloud-specific configurations**. For the complete migration procedure, refer to the official [Traefik nginx-to-traefik migration guide](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/). +> +> For a broader perspective on the transition from Ingress to Gateway API, read the OVHcloud blog post: [Moving beyond Ingress: Why should OVHcloud MKS users start looking at the Gateway API](https://blog.ovhcloud.com/moving-beyond-ingress-why-should-ovhcloud-managed-kubernetes-service-mks-users-start-looking-at-the-gateway-api/). + +> [!warning] +> +> This guide applies to MKS clusters running Kubernetes **version 1.31 or later**, which use the [Public Cloud Load Balancer](/links/public-cloud/load-balancer) (OpenStack Octavia) by default. + +## Before you begin + +This tutorial assumes that you already have: + +- A working OVHcloud Managed Kubernetes cluster (version >= 1.31) +- The NGINX Ingress Controller deployed and serving traffic +- `kubectl` and `helm` CLI tools installed with cluster admin permissions +- DNS access to update records for your services + +We recommend creating backups before starting: + +```bash +# Export all Ingress resources +kubectl get ingress --all-namespaces -o yaml > ingress-backup.yaml + +# Export NGINX ConfigMaps +kubectl get configmap --all-namespaces -l app.kubernetes.io/name=ingress-nginx -o yaml > nginx-configmaps.yaml +``` + +You should also be familiar with: + +- [Exposing applications using a Load Balancer on MKS](/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer) +- [Getting the source IP behind the LoadBalancer](/pages/public_cloud/containers_orchestration/managed_kubernetes/getting-source-ip-behind-loadbalancer) + +## OVHcloud-specific considerations + +### Load Balancer (OpenStack Octavia) + +On MKS clusters >= 1.31, the [Public Cloud Load Balancer](/links/public-cloud/load-balancer) (based on OpenStack Octavia) is the default Load Balancer. Octavia operates at **Layer 4** (TCP/UDP), meaning: + +- **TLS termination** is handled by Traefik, not by the Load Balancer +- **Layer 7 routing** (host-based, path-based) is handled by Traefik +- Octavia provides health checking, Floating IP management, and traffic distribution + +You can optionally choose the Load Balancer size using the annotation `loadbalancer.openstack.org/flavor-id`. If not specified, the default size is **small**. To list available flavors, install the [OVHcloud CLI](https://github.com/ovh/ovhcloud-cli) and run `ovhcloud cloud reference loadbalancer list-flavors `. For more details, see [Exposing applications using a Load Balancer](/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer#supported-annotations-features). + +### Proxy Protocol and source IP preservation + +To preserve the client's source IP behind the Load Balancer, you must enable **Proxy Protocol v2** between Octavia and Traefik. This requires configuration on both sides: + +**On the Load Balancer side** (Service annotation): + +```yaml +annotations: + loadbalancer.openstack.org/proxy-protocol: "v2" +``` + +**On the Traefik side** (Helm values), you must configure Traefik to accept Proxy Protocol and trust the Load Balancer IPs: + +- **Public network clusters**: Use the egress IPs from the Load Balancer annotation: + +```bash +kubectl get svc ingress-nginx-controller -n ingress-nginx \ + -o jsonpath="{.metadata.annotations.lb\.k8s\.ovh\.net/egress-ips}" +``` + +- **Private network clusters**: Use your subnet CIDR range (e.g., `10.0.0.0/20`) + +You must also set `externalTrafficPolicy: Local` on the Traefik Service to prevent source IP masquerading through inter-node SNAT. + +### CNI considerations + +| MKS Plan | CNI | Notes | +|----------|-----|-------| +| Free | Canal (Flannel + Calico) | Standard Kubernetes NetworkPolicies | +| Standard | Cilium (eBPF) | CiliumNetworkPolicy available, kube-proxy replaced | + +If you have NetworkPolicies targeting NGINX Ingress pods (labels, ports), you will need to update them to match Traefik's labels (`app.kubernetes.io/name: traefik`) and ports. + +## Step 1 - Install Traefik alongside NGINX + +Add the Traefik Helm repository: + +```bash +helm repo add traefik https://traefik.github.io/charts +helm repo update +``` + +Create a `traefik-values.yaml` file adapted for OVHcloud MKS: + +#### a. Public network clusters + +```yaml +providers: + kubernetesIngressNginx: + enabled: true + +service: + externalTrafficPolicy: Local + annotations: + loadbalancer.openstack.org/proxy-protocol: "v2" + loadbalancer.openstack.org/keep-floatingip: "true" + +ports: + web: + proxyProtocol: + trustedIPs: + - "aaa.aaa.aaa.aaa/32" # Replace with your egress IPs + - "bbb.bbb.bbb.bbb/32" + websecure: + proxyProtocol: + trustedIPs: + - "aaa.aaa.aaa.aaa/32" # Replace with your egress IPs + - "bbb.bbb.bbb.bbb/32" + +deployment: + replicas: 2 + +affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchLabels: + app.kubernetes.io/name: traefik + topologyKey: kubernetes.io/hostname + +podDisruptionBudget: + enabled: true + minAvailable: 1 +``` + +#### b. Private network clusters + +```yaml +providers: + kubernetesIngressNginx: + enabled: true + +service: + externalTrafficPolicy: Local + annotations: + loadbalancer.openstack.org/proxy-protocol: "v2" + loadbalancer.openstack.org/keep-floatingip: "true" + +ports: + web: + proxyProtocol: + trustedIPs: + - "10.0.0.0/20" # Replace with your subnet CIDR range + websecure: + proxyProtocol: + trustedIPs: + - "10.0.0.0/20" # Replace with your subnet CIDR range + +deployment: + replicas: 2 + +affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchLabels: + app.kubernetes.io/name: traefik + topologyKey: kubernetes.io/hostname + +podDisruptionBudget: + enabled: true + minAvailable: 1 +``` + +Install Traefik: + +```bash +helm upgrade --install traefik traefik/traefik \ + --namespace traefik --create-namespace \ + --values traefik-values.yaml +``` + +Verify both controllers are running: + +```bash +kubectl get pods -n ingress-nginx +kubectl get pods -n traefik +kubectl get svc -n ingress-nginx ingress-nginx-controller +kubectl get svc -n traefik traefik +``` + +> [!warning] +> +> The key configuration `providers.kubernetesIngressNginx.enabled: true` tells Traefik to watch for Ingress resources with `ingressClassName: nginx` and automatically translate NGINX annotations into native Traefik configuration. This requires Traefik **v3.6.2 or later**. + +## Step 2 - Verify Traefik handles traffic + +Get the LoadBalancer IPs for both controllers: + +```bash +NGINX_IP=$(kubectl get svc -n ingress-nginx ingress-nginx-controller \ + -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +TRAEFIK_IP=$(kubectl get svc -n traefik traefik \ + -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +echo "NGINX IP: $NGINX_IP" +echo "Traefik IP: $TRAEFIK_IP" +``` + +Test your application through both controllers using `curl --connect-to` to bypass DNS: + +```bash +FQDN=myapp.example.com + +# Test via NGINX +curl --connect-to "${FQDN}:80:${NGINX_IP}:80" "http://${FQDN}" + +# Test via Traefik +curl --connect-to "${FQDN}:80:${TRAEFIK_IP}:80" "http://${FQDN}" +``` + +Both commands should return the same response. Also verify that source IP is correctly preserved in the `X-Real-IP` or `X-Forwarded-For` headers. + +Check Traefik logs for Ingress discovery: + +```bash +kubectl logs -n traefik deployment/traefik | grep -i "ingress" +``` + +## Step 3 - Shift traffic to Traefik (DNS-based) + +The recommended approach is a DNS-based migration: + +1. **Add the Traefik IP** to your DNS records alongside the NGINX IP (round-robin) +2. **Monitor traffic** on both controllers to ensure Traefik handles requests correctly +3. **Remove the NGINX IP** from your DNS records +4. **Wait 24-48 hours** for DNS cache expiration before proceeding to the next step + +> [!warning] +> +> Some ISPs ignore DNS TTL values, caching records longer than specified. Keep NGINX running for at least 24-48 hours after removing it from DNS to avoid dropping traffic. + +We recommend reducing your DNS TTL to 300 seconds (5 minutes) before starting the migration. For detailed DNS switch instructions, see [How to perform a DNS switch](/pages/public_cloud/containers_orchestration/managed_kubernetes/migrate-loadbalancer-iolb-to-octavia#dns-switch). + +## Step 4 - Retain the LoadBalancer Floating IP (OVHcloud-specific) + +If you want Traefik to use the same IP as NGINX (to avoid DNS changes), follow this procedure: + +1. Ensure the `keep-floatingip` annotation is set on **both** services: + +```bash +kubectl annotate svc -n ingress-nginx ingress-nginx-controller \ + loadbalancer.openstack.org/keep-floatingip="true" +kubectl annotate svc -n traefik traefik \ + loadbalancer.openstack.org/keep-floatingip="true" +``` + +2. Ensure Traefik is receiving traffic (via its own IP or DNS round-robin) + +3. Delete the NGINX LoadBalancer service to release the Floating IP: + +```bash +kubectl delete svc -n ingress-nginx ingress-nginx-controller +``` + +4. Update `traefik-values.yaml` to claim the released Floating IP: + +```yaml +service: + spec: + loadBalancerIP: "" +``` + +5. Upgrade Traefik: + +```bash +helm upgrade traefik traefik/traefik \ + --namespace traefik \ + --values traefik-values.yaml +``` + +6. Verify Traefik claimed the IP: + +```bash +kubectl get svc -n traefik traefik +``` + +## Step 5 - Uninstall NGINX Ingress Controller + +### Preserve the IngressClass + +The `nginx` IngressClass must survive the NGINX uninstallation for Traefik to continue discovering your Ingress resources. + +If NGINX was installed via Helm, add the preservation annotation: + +```bash +helm upgrade ingress-nginx ingress-nginx \ + --repo https://kubernetes.github.io/ingress-nginx \ + --namespace ingress-nginx \ + --reuse-values \ + --set-json 'controller.ingressClassResource.annotations={"helm.sh/resource-policy": "keep"}' +``` + +> [!warning] +> +> The `--reuse-values` flag is critical - it preserves all your existing NGINX configuration during this annotation update. + +### Delete admission webhooks + +```bash +kubectl delete validatingwebhookconfiguration ingress-nginx-admission +kubectl delete mutatingwebhookconfiguration ingress-nginx-admission --ignore-not-found +``` + +### Uninstall NGINX + +```bash +helm uninstall ingress-nginx -n ingress-nginx +``` + +### Verify the IngressClass is preserved + +```bash +kubectl get ingressclass nginx +``` + +You should see the `nginx` IngressClass still present. + +### Clean up + +```bash +kubectl delete namespace ingress-nginx +``` + +## Next steps: Gateway API + +While Traefik with the NGINX Ingress provider is an excellent immediate solution, the long-term recommendation is to migrate to the **Kubernetes Gateway API**. Traefik natively supports Gateway API resources (HTTPRoute, TLSRoute, GRPCRoute, TCPRoute). + +The recommended migration path is: + +1. **NGINX Ingress** (current) -> **Traefik with NGINX provider** (this guide) -> **Traefik with Gateway API** + +For more details on Gateway API with OVHcloud MKS, read the blog post: [Moving beyond Ingress: Why should OVHcloud MKS users start looking at the Gateway API](https://blog.ovhcloud.com/moving-beyond-ingress-why-should-ovhcloud-managed-kubernetes-service-mks-users-start-looking-at-the-gateway-api/). + +## Troubleshooting + +### Ingresses not discovered by Traefik + +```bash +# Verify IngressClass exists +kubectl get ingressclass nginx + +# Check Traefik provider configuration +kubectl logs -n traefik deployment/traefik | grep -i "nginx\|ingress" + +# Verify Ingress has correct ingressClassName +kubectl get ingress -o yaml | grep ingressClassName +``` + +### Source IP not preserved + +- Verify Proxy Protocol is enabled on the Service: `loadbalancer.openstack.org/proxy-protocol: "v2"` +- Verify `externalTrafficPolicy: Local` is set on the Traefik Service +- Verify Traefik's `proxyProtocol.trustedIPs` match your Load Balancer egress IPs (public clusters) or subnet CIDR (private clusters) +- Check the `X-Real-IP` and `X-Forwarded-For` headers in your application responses + +### LoadBalancer IP not assigned + +```bash +# Check service status +kubectl describe svc -n traefik traefik + +# Check for events +kubectl get events -n traefik --sort-by='.lastTimestamp' +``` + +Verify that the Floating IP you are trying to claim is not still allocated to another service. + +### TLS certificates not working + +Traefik terminates TLS using the secrets referenced in your Ingress `spec.tls` entries. Ensure that: + +- TLS secrets exist in the same namespace as the Ingress +- Secrets contain valid `tls.crt` and `tls.key` data + +```bash +kubectl get secrets -n +kubectl get secret -n -o yaml +``` + +## Go further + +- Official Traefik migration guide: [Migrating from NGINX to Traefik](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/) +- OVHcloud blog: [Moving beyond Ingress](https://blog.ovhcloud.com/moving-beyond-ingress-why-should-ovhcloud-managed-kubernetes-service-mks-users-start-looking-at-the-gateway-api/) +- [Exposing applications using a Load Balancer on MKS](/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer) +- [Getting the source IP behind the LoadBalancer](/pages/public_cloud/containers_orchestration/managed_kubernetes/getting-source-ip-behind-loadbalancer) +- [Traefik HTTP Middlewares](https://doc.traefik.io/traefik/middlewares/overview/) (replacement for NGINX annotations) + +Visit our dedicated Discord channel: . Ask questions, provide feedback and interact directly with the team that builds our Container and Orchestration services. + +If you need training or technical assistance to implement our solutions, contact your sales representative or click on [this link](/links/professional-services) to get a quote and ask our Professional Services experts for a custom analysis of your project. + +Join our [community of users](/links/community). diff --git a/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/guide.fr-fr.md b/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/guide.fr-fr.md new file mode 100644 index 00000000000..6bd4ff563f6 --- /dev/null +++ b/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/guide.fr-fr.md @@ -0,0 +1,410 @@ +--- +title: Migrer de NGINX Ingress Controller vers Traefik sur OVHcloud Managed Kubernetes +excerpt: "Apprenez comment migrer de NGINX Ingress Controller vers Traefik sur votre cluster MKS OVHcloud sans interruption de service" +updated: 2026-03-04 +--- + +## Objectif + +Le projet [Kubernetes NGINX Ingress Controller](https://github.com/kubernetes/ingress-nginx) a annonce sa fin de vie en **mars 2026**. Ce guide aide les utilisateurs du service OVHcloud Managed Kubernetes (MKS) a migrer de NGINX Ingress Controller vers [Traefik](https://traefik.io/traefik/) sans interruption de service, en couvrant les specificites OVHcloud. + +Traefik v3.6.2+ inclut un [provider Kubernetes Ingress NGINX](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/) qui traduit automatiquement les annotations NGINX en configuration Traefik native. Vos manifestes Ingress existants avec `ingressClassName: nginx` fonctionnent immediatement, sans modification. + +> [!primary] +> +> Ce guide se concentre sur les **configurations specifiques a OVHcloud**. Pour la procedure de migration complete, consultez le guide officiel [Traefik nginx-to-traefik](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/). +> +> Pour une perspective plus large sur la transition d'Ingress vers Gateway API, lisez l'article de blog OVHcloud : [Moving beyond Ingress: Why should OVHcloud MKS users start looking at the Gateway API](https://blog.ovhcloud.com/moving-beyond-ingress-why-should-ovhcloud-managed-kubernetes-service-mks-users-start-looking-at-the-gateway-api/). + +> [!warning] +> +> Ce guide concerne les clusters MKS utilisant Kubernetes **version 1.31 ou superieure**, qui utilisent le [Public Cloud Load Balancer](/links/public-cloud/load-balancer) (OpenStack Octavia) par defaut. + +## Avant de commencer + +Ce tutoriel suppose que vous disposez deja de : + +- Un cluster OVHcloud Managed Kubernetes fonctionnel (version >= 1.31) +- Le NGINX Ingress Controller deploye et en service +- Les outils CLI `kubectl` et `helm` installes avec les permissions d'administration du cluster +- Un acces DNS pour mettre a jour les enregistrements de vos services + +Nous recommandons de creer des sauvegardes avant de commencer : + +```bash +# Exporter toutes les ressources Ingress +kubectl get ingress --all-namespaces -o yaml > ingress-backup.yaml + +# Exporter les ConfigMaps NGINX +kubectl get configmap --all-namespaces -l app.kubernetes.io/name=ingress-nginx -o yaml > nginx-configmaps.yaml +``` + +Vous devriez egalement etre familier avec : + +- [Exposer des applications avec un Load Balancer sur MKS](/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer) +- [Obtenir l'IP source derriere le LoadBalancer](/pages/public_cloud/containers_orchestration/managed_kubernetes/getting-source-ip-behind-loadbalancer) + +## Specificites OVHcloud + +### Load Balancer (OpenStack Octavia) + +Sur les clusters MKS >= 1.31, le [Public Cloud Load Balancer](/links/public-cloud/load-balancer) (base sur OpenStack Octavia) est le Load Balancer par defaut. Octavia opere au **niveau 4** (TCP/UDP), ce qui signifie : + +- La **terminaison TLS** est geree par Traefik, pas par le Load Balancer +- Le **routage niveau 7** (par hote, par chemin) est gere par Traefik +- Octavia fournit le health checking, la gestion des Floating IPs et la distribution du trafic + +Vous pouvez optionnellement choisir la taille du Load Balancer avec l'annotation `loadbalancer.openstack.org/flavor-id`. Si non specifiee, la taille par defaut est **small**. Pour lister les flavors disponibles, installez la [CLI OVHcloud](https://github.com/ovh/ovhcloud-cli) et executez `ovhcloud cloud reference loadbalancer list-flavors `. Pour plus de details, consultez [Exposer des applications avec un Load Balancer](/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer#supported-annotations-features). + +### Proxy Protocol et preservation de l'IP source + +Pour preserver l'IP source du client derriere le Load Balancer, vous devez activer le **Proxy Protocol v2** entre Octavia et Traefik. Cela necessite une configuration des deux cotes : + +**Cote Load Balancer** (annotation du Service) : + +```yaml +annotations: + loadbalancer.openstack.org/proxy-protocol: "v2" +``` + +**Cote Traefik** (valeurs Helm), vous devez configurer Traefik pour accepter le Proxy Protocol et faire confiance aux IPs du Load Balancer : + +- **Clusters reseau public** : Utilisez les IPs d'egress de l'annotation du Load Balancer : + +```bash +kubectl get svc ingress-nginx-controller -n ingress-nginx \ + -o jsonpath="{.metadata.annotations.lb\.k8s\.ovh\.net/egress-ips}" +``` + +- **Clusters reseau prive** : Utilisez le CIDR de votre sous-reseau (ex : `10.0.0.0/20`) + +Vous devez egalement definir `externalTrafficPolicy: Local` sur le Service Traefik pour empecher le masquage de l'IP source via le SNAT inter-noeuds. + +### Considerations CNI + +| Plan MKS | CNI | Notes | +|----------|-----|-------| +| Free | Canal (Flannel + Calico) | NetworkPolicies Kubernetes standard | +| Standard | Cilium (eBPF) | CiliumNetworkPolicy disponible, kube-proxy remplace | + +Si vous avez des NetworkPolicies ciblant les pods NGINX Ingress (labels, ports), vous devrez les mettre a jour pour correspondre aux labels Traefik (`app.kubernetes.io/name: traefik`) et a ses ports. + +## Etape 1 - Installer Traefik aux cotes de NGINX + +Ajoutez le depot Helm Traefik : + +```bash +helm repo add traefik https://traefik.github.io/charts +helm repo update +``` + +Creez un fichier `traefik-values.yaml` adapte a OVHcloud MKS : + +#### a. Clusters reseau public + +```yaml +providers: + kubernetesIngressNginx: + enabled: true + +service: + externalTrafficPolicy: Local + annotations: + loadbalancer.openstack.org/proxy-protocol: "v2" + loadbalancer.openstack.org/keep-floatingip: "true" + +ports: + web: + proxyProtocol: + trustedIPs: + - "aaa.aaa.aaa.aaa/32" # Remplacez par vos IPs d'egress + - "bbb.bbb.bbb.bbb/32" + websecure: + proxyProtocol: + trustedIPs: + - "aaa.aaa.aaa.aaa/32" # Remplacez par vos IPs d'egress + - "bbb.bbb.bbb.bbb/32" + +deployment: + replicas: 2 + +affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchLabels: + app.kubernetes.io/name: traefik + topologyKey: kubernetes.io/hostname + +podDisruptionBudget: + enabled: true + minAvailable: 1 +``` + +#### b. Clusters reseau prive + +```yaml +providers: + kubernetesIngressNginx: + enabled: true + +service: + externalTrafficPolicy: Local + annotations: + loadbalancer.openstack.org/proxy-protocol: "v2" + loadbalancer.openstack.org/keep-floatingip: "true" + +ports: + web: + proxyProtocol: + trustedIPs: + - "10.0.0.0/20" # Remplacez par le CIDR de votre sous-reseau + websecure: + proxyProtocol: + trustedIPs: + - "10.0.0.0/20" # Remplacez par le CIDR de votre sous-reseau + +deployment: + replicas: 2 + +affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchLabels: + app.kubernetes.io/name: traefik + topologyKey: kubernetes.io/hostname + +podDisruptionBudget: + enabled: true + minAvailable: 1 +``` + +Installez Traefik : + +```bash +helm upgrade --install traefik traefik/traefik \ + --namespace traefik --create-namespace \ + --values traefik-values.yaml +``` + +Verifiez que les deux controleurs fonctionnent : + +```bash +kubectl get pods -n ingress-nginx +kubectl get pods -n traefik +kubectl get svc -n ingress-nginx ingress-nginx-controller +kubectl get svc -n traefik traefik +``` + +> [!warning] +> +> La configuration cle `providers.kubernetesIngressNginx.enabled: true` indique a Traefik de surveiller les ressources Ingress avec `ingressClassName: nginx` et de traduire automatiquement les annotations NGINX en configuration Traefik native. Cela necessite Traefik **v3.6.2 ou superieur**. + +## Etape 2 - Verifier que Traefik gere le trafic + +Recuperez les IPs des LoadBalancers des deux controleurs : + +```bash +NGINX_IP=$(kubectl get svc -n ingress-nginx ingress-nginx-controller \ + -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +TRAEFIK_IP=$(kubectl get svc -n traefik traefik \ + -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +echo "NGINX IP: $NGINX_IP" +echo "Traefik IP: $TRAEFIK_IP" +``` + +Testez votre application via les deux controleurs en utilisant `curl --connect-to` pour contourner le DNS : + +```bash +FQDN=myapp.example.com + +# Test via NGINX +curl --connect-to "${FQDN}:80:${NGINX_IP}:80" "http://${FQDN}" + +# Test via Traefik +curl --connect-to "${FQDN}:80:${TRAEFIK_IP}:80" "http://${FQDN}" +``` + +Les deux commandes doivent retourner la meme reponse. Verifiez egalement que l'IP source est correctement preservee dans les en-tetes `X-Real-IP` ou `X-Forwarded-For`. + +Verifiez les logs Traefik pour la decouverte des Ingress : + +```bash +kubectl logs -n traefik deployment/traefik | grep -i "ingress" +``` + +## Etape 3 - Basculer le trafic vers Traefik (par DNS) + +L'approche recommandee est une migration basee sur le DNS : + +1. **Ajoutez l'IP Traefik** a vos enregistrements DNS aux cotes de l'IP NGINX (round-robin) +2. **Surveillez le trafic** sur les deux controleurs pour vous assurer que Traefik traite correctement les requetes +3. **Retirez l'IP NGINX** de vos enregistrements DNS +4. **Attendez 24 a 48 heures** pour l'expiration des caches DNS avant de passer a l'etape suivante + +> [!warning] +> +> Certains FAI ignorent les valeurs TTL du DNS, mettant en cache les enregistrements plus longtemps que specifie. Gardez NGINX en fonctionnement pendant au moins 24 a 48 heures apres l'avoir retire du DNS pour eviter de perdre du trafic. + +Nous recommandons de reduire votre TTL DNS a 300 secondes (5 minutes) avant de commencer la migration. Pour des instructions detaillees sur le changement DNS, consultez [Comment effectuer un changement DNS](/pages/public_cloud/containers_orchestration/managed_kubernetes/migrate-loadbalancer-iolb-to-octavia#dns-switch). + +## Etape 4 - Conserver la Floating IP du LoadBalancer (specifique OVHcloud) + +Si vous souhaitez que Traefik utilise la meme IP que NGINX (pour eviter les changements DNS), suivez cette procedure : + +1. Assurez-vous que l'annotation `keep-floatingip` est definie sur **les deux** services : + +```bash +kubectl annotate svc -n ingress-nginx ingress-nginx-controller \ + loadbalancer.openstack.org/keep-floatingip="true" +kubectl annotate svc -n traefik traefik \ + loadbalancer.openstack.org/keep-floatingip="true" +``` + +2. Assurez-vous que Traefik recoit du trafic (via sa propre IP ou le round-robin DNS) + +3. Supprimez le service LoadBalancer de NGINX pour liberer la Floating IP : + +```bash +kubectl delete svc -n ingress-nginx ingress-nginx-controller +``` + +4. Mettez a jour `traefik-values.yaml` pour reclamer la Floating IP liberee : + +```yaml +service: + spec: + loadBalancerIP: "" +``` + +5. Mettez a jour Traefik : + +```bash +helm upgrade traefik traefik/traefik \ + --namespace traefik \ + --values traefik-values.yaml +``` + +6. Verifiez que Traefik a reclame l'IP : + +```bash +kubectl get svc -n traefik traefik +``` + +## Etape 5 - Desinstaller NGINX Ingress Controller + +### Preserver l'IngressClass + +L'IngressClass `nginx` doit survivre a la desinstallation de NGINX pour que Traefik continue a decouvrir vos ressources Ingress. + +Si NGINX a ete installe via Helm, ajoutez l'annotation de preservation : + +```bash +helm upgrade ingress-nginx ingress-nginx \ + --repo https://kubernetes.github.io/ingress-nginx \ + --namespace ingress-nginx \ + --reuse-values \ + --set-json 'controller.ingressClassResource.annotations={"helm.sh/resource-policy": "keep"}' +``` + +> [!warning] +> +> Le flag `--reuse-values` est critique - il preserve toute votre configuration NGINX existante lors de cette mise a jour d'annotation. + +### Supprimer les admission webhooks + +```bash +kubectl delete validatingwebhookconfiguration ingress-nginx-admission +kubectl delete mutatingwebhookconfiguration ingress-nginx-admission --ignore-not-found +``` + +### Desinstaller NGINX + +```bash +helm uninstall ingress-nginx -n ingress-nginx +``` + +### Verifier que l'IngressClass est preservee + +```bash +kubectl get ingressclass nginx +``` + +L'IngressClass `nginx` devrait toujours etre presente. + +### Nettoyage + +```bash +kubectl delete namespace ingress-nginx +``` + +## Prochaines etapes : Gateway API + +Bien que Traefik avec le provider NGINX Ingress soit une excellente solution immediate, la recommandation a long terme est de migrer vers la **Kubernetes Gateway API**. Traefik supporte nativement les ressources Gateway API (HTTPRoute, TLSRoute, GRPCRoute, TCPRoute). + +Le parcours de migration recommande est : + +1. **NGINX Ingress** (actuel) -> **Traefik avec provider NGINX** (ce guide) -> **Traefik avec Gateway API** + +Pour plus de details sur Gateway API avec OVHcloud MKS, lisez l'article de blog : [Moving beyond Ingress: Why should OVHcloud MKS users start looking at the Gateway API](https://blog.ovhcloud.com/moving-beyond-ingress-why-should-ovhcloud-managed-kubernetes-service-mks-users-start-looking-at-the-gateway-api/). + +## Depannage + +### Les Ingresses ne sont pas decouverts par Traefik + +```bash +# Verifier que l'IngressClass existe +kubectl get ingressclass nginx + +# Verifier la configuration du provider Traefik +kubectl logs -n traefik deployment/traefik | grep -i "nginx\|ingress" + +# Verifier que l'Ingress a le bon ingressClassName +kubectl get ingress -o yaml | grep ingressClassName +``` + +### L'IP source n'est pas preservee + +- Verifiez que le Proxy Protocol est active sur le Service : `loadbalancer.openstack.org/proxy-protocol: "v2"` +- Verifiez que `externalTrafficPolicy: Local` est defini sur le Service Traefik +- Verifiez que les `proxyProtocol.trustedIPs` de Traefik correspondent aux IPs d'egress de votre Load Balancer (clusters publics) ou au CIDR de votre sous-reseau (clusters prives) +- Verifiez les en-tetes `X-Real-IP` et `X-Forwarded-For` dans les reponses de votre application + +### La Floating IP du LoadBalancer n'est pas assignee + +```bash +# Verifier le statut du service +kubectl describe svc -n traefik traefik + +# Verifier les evenements +kubectl get events -n traefik --sort-by='.lastTimestamp' +``` + +Verifiez que la Floating IP que vous essayez de reclamer n'est pas encore allouee a un autre service. + +### Les certificats TLS ne fonctionnent pas + +Traefik termine le TLS en utilisant les secrets references dans les entrees `spec.tls` de vos Ingress. Assurez-vous que : + +- Les secrets TLS existent dans le meme namespace que l'Ingress +- Les secrets contiennent des donnees `tls.crt` et `tls.key` valides + +```bash +kubectl get secrets -n +kubectl get secret -n -o yaml +``` + +## Aller plus loin + +- Guide officiel de migration Traefik : [Migrating from NGINX to Traefik](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/) +- Blog OVHcloud : [Moving beyond Ingress](https://blog.ovhcloud.com/moving-beyond-ingress-why-should-ovhcloud-managed-kubernetes-service-mks-users-start-looking-at-the-gateway-api/) +- [Exposer des applications avec un Load Balancer sur MKS](/pages/public_cloud/containers_orchestration/managed_kubernetes/expose_your_applications_using_a_load_balancer) +- [Obtenir l'IP source derriere le LoadBalancer](/pages/public_cloud/containers_orchestration/managed_kubernetes/getting-source-ip-behind-loadbalancer) +- [Middlewares HTTP Traefik](https://doc.traefik.io/traefik/middlewares/overview/) (remplacement des annotations NGINX) + +Retrouvez-nous sur notre channel Discord dedie : . Posez des questions, donnez votre avis et interagissez directement avec l'equipe qui construit nos services Container et Orchestration. + +Si vous avez besoin d'une formation ou d'une assistance technique pour mettre en oeuvre nos solutions, contactez votre commercial ou cliquez sur [ce lien](/links/professional-services) pour obtenir un devis et demander a nos experts Professional Services une analyse personnalisee de votre projet. + +Rejoignez notre [communaute d'utilisateurs](/links/community). diff --git a/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/meta.yaml b/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/meta.yaml new file mode 100644 index 00000000000..6772375a949 --- /dev/null +++ b/pages/public_cloud/containers_orchestration/managed_kubernetes/migrating-nginx-to-traefik/meta.yaml @@ -0,0 +1,3 @@ +id: 2bf42a11-73a4-4b07-a526-8cb170390dff +full_slug: public-cloud-kubernetes-migrating-nginx-to-traefik +reference_category: public-cloud-containers-orchestration-managed-kubernetes-k8s-configuration-traffic-management