Documentation Oracle Cloud Infrastructure

Exemple : configuration d'un contrôleur d'entrée Nginx sur un cluster

Découvrez comment configurer et utiliser un exemple de contrôleur d'entrée Nginx sur un cluster que vous avez créé à l'aide de Kubernetes Engine (OKE).

Vous pouvez configurer différents contrôleurs d'entrée open source sur des clusters créés à l'aide de Kubernetes Engine afin de gérer le trafic d'application Kubernetes.

Cette rubrique explique comment configurer un contrôleur d'entrée Nginx ainsi que le contrôle d'accès correspondant sur un cluster existant. Une fois le contrôleur d'entrée configuré, cette rubrique explique comment utiliser le contrôleur d'entrée avec un back-end hello-world d'exemple et comment vérifier que le contrôleur d'entrée fonctionne comme prévu. Si vous souhaitez continuer à utiliser l'exemple de contrôleur d'entrée, suivez les instructions de mise à niveau. Et lorsque vous n'avez plus d'utilisation pour l'exemple de contrôleur d'entrée, cette rubrique vous explique comment le supprimer.

Composants de l'exemple

Cet exemple comprend un contrôleur d'entrée et un back-end hello-world.

Composants du contrôleur d'entrée

Le contrôleur d'entrée comporte les éléments suivants :

  • Un déploiement de contrôleur d'entrée nommé ingress-nginx-controller. Le déploiement déploie une image contenant le fichier binaire du contrôleur d'entrée et de Nginx. Le fichier binaire manipule et recharge le fichier de configuration /etc/nginx/nginx.conf lorsqu'une entrée est créée dans Kubernetes. Les groupes de serveurs en amont Nginx pointent vers des services qui correspondent aux sélecteurs spécifiés.
  • Un service de contrôleur d'entrée nommé ingress-nginx-controller. Le service expose le déploiement de contrôleur d'entrée comme un service de type LoadBalancer. Kubernetes Engine utilisant un fournisseur cloud/d'intégration Oracle Cloud Infrastructure, un équilibreur de charge est créé dynamiquement avec les noeuds appropriés configurés en tant qu'ensemble de back-ends.

Composants du back-end

Le back-end hello-world comprend les éléments suivants :

  • Un déploiement back-end nommé docker-hello-world. Le déploiement gère les routages par défaut pour les vérifications d'état et les réponses 404. Pour cela, il utilise une image hello-world publique qui traite les routages minimaux requis pour un back-end par défaut.
  • Un service back-end nommé docker-hello-world-svc. Le service permet la réception du déploiement back-end par le déploiement du contrôleur d'entrée.

Configuration du contrôleur d'entrée d'exemple

Dans cette section, vous allez créer des règles d'accès pour le contrôleur entrant. Vous créez ensuite les composants du contrôleur d'entrée d'exemple et vérifierez qu'ils sont en cours d'exécution.

Création des règles d'accès pour le contrôleur d'entrée

  1. Si vous ne l'avez pas encore fait, suivez les étapes permettant de configurer le fichier de configuration Kubeconfig du cluster et (si nécessaire) de définir la variable d'environnement KUBECONFIG de sorte qu'elle pointe vers le fichier. Vous devez configurer votre propre fichier Kubeconfig. Vous ne pouvez pas accéder à un cluster à l'aide d'un fichier Kubeconfig configuré par un autre utilisateur. Reportez-vous à Configuration de l'accès à un cluster.
  2. Si votre utilisateur Oracle Cloud Infrastructure est un administrateur de location, ignorez l'étape suivante et accédez directement à Déploiement du contrôleur d'entrée et des ressources associées.

  3. Si votre utilisateur Oracle Cloud Infrastructure n'est pas un administrateur de location, dans une fenêtre de terminal, octroyez à l'utilisateur le rôle de cluster RBAC Kubernetes cluster-admin sur le cluster en saisissant la commande suivante :

    kubectl create clusterrolebinding <my-cluster-admin-binding> --clusterrole=cluster-admin --user=<user-OCID>

    où :

    • <my-cluster-admin-binding> est une chaîne de votre choix à utiliser en tant que nom pour la liaison entre l'utilisateur et le rôle de cluster RBAC Kubernetes cluster-admin. Par exemple, jdoe_clst_adm
    • <user-OCID> est l'OCID de l'utilisateur (obtenu à partir de la console ). Par exemple, ocid1.user.oc1..aaaaa...zutq (abrégé pour plus de lisibilité).

    Par exemple :

    kubectl create clusterrolebinding jdoe_clst_adm --clusterrole=cluster-admin --user=ocid1.user.oc1..aaaaa...zutq

