Tutoriel : Configurer les rapports d’utilisation NGINX

NGINX Plus R31 introduit un moyen plus simple et plus efficace de signaler l'utilisation de NGINX Plus. L'intégration native des rapports d'utilisation élimine le besoin d'un agent NGINX distinct, ce qui rend le processus de création de rapports transparent et sans tracas pour les clients du programme de consommation flexible (FCP) de F5 et pour les clients non-FCP disposant d'un abonnement à durée déterminée. Grâce à cette fonctionnalité intégrée directement dans NGINX Plus, les instances peuvent communiquer périodiquement les informations d'utilisation nécessaires au gestionnaire d'instances NGINX, sans aucun impact sur les performances. Cette fonctionnalité est disponible pour les machines virtuelles et les contrôleurs d'entrée NGINX, mais ce blog se concentre sur les instances NGINX Plus. Vous pouvez trouver un guide sur la création de rapports sur le contrôleur d'entrée NGINX au gestionnaire d'instances NGINX ici .

En simplifiant la configuration, en proposant des options de personnalisation et en fournissant des méthodes de secours, nous visons à faire du reporting d'utilisation requis un processus efficace et adaptable pour que les clients puissent mettre en œuvre et maintenir la conformité avec FCP. Pour les clients qui ne sont pas encore sur R31 ou qui ne prévoient pas de mettre à niveau, des méthodes alternatives pour activer les rapports d'utilisation sont disponibles, soit en installant l'agent NGINX, soit en configurant des contrôles d'intégrité HTTP.

Note: Pour signaler l’utilisation de NGINX Plus, vous devez installer NGINX Instance Manager sur un hôte dédié. Reportez-vous au guide d'installation pour en savoir plus sur les différentes méthodes d'installation.

Vous pouvez choisir entre trois méthodes pour signaler les instances NGINX Plus à F5.

• Utilisateurs de NGINX Plus R31 — Configuration des rapports d'utilisation natifs de NGINX
• Utilisateurs R31 ou pré-R31 — Installation de l'agent NGINX
• Utilisateurs pré-R31 — Configuration du contrôle d'intégrité HTTP pour NGINX Plus

Explorons-les un par un :

Configurer les rapports d'utilisation natifs de NGINX

Lors de l'installation, NGINX Plus établit une connexion automatisée au gestionnaire d'instances NGINX via l'entrée DNS par défaut « nginx-mgmt.local ». Par défaut, toutes les 30 minutes, NGINX Plus communique avec le gestionnaire d'instances et envoie les informations d'utilisation. Si vous devez modifier l'entrée DNS du gestionnaire d'instances ou modifier l'intervalle de connexion par défaut pour mieux répondre à vos besoins, ajoutez le bloc mgmt{} à votre configuration NGINX. De plus, il est livré avec d'autres directives par défaut, telles que le fichier UUID, mTLS, le résolveur DNS, l'intervalle d'utilisation et le point de terminaison usage_report. Pour une liste complète des directives personnalisables, reportez-vous à la documentation complète de mgmtmodule . Avec le module ngx_mgmt_module , vous pouvez facilement personnaliser les directives, offrant une plus grande flexibilité et commodité.

Les sections suivantes expliquent comment configurer cette fonctionnalité pour votre environnement.

Configurer NGINX Plus

1. Il est conseillé d'utiliser mTLS pour améliorer la sécurité de votre système. Vous pouvez y parvenir en générant un certificat, une clé et un certificat de clé CA pour l’instance NGINX Plus et NGINX Instance Manager. Pour plus d'informations sur la façon de générer des clés, cliquez ici .
2. Spécifiez le chemin d'accès au certificat client et au fichier de clé privée dans le bloc de gestion du fichier de configuration nginx.conf.

   		
      mgmt {
             ssl_protocols TLSv1.2 TLSv1.3;
             ssl_ciphers DEFAULT;
             ssl_certificate          /home/ubuntu/agent.crt;
             ssl_certificate_key      /home/ubuntu/agent.key
          }
   

3. Pour un processus d’authentification sécurisé et fiable, spécifiez le chemin d’accès à la chaîne CA pour valider l’authenticité des certificats.

   
      mgmt {
             ssl_trusted_certificate  /home/ubuntu/ca.pem;
             ssl_verify               on;
             ssl_verify_depth         2;
          }
   

