Tutoriel : configurer les rapports d’utilisation de NGINX

Akash AnanthanarayananResponsable marketing technique | F5 NGINX

NGINX Plus R31 propose une méthode plus simple et plus efficace pour déclarer l’utilisation de NGINX Plus. L’intégration native de la déclaration d’utilisation élimine le besoin de recourir à un agent NGINX distinct, ce qui rend le processus fluide et simple pour les clients du programme Flex Consumption Program (FCP) de F5, ainsi que pour les clients hors FCP disposant d’un abonnement à durée déterminée. Grâce à cette fonctionnalité directement intégrée à NGINX Plus, les instances peuvent transmettre périodiquement les informations d’utilisation nécessaires à NGINX Instance Manager, sans aucune incidence sur les performances. Cette fonctionnalité est disponible pour les machines virtuelles et les contrôleurs NGINX Ingress, mais cet article se concentre sur les instances NGINX Plus. Vous trouverez un guide expliquant comment déclarer le contrôleur NGINX Ingress auprès de NGINX Instance Manager ici.

En simplifiant la configuration, en proposant des options de personnalisation et en fournissant des méthodes de secours, nous souhaitons faire du reporting d’utilisation obligatoire un processus efficace et adaptable, facile à mettre en œuvre pour les clients afin de rester en conformité avec le FCP. Pour les clients qui n’utilisent pas encore la version R31 ou qui ne prévoient pas d’effectuer la mise à niveau, d’autres méthodes permettent d’activer le reporting d’utilisation, soit en installant NGINX Agent, soit en configurant des contrôles d’intégrité HTTP.

Remarque : Pour transmettre les données d’utilisation de NGINX Plus, vous devez installer NGINX Instance Manager sur un hôte dédié. Consultez le guide d’installation pour découvrir les différentes méthodes d’installation.

Vous pouvez choisir parmi trois méthodes pour déclarer les instances NGINX Plus auprès de F5.

• Utilisateurs de NGINX Plus R31 — Configuration du rapport d’utilisation natif de NGINX
• Utilisateurs de R31 ou d’une version antérieure à R31 — Installation de NGINX Agent
• Utilisateurs des versions antérieures à R31 — Configuration de la vérification de l’état HTTP pour NGINX Plus

Examinons-les un par un :

Configurer les rapports d’utilisation natifs de NGINX

Lors de l’installation, NGINX Plus établit automatiquement une connexion à NGINX Instance Manager via l’entrée DNS par défaut « nginx-mgmt.local ». Par défaut, NGINX Plus communique toutes les 30 minutes avec NGINX Instance Manager et lui envoie les informations d’utilisation. Si vous devez modifier l’entrée DNS de NGINX Instance Manager ou adapter l’intervalle de connexion par défaut à vos besoins, ajoutez le bloc mgmt{} à votre configuration NGINX. Ce bloc comprend également d’autres directives par défaut, notamment le fichier UUID, mTLS, le résolveur DNS, l’intervalle d’envoi des données d’utilisation et le point de terminaison usage_report. Pour obtenir la liste complète des directives personnalisables, consultez la documentation détaillée du mgmtmodule. Grâce au ngx_mgmt_module, vous pouvez facilement personnaliser les directives, pour davantage de flexibilité et de simplicité.

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

Configurer NGINX Plus

1. Il est recommandé d’utiliser mTLS pour renforcer la sécurité de votre système. Pour ce faire, générez un certificat, une clé et un certificat de clé d’autorité de certification pour l’instance NGINX Plus et NGINX Instance Manager. Pour plus d’informations sur la génération de 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 management 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
       }

1. Pour garantir un processus d’authentification sécurisé et fiable, indiquez le chemin d’accès à la chaîne d’autorités de certification afin de valider l’authenticité des certificats.

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

1. Pour les résolveurs DNS personnalisés, indiquez l’adresse du résolveur dans le bloc mgmt{}block à l’aide de la directive resolver.

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