Déploiement du contrôleur d'entrée et des ressources associées

Le déploiement du contrôleur d'entrée et des ressources associées (y compris les rôles et liaisons RBAC Kubernetes et le service de contrôleur d'entrée ingress-nginx-controller de type LoadBalancer) dépend du déploiement dans un cluster avec des noeuds gérés/autogérés ou dans un cluster avec des noeuds virtuels :

  • Noeuds gérés et noeuds autogérés

    Pour déployer le contrôleur d'entrée Nginx, exécutez la commande suivante :

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v<vnum>/deploy/static/provider/cloud/deploy.yaml

    où <vnum> est le numéro de version de la dernière version du script de déploiement de contrôleur entrant ingress-nginx-controller. Par exemple, au moment de l'écriture, la dernière version du script a le numéro de version 1.1.3, de sorte que la commande à exécuter est la suivante :

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.3/deploy/static/provider/cloud/deploy.yaml

    Pour connaître le numéro de version de la dernière version du script, reportez-vous à la documentation kubernetes/ingress-nginx sur GitHub.

  • Noeuds virtuels

    Sur les noeuds virtuels, vous devez modifier le manifeste de déploiement du contrôleur d'entrée et mettre en commentaire les contextes de sécurité fsgroup, allowprivilegeEscalation et capabilities. Pour obtenir un exemple de manifeste de déploiement modifié, reportez-vous à https://github.com/oracle-devrel/oci-oke-virtual-nodes/tree/main/ingress-nginx.

    Pour déployer le contrôleur d'entrée Nginx en fonction de ce manifeste modifié, exécutez la commande suivante :

    kubectl apply -f https://raw.githubusercontent.com/oracle-devrel/oci-oke-virtual-nodes/main/ingress-nginx/deploy.yaml

Vérification de l'exécution du service de contrôleur d'entrée ingress-nginx-controller en tant que service d'équilibreur de charge

  1. Visualisez la liste des services en cours d'exécution à l'aide la commande suivante :

    kubectl get svc -n ingress-nginx

    La sortie de la commande ci-dessus indique les services en cours d'exécution :

    
NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)                       AGE
ingress-nginx-controller   LoadBalancer   10.96.229.38   <pending>      80:30756/TCP,443:30118/TCP    1h

    L'adresse IP EXTERNAL-IP pour le service de contrôleur d'entrée ingress-nginx-controller affiche le statut <pending> jusqu'à ce que l'équilibreur de charge soit complètement créé dans Oracle Cloud Infrastructure.

  2. Répétez la commande kubectl get svc jusqu'à ce qu'une valeur EXTERNAL-IP s'affiche pour le service de contrôleur d'entrée ingress-nginx-controller :

    kubectl get svc -n ingress-nginx

    La sortie de la commande ci-dessus indique l'adresse EXTERNAL-IP du service de contrôleur d'entrée ingress-nginx-controller :

    
NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP       PORT(S)                       AGE
ingress-nginx-controller   LoadBalancer   10.96.229.38   129.146.214.219   80:30756/TCP,443:30118/TCP    1h

Création de la clé secrète TLS