4. Pour les résolveurs DNS personnalisés, spécifiez l'adresse du résolveur dans le bloc mgmt{} à l'aide de la directive resolver.

   
      mgmt {
             resolver 3.X.X.X;
          }
   

5. Pour configurer un nom de domaine complet personnalisé pour NGINX Instance Manager, spécifiez le nom de domaine complet dans la directive usage_report . Ensuite, ajoutez un enregistrement A à votre DNS local qui associe le nom d’hôte à l’adresse IP de NGINX Instance Manager.

   
      mgmt {
             resolver 3.X.X.X;
             usage_report endpoint=nms.local interval=15m;
          }
   

Exemple de configuration NGINX Plus :

  mgmt {
         usage_report endpoint=nms.local interval=30m;
         resolver 3.X.X.X;
         ssl_protocols TLSv1.2 TLSv1.3;
         ssl_ciphers DEFAULT;
         ssl_certificate          /home/ubuntu/agent.crt;
         ssl_certificate_key      /home/ubuntu/agent.key;

         ssl_trusted_certificate  /home/ubuntu/ca.pem;
         ssl_verify               on;
         ssl_verify_depth         2;
     }

Enregistrez la configuration NGINX et rechargez NGINX Plus.

sudo nginx -s recharger

Configurer le gestionnaire d'instances NGINX

Ajoutez le certificat SSL dans /etc/nginx/conf.d/nms-HTTP.conf à l'intérieur du bloc serveur. Cliquez ici pour savoir comment configurer un certificat SSL sur le serveur NGINX Management Suite.

server {
    listen 443 ssl http2;
    root /var/www/nms;
    server_name _;
    ssl_protocols       TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_certificate         /etc/nms/certs/server.crt;
    ssl_certificate_key     /etc/nms/certs/server.key;
    ssl_client_certificate  /etc/nms/certs/ca.pem;
    ssl_verify_client on;
 }

Pour afficher l'utilisation de NGINX Plus, connectez-vous à NGINX Management Suite sur votre navigateur et accédez au module NGINX Instance Manager. Ensuite, sélectionnez l’onglet NGINX Plus situé en bas à gauche de la page.

Regardez ce didacticiel vidéo avec des instructions étape par étape :

Messages du journal d'erreurs

Voici une liste de messages d'erreur à résoudre dans l'instance NGINX Plus lorsque vous ne parvenez pas à voir les données d'utilisation dans le gestionnaire d'instances NGINX : Voici quelques exemples de messages d’erreur :

• Échecs du résolveur dynamique : Échec de la résolution du résolveur DNS.

  2024/04/02 04:02:10 [error] 574079#574079: recv() failed (111: Connection refused) while resolving, resolver: 3.17.128.165:53
  2024/04/02 04:02:35 [warn] 574079#574079: usage report: nginx-mgmt.locals could not be resolved (110: Operation timed out)
  

• Échecs du résolveur système : Échec de la résolution du nom d'hôte du gestionnaire d'instances NGINX

  2024/04/02 13:20:44 [info] 103888#0: usage report: host not found in resolver "nginx-mgmt.local"
  

• Échecs de connexion SSL : Impossible de vérifier ou certificat SSL expiré.

  2024/04/02 13:13:50 [warn] 103877#0: usage report: peer SSL connection failed
  

• Échecs de communication entre pairs : Échec de la connexion au gestionnaire d'instances NGINX.

  2024/04/02 13:15:25 [warn] 103877#0: usage report: peer connection failed (-1: Unknown error)
  2024/04/02 13:23:32 [warn] 103877#0: usage report: failed (server returned: 404 Not Found)
  2024/04/02 19:53:45 [warn] 4648#4648: usage report: connection timed out
  

Installer l'agent NGINX

Si vous n'êtes pas encore passé à R31 ou n'avez pas l'intention de le faire prochainement, vous pouvez toujours signaler vos instances NGINX Plus au gestionnaire d'instances NGINX. Vous pouvez y parvenir en installant l’agent NGINX dans votre environnement. Une fois l’installation terminée, vous pouvez établir une connexion avec le gestionnaire d’instances et commencer à transmettre les données d’utilisation. Pour installer l'agent NGINX, suivez les instructions fournies dans ce lien .