1. Pour configurer un nom de domaine complet (FQDN) personnalisé pour NGINX Instance Manager, indiquez-le dans la directive usage_report directive. Ajoutez ensuite à votre DNS local un enregistrement A 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 reload

Configurer NGINX Instance Manager

Ajoutez le certificat SSL dans /etc/nginx/conf.d/nms-HTTP.conf, à l’intérieur du bloc server. 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 consulter l’utilisation de NGINX Plus, connectez-vous à NGINX Management Suite dans votre navigateur et accédez au module NGINX Instance Manager. Sélectionnez ensuite l’onglet NGINX Plus situé en bas à gauche de la page.

Regardez ce tutoriel vidéo qui vous guidera étape par étape :

 

Messages du journal d’erreurs

Voici une liste de messages d’erreur permettant de résoudre les problèmes liés à une instance NGINX Plus lorsque les données d’utilisation ne s’affichent pas dans NGINX Instance Manager. Voici quelques exemples de messages d’erreur :

• Échecs du résolveur dynamique : échec de la résolution 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 : impossible de résoudre le nom d’hôte de NGINX Instance Manager

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

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

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

• Échecs de communication avec les pairs : impossible de joindre NGINX Instance Manager.

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 NGINX Agent

Si vous n’êtes pas encore passé à la version R31 ou si vous ne prévoyez pas de le faire prochainement, vous pouvez toujours déclarer vos instances NGINX Plus auprès de NGINX Instance Manager. Pour cela, installez NGINX Agent dans votre environnement. Une fois l’installation terminée, vous pouvez établir une connexion avec Instance Manager et commencer à transmettre les données d’utilisation. Pour installer NGINX Agent, suivez les instructions fournies via ce lien.

Pour consulter l’utilisation de NGINX Plus, connectez-vous à NGINX Management Suite dans votre navigateur et accédez au module NGINX Instance Manager. Sélectionnez ensuite l’onglet NGINX Plus situé en bas à gauche de la page.

Regardez ce tutoriel vidéo qui vous guidera étape par étape :

 

Configurer la vérification de l’état HTTP pour NGINX Plus

Si vous ne prévoyez pas d’installer l’agent NGINX ni d’effectuer une mise à niveau vers R31, vous pouvez tout de même déclarer vos instances NGINX Plus. Pour ce faire, configurez une vérification de l’état HTTP dans le fichier de configuration NGINX. Toutefois, vous devez mettre à jour manuellement le fichier de configuration de 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 recommandé de tenir compte de ces facteurs avant de choisir cette option.

Configurer NGINX Plus

1. Ouvrez la configuration de 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;
 }

1. Remplacez le nom de domaine complet (FQDN) de NMS par le nom d’hôte ou l’adresse IP de votre Instance Manager. Si vous utilisez un DNS privé, décommentez l’adresse IP de votre serveur DNS et mettez-la à jour.
2. Pour garantir la sécurité du trafic HTTP vers NGINX Instance Manager, il est essentiel d’indiquer les emplacements du certificat SSL et de la clé dans les blocs map CERT et map KEY.

Enregistrez les modifications et rechargez NGINX.

sudo nginx -s reload

Pour consulter l’utilisation de NGINX Plus, connectez-vous à NGINX Management Suite dans votre navigateur et accédez au module NGINX Instance Manager. Sélectionnez ensuite l’onglet NGINX Plus en bas à gauche de la page.

Regardez ce tutoriel vidéo qui vous guidera étape par étape :

 

Conclusion

Nous nous engageons à nous adapter à votre situation et à vous aider à simplifier et à automatiser facilement la déclaration de votre utilisation. C’est pourquoi nous proposons plusieurs options pour vous offrir davantage de flexibilité en matière de déclaration. La récente mise à jour R31 de NGINX Plus permet de déclarer encore plus simplement et efficacement les données d’utilisation mensuelle des instances NGINX Plus, sans incidence sur les performances et dans le respect des exigences de F5.

À propos de l’auteur

Akash AnanthanarayananResponsable marketing technique | F5 NGINX

Autres articles de Akash Ananthanarayanan