Une clé secrète TLS est utilisée pour la terminaison SSL sur le contrôleur d'entrée.

  1. Générez une nouvelle clé dans un fichier. Par exemple, entrez la commande suivante :

    openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc"

    Pour générer la clé secrète de cet exemple, un certificat auto-signé est utilisé. Bien que ce type de certificat puisse être utilisé pour la réalisation de tests et la production, nous vous recommandons vivement d'utiliser un certificat signé par une autorité de certification.

    Remarque

    Sous Windows, vous devrez peut-être remplacer "/CN=nginxsvc/O=nginxsvc" par "//CN=nginxsvc\O=nginxsvc". Ce remplacement est par exemple nécessaire lorsque vous exécutez la commande openssl à partir d'un shell Git Bash.

  2. Créez la clé secrète TLS en saisissant ce qui suit :

    kubectl create secret tls tls-secret --key tls.key --cert tls.crt

Configuration du back-end d'exemple

Dans cette section, vous allez définir un déploiement et un service back-end hello-world.

Création de la définition de service docker-hello-world

  1. Créez le fichier hello-world-ingress.yaml contenant le code suivant. Ce code utilise une image hello-world publique issue de Docker Hub. Vous pouvez la remplacer par autre image de votre choix pouvant être exécutée de la même façon.

    
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-hello-world
  labels:
    app: docker-hello-world
spec:
  selector:
    matchLabels:
      app: docker-hello-world
  replicas: 3
  template:
    metadata:
      labels:
        app: docker-hello-world
    spec:
      containers:
      - name: docker-hello-world
        image: scottsbaldwin/docker-hello-world:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: docker-hello-world-svc
spec:
  selector:
    app: docker-hello-world
  ports:
    - port: 8088
      targetPort: 80
  type: ClusterIP

    Le service docker-hello-world est de type ClusterIP, et non LoadBalancer, car il sert de proxy au service de contrôleur d'entrée ingress-nginx-controller. Le service docker-hello-world n'a pas besoin d'un accès public direct. L'accès public sera acheminé de l'équilibreur de charge vers le contrôleur d'entrée, et du contrôleur d'entrée vers le service en amont.

  2. Créez le déploiement et le service hello-world sur les noeuds du cluster en exécutant la commande suivante :

    kubectl create -f hello-world-ingress.yaml

Utilisation du contrôleur d'entrée d'exemple pour accéder au back-end d'exemple

Dans cette section, vous allez créer une ressource entrante permettant d'accéder au back-end à l'aide du contrôleur d'entrée.

Création de la ressource entrante

  1. Créez le fichier ingress.yaml et remplissez-le avec le code suivant :

    
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello-world-ing
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  tls:
  - secretName: tls-secret
  rules:
  - http:
      paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: docker-hello-world-svc
              port:
                number: 8088

    Notez que l'exemple de YAML ci-dessus fonctionne avec des clusters exécutant Kubernetes version 1.19.x et ultérieure.

  2. Créez la ressource en saisissant ce qui suit :

    kubectl create -f ingress.yaml

Vérification du bon fonctionnement des composants d'exemple

Dans cette section, vous allez vérifier que tous les composants de l'exemple ont été correctement créés et fonctionnent comme prévu. Le service docker-hello-world-svc doit être exécuté en tant que service ClusterIP et le service ingress-nginx-controller doit être exécuté en tant que service LoadBalancer. Les demandes envoyées au contrôleur d'entrée doivent être acheminées vers les noeuds du cluster.

Obtention de l'adresse IP externe de l'équilibreur de charge.

Pour vérifier que le service ingress-nginx-controller est exécuté en tant que service LoadBalancer, obtenez son adresse IP externe à l'aide de la commande suivante :

kubectl get svc --all-namespaces

La sortie de la commande ci-dessus indique les services en cours d'exécution :