Pour afficher l'utilisation de NGINX Plus, connectez-vous à NGINX Management Suite sur votre navigateur et accédez au module NGINX Instance Manager. Ensuite, sélectionnez l’onglet NGINX Plus situé en bas à gauche de la page.

Regardez ce didacticiel vidéo avec des instructions étape par étape :

Configurer le contrôle de santé HTTP pour NGINX Plus

Si vous n'envisagez pas d'installer l'agent NGINX ou de procéder à une mise à niveau vers R31, vous pouvez toujours signaler vos instances NGINX Plus. Cela peut être réalisé en configurant un contrôle de santé HTTP via le fichier de configuration NGINX. Cependant, vous devez mettre à jour manuellement le fichier de configuration NGINX Plus pour utiliser cette option. Cette méthode peut être longue et fastidieuse, en particulier si votre environnement comporte plusieurs instances. Il est donc conseillé de prendre en compte ces facteurs avant de choisir cette option.

Configurer NGINX Plus

1. Ouvrez la configuration NGINX Plus et insérez le code dans le bloc http {} :

   
      keyval_zone zone=uuid:32K state=/var/lib/nginx/state/instance_uuid.json;
      keyval 1 $nginx_uuid zone=uuid;
      upstream receiver {
       zone receiver 64k;
   
       # REQUIRED: Update NMS_FQDN with NGINX Management Suite IP Address or hostname.
       # If configuring with hostname, please ensure to uncomment the resolver
       # directive below and define a DNS server that can resolve the hostname.
       server NMS_FQDN:443;
   
       # OPTIONAL: Update DNS_UP with DNS server IP address that can resolve
       # the hostname defined above.
       #resolver DNS_IP;
      }  
   
   map CERT $repo_crt {
       # OPTIONAL: Location of client certificate
         default /home/ubuntu/agent.crt;
      }  
   
   map KEY $repo_key {
       # OPTIONAL: Location of client certificate private key
         default /home/ubuntu/agent.key; 
      }
   
   
    server {
       location @ngx_usage_https {
           # OPTIONAL: Configure scheme (http|https) here
           proxy_pass https://receiver;
   
           # REQUIRED: If using NGINX APP PROTECT (NAP) on this instance, set nap=active on the following line:
   proxy_set_header Nginx-Usage "Version=$nginx_version;Hostname=$hostname;uuid=$nginx_uuid;nap=active";	 
   
           health_check uri=/api/nginx-usage interval=1800s;       # DO NOT MODIFY
           proxy_ssl_certificate     $repo_crt;                    # DO NOT MODIFY
           proxy_ssl_certificate_key $repo_key;                    # DO NOT MODIFY
       }
   
       location @self {
           health_check uri=/_uuid interval=1d;
           proxy_pass http://self;
       }
   
       location = /_uuid {
           if ($nginx_uuid !~ .) {
               set $nginx_uuid $request_id;
           }
           return 204;
       }
   
       listen unix:/tmp/ngx_usage.sock;
     }
   
    upstream self {
       zone self 64k;
       server unix:/tmp/ngx_usage.sock;
    }
   

2. Mettez à jour le nom de domaine complet NMS avec le nom d’hôte ou l’adresse IP de votre gestionnaire d’instances. Si vous utilisez un DNS privé, supprimez le commentaire et mettez à jour votre adresse IP DNS.
3. Pour garantir la sécurité du trafic HTTP vers NGINX Instance Manager, il est essentiel de spécifier les emplacements du certificat SSL et de la clé dans les blocs CERT et KEY de la carte.

Enregistrez les modifications et rechargez NGINX.

sudo nginx -s recharger

Pour afficher l'utilisation de NGINX Plus, connectez-vous à NGINX Management Suite sur votre navigateur et accédez au module NGINX Instance Manager. Ensuite, sélectionnez l’onglet NGINX Plus en bas à gauche de la page.

Regardez ce didacticiel vidéo avec des instructions étape par étape :

Conclusion

Nous nous engageons à vous rencontrer là où vous êtes et à vous aider à rationaliser et automatiser les rapports d'utilisation en toute simplicité. C'est pourquoi nous proposons plusieurs options pour une flexibilité de reporting. La mise à jour NGINX Plus R31 récemment publiée rend encore plus simple et plus efficace la création de rapports sur les données d'utilisation mensuelles sur les instances NGINX Plus, sans impacter les performances, tout en garantissant la conformité aux exigences de F5.