Tutorial: NGINX-Nutzungsberichte konfigurieren

Akash AnanthanarayananManager für technisches Marketing | F5 NGINX

NGINX Plus R31 bietet eine einfachere und effizientere Möglichkeit, die Nutzung von NGINX Plus zu melden. Durch die native Integration der Nutzungsmeldung ist kein separater NGINX Agent mehr erforderlich. Dadurch erfolgt die Meldung für Kunden des Flex Consumption Program (FCP) von F5 sowie für Nicht-FCP-Kunden mit einem befristeten Abonnement nahtlos und unkompliziert. Da diese Funktionalität direkt in NGINX Plus integriert ist, können Instanzen die erforderlichen Nutzungsinformationen regelmäßig und ohne Leistungseinbußen an den NGINX Instance Manager übermitteln. Diese Funktion ist für virtuelle Maschinen und NGINX Ingress Controller verfügbar. Dieser Blog konzentriert sich jedoch auf NGINX Plus-Instanzen. Eine Anleitung zur Meldung des NGINX Ingress Controllers an den NGINX Instance Manager finden Sie hier.

Durch eine vereinfachte Einrichtung, Anpassungsoptionen und Ausweichmethoden möchten wir die erforderliche Nutzungsberichterstattung zu einem effizienten und flexiblen Prozess machen, den Kunden implementieren können, um die FCP-Vorgaben dauerhaft einzuhalten. Kunden, die R31 noch nicht einsetzen oder kein Upgrade planen, stehen alternative Methoden zur Aktivierung der Nutzungsberichterstattung zur Verfügung: Sie können entweder den NGINX Agent installieren oder HTTP-Integritätsprüfungen konfigurieren.

Hinweis: Um die Nutzung von NGINX Plus zu melden, müssen Sie NGINX Instance Manager auf einem dedizierten Host installieren. Informationen zu den verschiedenen Installationsmethoden finden Sie in der Installationsanleitung.

Sie können zwischen drei Möglichkeiten wählen, um NGINX Plus-Instanzen an F5 zu melden.

• Benutzer von NGINX Plus R31 — Konfigurieren der nativen NGINX-Nutzungsberichterstattung
• Benutzer von R31 oder älteren Versionen – Installieren des NGINX Agent
• Benutzer von Versionen vor R31 — Konfigurieren der HTTP-Systemdiagnose für NGINX Plus

Sehen wir sie uns der Reihe nach an:

Native NGINX-Nutzungsberichte konfigurieren

Nach der Installation stellt NGINX Plus über den standardmäßigen DNS-Eintrag „nginx-mgmt.local“ automatisch eine Verbindung zum NGINX Instance Manager her. Standardmäßig kommuniziert NGINX Plus alle 30 Minuten mit dem Instance Manager und sendet die Nutzungsinformationen. Wenn Sie den DNS-Eintrag des Instance Manager ändern oder das standardmäßige Verbindungsintervall besser an Ihre Anforderungen anpassen möchten, fügen Sie Ihrer NGINX-Konfiguration den Block mgmt{} hinzu. Darüber hinaus umfasst dieser weitere Standarddirektiven, etwa für die UUID-Datei, mTLS, den DNS-Resolver, das Nutzungsintervall und den Endpunkt usage_report. Eine vollständige Liste der anpassbaren Direktiven finden Sie in der umfassenden Dokumentation zum mgmtmodule. Mit dem ngx_mgmt_module können Sie die Direktiven ganz einfach anpassen und profitieren so von mehr Flexibilität und Komfort.

In den folgenden Abschnitten wird erläutert, wie Sie diese Funktion für Ihre Umgebung konfigurieren.

NGINX Plus konfigurieren

1. Es wird empfohlen, mTLS zu verwenden, um die Sicherheit Ihres Systems zu erhöhen. Generieren Sie dazu für die NGINX Plus-Instanz und NGINX Instance Manager jeweils ein Zertifikat, einen Schlüssel und ein CA-Schlüsselzertifikat. Weitere Informationen zum Generieren von Schlüsseln finden Sie hier.
2. Geben Sie im management-Block der Konfigurationsdatei nginx.conf den Pfad zum Clientzertifikat und zur Datei mit dem privaten Schlüssel an.

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

1. Geben Sie für einen sicheren und zuverlässigen Authentifizierungsprozess den Pfad zur CA-Kette an, um die Echtheit der Zertifikate zu überprüfen.

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

1. Geben Sie für benutzerdefinierte DNS-Resolver die Resolver-Adresse im mgmt{}block mithilfe der Resolver-Direktive an.

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

1. Um einen benutzerdefinierten FQDN für NGINX Instance Manager zu konfigurieren, geben Sie den FQDN in der Direktive „usage_report“ an. Fügen Sie anschließend Ihrem lokalen DNS einen A-Record hinzu, der den Hostnamen mit der IP-Adresse von NGINX Instance Manager verknüpft.

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

Beispielkonfiguration für 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;
     }

Speichern Sie die NGINX-Konfiguration und laden Sie NGINX Plus neu.

sudo nginx -s reload

NGINX Instance Manager konfigurieren