NAMESPACE       NAME                          TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                      AGE
default         docker-hello-world-svc      ClusterIP      10.96.83.247    <none>           8088/TCP                     16s
default         kubernetes                  ClusterIP      10.96.0.1       <none>           443/TCP                      1h
ingress-nginx   ingress-nginx-controller    LoadBalancer   10.96.229.38    129.146.214.219  80:30756/TCP,443:30118/TCP   5m			
kube-system     kube-dns                    ClusterIP      10.96.5.5       <none>           53/UDP,53/TCP                1h

Envoi des demandes cURL à l'équilibreur de charge

  1. Utilisez l'adresse IP externe du service ingress-nginx-controller (par exemple, 129.146.214.219) pour réacheminer une demande HTTP en entrant la commande suivante :

    curl -I http://129.146.214.219

    Exemple de sortie de la commande ci-dessus :

    HTTP/1.1 301 Moved Permanently
Via: 1.1 10.68.69.10 (McAfee Web Gateway 7.6.2.10.0.23236)
Date: Thu, 07 Sep 2017 15:20:16 GMT
Server: nginx/1.13.2
Location: https://129.146.214.219/
Content-Type: text/html
Content-Length: 185
Proxy-Connection: Keep-Alive
Strict-Transport-Security: max-age=15724800; includeSubDomains;

    La sortie affiche un réacheminement 301 et un en-tête d'emplacement qui suggèrent que le trafic HTTP est réacheminé vers HTTPS.

  2. Utilisez cURL sur l'URL HTTPS ou ajoutez l'option -L pour suivre automatiquement l'en-tête d'emplacement. L'option -k indique à cURL de ne pas vérifier les certificats SSL. Par exemple, entrez la commande suivante :
    curl -ikL http://129.146.214.219

    Exemple de sortie de la commande ci-dessus :

    HTTP/1.1 301 Moved Permanently
Via: 1.1 10.68.69.10 (McAfee Web Gateway 7.6.2.10.0.23236)
Date: Thu, 07 Sep 2017 15:22:29 GMT
Server: nginx/1.13.2
Location: https://129.146.214.219/
Content-Type: text/html
Content-Length: 185
Proxy-Connection: Keep-Alive
Strict-Transport-Security: max-age=15724800; includeSubDomains;

HTTP/1.0 200 Connection established

HTTP/1.1 200 OK
Server: nginx/1.13.2
Date: Thu, 07 Sep 2017 15:22:30 GMT
Content-Type: text/html
Content-Length: 71
Connection: keep-alive
Last-Modified: Thu, 07 Sep 2017 15:17:24 GMT
ETag: "59b16304-47"
Accept-Ranges: bytes
Strict-Transport-Security: max-age=15724800; includeSubDomains;

<h1>Hello webhook world from: docker-hello-world-1732906117-0ztkm</h1>

    La dernière ligne de la sortie montre le code HTML renvoyé par le pod dont le nom d'hôte est docker-hello-world-1732906117-0ztkm.

  3. Emettez la demande cURL plusieurs fois pour voir le nom d'hôte changer dans la sortie HTML. Cela prouve que l'équilibrage de charge a bien lieu :

    $ curl -k https://129.146.214.219

<h1>Hello webhook world from: docker-hello-world-1732906117-6115l</h1>

$ curl -k https://129.146.214.219

<h1>Hello webhook world from: docker-hello-world-1732906117-7r89v</h1>

$ curl -k https://129.146.214.219

<h1>Hello webhook world from: docker-hello-world-1732906117-0ztkm</h1>

Inspection de nginx.conf

Le déploiement de contrôleur d'entrée ingress-nginx-controller manipule le fichier nginx.conf dans le pod où il est en cours d'exécution.

  1. Recherchez le nom du pod exécutant le déploiement du contrôleur d'entrée ingress-nginx-controller en saisissant ce qui suit :

    kubectl get po -n ingress-nginx

    La sortie de la commande ci-dessus indique le nom du pod exécutant le déploiement du contrôleur d'entrée ingress-nginx-controller :

    
NAME                                       READY     STATUS    RESTARTS   AGE
ingress-nginx-controller-110676328-h86xg   1/1       Running   0          1h

  2. Utilisez le nom du pod exécutant le déploiement du contrôleur d'entrée ingress-nginx-controller pour afficher le contenu de nginx.conf en saisissant la commande kubectl exec suivante :

    kubectl exec -n ingress-nginx -it ingress-nginx-controller-110676328-h86xg -- cat /etc/nginx/nginx.conf

  3. Repérez proxy_pass dans la sortie. La sortie comportera un back-end par défaut et un autre back-end semblable à ce qui suit :

    proxy_pass http://upstream_balancer;

    Cela indique que Nginx envoie des demandes par proxy à un groupe de serveurs en amont appelé upstream_balancer.

  4. Localisez la définition en amont dans la sortie. Elle prend la forme suivante :

    upstream upstream_balancer {
                server 0.0.0.1:1234; # placeholder

                balancer_by_lua_block {
                        tcp_udp_balancer.balance()
                }
        }

    Le groupe de serveurs en amont utilise un proxy via Lua.

(Facultatif) Mise à niveau de l'exemple de contrôleur d'entrée

Dans cette section facultative, vous allez découvrir comment continuer à utiliser l'exemple de contrôleur d'entrée pour la gestion du trafic d'application Kubernetes, plutôt que de le supprimer immédiatement.

Si vous le souhaitez, vous pouvez continuer à utiliser l'exemple de contrôleur d'entrée que vous avez créé précédemment. Cependant, notez que de nouvelles versions de Nginx sont publiées périodiquement. Par conséquent, si vous continuez à utiliser l'exemple de contrôleur d'entrée, vous devrez régulièrement mettre à niveau la version de Nginx utilisée par le contrôleur d'entrée. En règle générale, vous devez conserver l'adresse EXTERNAL-IP existante du contrôleur d'entrée lors de la mise à niveau de Nginx.

Pour mettre à niveau le contrôleur d'entrée existant sans supprimer l'équilibreur de charge Oracle Cloud Infrastructure existant (et conserver ainsi son adresse IP EXTERNE existante), suivez les instructions de mise à niveau de Nginx sans Helm dans la documentation Nginx.

Pour déterminer l'image Nginx à référencer lors de la mise à niveau de Nginx, reportez-vous au Changelog Nginx dans la documentation Nginx.

(Facultatif) Suppression de l'exemple de contrôleur d'entrée

Dans cette section facultative, vous supprimez l'exemple de contrôleur d'entrée que vous avez créé précédemment, notamment :

  • le déploiement du contrôleur d'entrée ingress-nginx-controller
  • les rôles et liaisons RBAC Kubernetes
  • le service de contrôleur d'entrée ingress-nginx-controller de type LoadBalancer

Si vous décidez ultérieurement d'appliquer le script de déploiement du contrôleur entrant pour une deuxième fois afin de recréer l'exemple de contrôleur entrant, un service ingress-nginx-controller de type LoadBalancer est créé avec une adresse EXTERNAL-IP différente du service précédent.

Vous n'avez pas besoin de supprimer l'exemple de contrôleur d'entrée si vous souhaitez continuer à l'utiliser. Toutefois, si vous continuez à utiliser l'exemple de contrôleur d'entrée, vous devrez régulièrement mettre à niveau la version de Nginx utilisée par le contrôleur d'entrée. Reportez-vous à la section (Optional) Upgrading the Example Ingress Controller.

Suppression de l'exemple de contrôleur d'entrée

  1. Exécutez la commande suivante pour supprimer l'exemple de contrôleur d'entrée que vous avez créé précédemment :

    kubectl delete -f <deployment-script-location>

    où <deployment-script-location> est l'emplacement du script de déploiement que vous avez utilisé précédemment pour créer l'exemple de contrôleur entrant.

    Par exemple :

    kubectl delete -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.1.3/deploy/static/provider/cloud/deploy.yaml