Fügen Sie das SSL-Zertifikat in /etc/nginx/conf.d/nms-HTTP.conf innerhalb des server-Blocks hinzu. Klicken Sie hier, um zu erfahren, wie Sie ein SSL-Zertifikat auf dem NGINX Management Suite-Server konfigurieren.

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;
 }

Um die Nutzung von NGINX Plus anzuzeigen, melden Sie sich in Ihrem Browser bei der NGINX Management Suite an und navigieren Sie zum Modul NGINX Instance Manager. Wählen Sie anschließend unten links auf der Seite die Registerkarte NGINX Plus aus.

Sehen Sie sich dieses Video-Tutorial mit einer Schritt-für-Schritt-Anleitung an:

 

Fehlerprotokollmeldungen

Hier finden Sie eine Liste von Fehlermeldungen zur Fehlerbehebung in einer NGINX Plus-Instanz, wenn in NGINX Instance Manager keine Nutzungsdaten angezeigt werden. Nachfolgend finden Sie einige Beispiele für solche Fehlermeldungen:

• Fehler bei der dynamischen Namensauflösung: Der DNS-Resolver konnte nicht aufgelöst werden.

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)

• Fehler des System-Resolvers: Der Hostname von NGINX Instance Manager konnte nicht aufgelöst werden

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

• SSL-Verbindungsfehler: Das SSL-Zertifikat konnte nicht verifiziert werden oder ist abgelaufen.

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

• Fehler bei der Peer-Kommunikation: NGINX Instance Manager ist nicht erreichbar.

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

NGINX Agent installieren

Wenn Sie noch nicht auf R31 umgestiegen sind oder dies in nächster Zeit nicht beabsichtigen, können Sie Ihre NGINX Plus-Instanzen weiterhin an den NGINX Instance Manager melden. Installieren Sie dazu den NGINX Agent in Ihrer Umgebung. Nach Abschluss der Installation können Sie eine Verbindung mit dem Instance Manager herstellen und mit der Übertragung von Nutzungsdaten beginnen. Befolgen Sie zur Installation des NGINX Agent die Anweisungen unter diesem Link.

Um die Nutzung von NGINX Plus anzuzeigen, melden Sie sich in Ihrem Browser bei der NGINX Management Suite an und navigieren Sie zum Modul NGINX Instance Manager. Wählen Sie anschließend unten links auf der Seite die Registerkarte NGINX Plus aus.

Sehen Sie sich dieses Video-Tutorial mit einer Schritt-für-Schritt-Anleitung an:

 

HTTP-Integritätsprüfung für NGINX Plus konfigurieren

Wenn Sie weder die Installation des NGINX Agent noch ein Upgrade auf R31 planen, können Sie Ihre NGINX Plus-Instanzen dennoch melden. Dazu können Sie über die NGINX-Konfigurationsdatei eine HTTP-Zustandsprüfung konfigurieren. Um diese Option zu nutzen, müssen Sie die NGINX Plus-Konfigurationsdatei jedoch manuell aktualisieren. Diese Methode kann zeitaufwendig und umständlich sein, insbesondere wenn Ihre Umgebung mehrere Instanzen umfasst. Daher sollten Sie diese Faktoren berücksichtigen, bevor Sie sich für diese Option entscheiden.

NGINX Plus konfigurieren

1. Öffnen Sie die NGINX Plus-Konfiguration und fügen Sie den Code in den Block http {} ein:

   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. Ersetzen Sie den NMS-FQDN durch den Hostnamen oder die IP-Adresse Ihres Instance Managers. Wenn Sie privates DNS verwenden, entfernen Sie die Auskommentierung und aktualisieren Sie die IP-Adresse Ihres DNS-Servers.
2. Um die Sicherheit des HTTP-Datenverkehrs zum NGINX Instance Manager zu gewährleisten, müssen die Speicherorte des SSL-Zertifikats und des Schlüssels in den Blöcken map CERT und map KEY angegeben werden.

Speichern Sie die Änderungen und laden Sie NGINX neu.

sudo nginx -s reload

Um die Nutzung von NGINX Plus anzuzeigen, melden Sie sich in Ihrem Browser bei der NGINX Management Suite an und navigieren Sie zum Modul NGINX Instance Manager. Wählen Sie anschließend unten links auf der Seite die Registerkarte NGINX Plus aus.

Sehen Sie sich dieses Video-Tutorial mit einer Schritt-für-Schritt-Anleitung an:

 

Fazit

Wir möchten Sie dort abholen, wo Sie stehen, und Ihnen dabei helfen, die Nutzungsberichte mühelos zu optimieren und zu automatisieren. Deshalb bieten wir mehrere Optionen für eine flexible Berichterstattung an. Mit dem kürzlich veröffentlichten Update R31 für NGINX Plus können Sie monatliche Nutzungsdaten zu NGINX Plus-Instanzen noch einfacher und effizienter melden – ohne die Leistung zu beeinträchtigen und unter Einhaltung der Anforderungen von F5.

Über den Autor

Akash AnanthanarayananManager für technisches Marketing | F5 NGINX

Weitere Blogbeiträge von Akash Ananthanarayanan