Tutorial: .NET Core und Kestrel mit NGINX und NGINX Plus als Proxy betreiben

Nick ShadrinSoftwarearchitekt

Vor etwa zwei Jahren kündigte Microsoft® .NET Core an, ein Framework, mit dem Sie .NET-Anwendungen nativ auf Linux- und Mac-Systemen entwickeln und ausführen können. ASP.NET Core enthält Kestrel, eine interne Webserverbibliothek.

Wie in der Dokumentation zu Kestrel auf der Microsoft-Website und im GitHub-Repository beschrieben, wird Kestrel üblicherweise hinter einem für den Produktivbetrieb geeigneten Webserver wie IIS oder NGINX ausgeführt. In diesem Tutorial beschreiben wir, wie Kestrel hinter NGINX und NGINX Plus implementiert wird.

In diesem Tutorial erfahren Sie, wie Sie:

• Installieren Sie .NET Core, NGINX und NGINX Plus
• Erstellen Sie eine sehr einfache Webanwendung
• Kestrel als Webserver starten
• NGINX als Frontend installieren und konfigurieren
• Erweiterte Funktionen von NGINX Plus aktivieren

Wenn die Installation und Konfiguration abgeschlossen sind:

• .NET Core und Kestrel:
  • Den dynamischen Anwendungscode ausführen
  • An einer lokalen IP-Adresse lauschen und auf HTTP-Anfragen antworten
• NGINX oder NGINX Plus als Reverse-Proxy:
  • Akzeptiert HTTP/2-Datenverkehr über IPv6 und IPv4
  • Stellt SSL-Offloading für die .NET-Anwendung bereit
  • Stellt statische Dateien bereit
  • Stellt Zugriffsprotokolle bereit
  • Fügt Caching hinzu
• NGINX Plus:
  • Bietet Echtzeitüberwachung von Aktivitäten und Metriken
  • Stellt mithilfe aktiver Integritätsprüfungen sicher, dass die App funktioniert

Die Bereitstellungsarchitektur für .NET-Core-Anwendungen ähnelt der Bereitstellungsarchitektur von Node.js- oder Go-Anwendungen. NGINX stellt .NET-Anwendungen Funktionen zur Datenverkehrssteuerung bereit, die die Produktivbereitstellung und Skalierbarkeit der Anwendungen vereinfachen. Sie können mehrere .NET-Anwendungen auf demselben oder auf unterschiedlichen Rechnern ausführen. NGINX oder NGINX Plus übernimmt dabei den Lastenausgleich und die intelligente Weiterleitung des Datenverkehrs zwischen den Anwendungen.

Anleitung

Die folgende Anleitung erläutert, wie Sie schnell eine „Hello World“-App mit .NET Core erstellen, unter Linux ausführen und hinter einem NGINX- oder NGINX Plus-Reverse-Proxy mit erweiterten Funktionen zur Datenverkehrssteuerung bereitstellen.

1. Installieren Sie .NET Core, NGINX und NGINX Plus
2. „Hello World“-App ausführen
3. Kestrel-HTTP-Server ausführen
4. NGINX oder NGINX Plus als Reverse-Proxy für die .NET-Anwendung konfigurieren
5. Live-Aktivitätsüberwachung und aktive Integritätsprüfungen in NGINX Plus konfigurieren

Installieren von .NET Core, NGINX und NGINX Plus

1. Installieren Sie .NET Core gemäß der Anleitung auf der Microsoft-Website. In unserem Beispiel verwenden wir Ubuntu 16.04. Die folgenden Befehle waren zum Zeitpunkt der Erstellung korrekt, können sich jedoch ändern, da Kestrel noch in der Entwicklung ist. Ziehen Sie bei Bedarf die .NET-Core-Dokumentation zurate.

$ sudo apt-get install apt-transport-https$ sudo sh -c 'echo "deb [arch=amd64] https://apt-mo.trafficmanager.net/repos/dotnet-release/ xenial main" > /etc/apt/sources.list.d/dotnetdev.list'
$ sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893
$ sudo apt-get update
$ sudo apt-get install dotnet-dev-1.0.0-preview2-003131

1. NGINX installieren:

$ sudo apt-get install nginx

1. Installieren Sie NGINX Plus, wenn Sie eine Live-Aktivitätsüberwachung, aktive Systemdiagnosen oder beides wünschen. Befolgen Sie die Anweisungen im NGINX Plus-Administratorhandbuch.
   1. Bearbeiten Sie die Datei ./project.json, um Kestrel als Abhängigkeit zum Projekt hinzuzufügen.

{  "version": "1.0.0-*",
  "buildOptions": {
    "debugType": "portable",
    "emitEntryPoint": true
  },
  "dependencies": {},
  "frameworks": {
    "netcoreapp1.0": {
      "dependencies": {
        "Microsoft.NETCore.App": {
          "type": "platform",
          "version": "1.0.1"
        }, "Microsoft.AspNetCore.Server.Kestrel": "1.0.0"
      },
      "imports": "dnxcore50"
    }
  }
}

1. Kopieren Sie diesen Code für eine einfache App in eine neue Datei namens Program.cs. Die App gibt das aktuelle Datum und die aktuelle Uhrzeit zurück und führt Kestrel auf localhost an Port 5000 aus.

using System;using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;

namespace ConsoleApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .Configure(app =>
                {
                    app.Run(async (context) => await context.Response.WriteAsync("Current date: " + DateTime.Now + "n"));
                })
                .Build();

            host.Run();
        }
    }
}

1. Führen Sie den Befehl „dotnet run“ aus, um den .NET Core-Server zu starten:

$ dotnet runProject app (.NETCoreApp,Version=v1.0) will be compiled because inputs were modified
Compiling app for .NETCoreApp,Version=v1.0

Compilation succeeded.
    0 Warning(s)
    0 Error(s)

Time elapsed 00:00:01.9047678

Hello World!
Hosting environment: Production
Content root path: /app/bin/Debug/netcoreapp1.0
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

1. Führen Sie den Befehl „curl“ aus, um die Konnektivität und HTTP zu testen:

$ curl -v localhost:5000* Rebuilt URL to: localhost:5000/
*   Trying ::1...
* Connected to localhost (::1) port 5000 (#0)
> GET / HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.47.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Tue, 14 Feb 2017 19:50:59 GMT
< Transfer-Encoding: chunked
< Server: Kestrel
<
Current date: 02/14/17 12:50:59 PM
* Connection #0 to host localhost left intact

1. Installieren Sie ein SSL-Zertifikat. Es gibt mehrere Möglichkeiten, eines zu beziehen: Um schnell eine .NET-Core-Beispielanwendung mit SSL einzurichten, erstellen wir mit diesem openssl-Befehl ein selbstsigniertes Zertifikat und den zugehörigen Schlüssel. Wir installieren das Zertifikat und den Schlüssel im Standardverzeichnis von NGINX, /etc/nginx, Sie können jedoch auch ein anderes Verzeichnis wählen.

$ openssl req -x509 -subj /CN=localhost -days 365 -set_serial 2 -newkey rsa:4096 -keyout /etc/nginx/cert.key -nodes -out /etc/nginx/cert.pemGenerating a 4096 bit RSA private key
.........++
............................++
writing new private key to '/etc/nginx/cert.key'
-----

• Kaufen Sie es bei einer renommierten Zertifizierungsstelle (CA)
• Lassen Sie es von Ihrer IT-Abteilung oder Zertifizierungsstelle (CA) erstellen
• Exportieren Sie es von einem vorhandenen IIS-Server
• Verwenden Sie eine kostenlose Zertifizierungsstelle wie Let’s Encrypt
• Direkt ein selbstsigniertes Zertifikat erstellen

1. Konfigurieren Sie den Reverse-Proxy in der standardmäßigen NGINX- und NGINX-Plus-Konfigurationsdatei für virtuelle HTTP-Server. Die Hauptkonfigurationsdatei von NGINX und NGINX Plus ist /etc/nginx/nginx.conf. Bei mehreren NGINX-Distributionen (sowie bei NGINX Plus) ist es jedoch üblich, die eigentliche Konfiguration nicht größtenteils in der Hauptdatei abzulegen, sondern stattdessen kleinere, funktionsspezifische Dateien in einem Unterverzeichnis von /etc/nginx zu erstellen: Der Inhalt der funktionsspezifischen Dateien in diesen Verzeichnissen wird dann mit einer nginx.conf-Datei über eine include-Direktive in die Hauptdatei eingelesen, zum Beispiel:

include /etc/nginx/conf.d/*.conf;include /etc/nginx/sites-enabled/*;

1. Wenn Sie nicht sicher sind, welche Datei auf Ihrem System die Standardkonfigurationsdatei für virtuelle HTTP-Server ist, suchen Sie nach der entsprechenden include-Direktive in /etc/nginx/nginx.conf. Um NGINX oder NGINX Plus als Reverse-Proxy zu konfigurieren, fügen Sie der Standardkonfigurationsdatei für virtuelle HTTP-Server die folgenden drei Konfigurationsblöcke hinzu:

server {    listen 80 default_server;
    listen [::]:80 default_server;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2 default_server;
    listen [::]:443 ssl http2 default_server;

    ssl_certificate /etc/nginx/cert.pem;
    ssl_certificate_key /etc/nginx/cert.key;

    location / {
        proxy_pass http://dotnet;
        proxy_set_header Host $host;
    }
}

upstream dotnet {
    zone dotnet 64k;
    server 127.0.0.1:5000;
}

• Bei von nginx.org bereitgestellten NGINX Open Source-Builds und bei NGINX Plus lautet das Verzeichnis /etc/nginx/conf.d, und die Standarddatei für virtuelle HTTP-Server ist default.conf.
• Bei mit Ubuntu ausgelieferten NGINX Open Source-Builds lautet das Verzeichnis /etc/nginx/sites-enabled, und die Standarddatei für virtuelle HTTP-Server heißt default.
• Der erste server-Block nimmt HTTP-Anfragen an Port 80 entgegen und leitet sie an den virtuellen Server für HTTPS-Anfragen weiter.
• Der zweite server-Block akzeptiert HTTPS-Anfragen an Port 443 und leitet sie per Proxy an eine Gruppe aus einem oder mehreren Upstream-Servern (Backend-Servern) weiter, die hier als dotnet bezeichnet wird. (Wenn Sie in Schritt 1 Ihr selbstsigniertes SSL-Zertifikat in einem anderen Verzeichnis als /etc/nginx installiert haben, geben Sie in den Direktiven ssl_certificate und ssl_certificate_key den korrekten Pfad an.)
• Der upstream-Block definiert die Backendservergruppe dotnet. Unter „Ausführen des Kestrel-HTTP-Servers“ haben wir Kestrel auf localhost:5000 konfiguriert. Das bedeutet, dass Kestrel an diesem Port sowohl IPv4- als auch IPv6-Datenverkehr entgegennimmt. (Wenn Kestrel nur für eines der beiden Protokolle konfiguriert wird, kann dies zu Instabilität und möglicherweise zu 502-Fehlern führen.) Ebenso lösen NGINX und NGINX Plus localhost sowohl in die IPv4- als auch in die IPv6-Adresse auf (127.0.0.1 und ::1). Der Einfachheit halber geben wir den Upstreamserver hier als 127.0.0.1 statt als localhost an, sodass er nur IPv4-Datenverkehr entgegennimmt. Sie können localhost verwenden, wenn Sie mit einer komplexeren Konfiguration vertraut sind, die IPv6 einschließt.

1. Führen Sie diesen curl-Befehl aus, um die Verbindung zur .NET-Core-App über HTTPS zu testen. (Alternativ können Sie Ihren Browser auf Ihren Linux-Server verweisen.)

$ curl -kv https://localhost* Rebuilt URL to: https://localhost/
*   Trying ::1...
* Connected to localhost (::1) port 443 (#0)
...[SKIPPED]...
< HTTP/1.1 200 OK
< Server: nginx/1.10.0 (Ubuntu)
< Date: Tue, 14 Feb 2017 20:22:07 GMT
< Transfer-Encoding: chunked
< Connection: keep-alive
<
Current date: 02/14/17 1:22:07 PM

1. Hinweis: Wenn 502-Fehler vom Typ „Bad Gateway“ angezeigt werden, bedeutet dies, dass NGINX oder NGINX Plus keine Verbindung zu Ihrer .NET-Anwendung herstellen kann. Stellen Sie sicher, dass sie ausgeführt wird und Antworten über Port 5000 bereitstellt. Wenn Sie das Paket nghttp2 installiert haben, können Sie auch den folgenden nghttp-Befehl ausführen, um die Verbindung über HTTP/2 zu testen. Suchen Sie im folgenden Beispiel nahe dem Anfang der recht umfangreichen Ausgabe nach der orange hervorgehobenen Zeile.

$ nghttp -v https://localhost[  0.000] Connected
The negotiated protocol: h2
[  0.009] send SETTINGS frame 
          (niv=2)
          [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
          [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
[  0.009] send PRIORITY frame 
          (dep_stream_id=0, weight=201, exclusive=0)

• Der Antwortcode lautet 200 OK
• Der Anwendungsserver ist Kestrel und keine andere Software
• Der Antworttext enthält die Wörter „Aktuelles Datum“
• Die App antwortet innerhalb eines Zeitlimits von 1 Sekunde.

Führen Sie die „Hello World“-App aus

Installieren und initialisieren Sie eine „Hello World“-App in einem übergeordneten Verzeichnis Ihrer Wahl:

$ cd parent-dir-for-apps
$ mkdir app
$ cd app
$ dotnet restore

Um zu überprüfen, ob die App funktioniert, führen Sie den Befehl „dotnet run“ aus.

Kestrel-HTTP-Server ausführen

Zu diesem Zeitpunkt wird .NET Core unter Linux ausgeführt und stellt dynamische Daten bereit, wobei Kestrel als HTTP-Server verwendet wird.

NGINX oder NGINX Plus als Reverse-Proxy für die .NET-Anwendung konfigurieren

Wenn Sie NGINX oder NGINX Plus als Reverse-Proxy für die .NET-Anwendung einsetzen, können Sie auf demselben Rechner, auf dem die .NET Core-Anwendung ausgeführt wird, problemlos SSL/TLS-Sicherheit, HTTP/2-Unterstützung und viele weitere Funktionen für eine schnelle Anwendungsbereitstellung konfigurieren. Die folgenden Anweisungen setzen voraus, dass NGINX und NGINX Plus bereits auf Ihrem System installiert sind. Ist dies nicht der Fall, lesen Sie Installieren von .NET Core, NGINX und NGINX Plus.

Live-Aktivitätsüberwachung und aktive Integritätsprüfungen in NGINX Plus konfigurieren

Damit ist die grundlegende Konfiguration von NGINX bzw. NGINX Plus mit .NET Core abgeschlossen. NGINX bzw. NGINX Plus übernimmt für unsere .NET-Core-App die HTTP-Verarbeitung, passive Integritätsprüfungen, die Absicherung mit SSL/TLS sowie die HTTP/2-Konnektivität.

Wenn Sie NGINX Plus installiert haben, können Sie zwei zusätzliche Funktionen konfigurieren: Live-Aktivitätsüberwachung und aktive Systemdiagnosen.

Live-Aktivitätsüberwachung konfigurieren

[Redaktion – Dieser Abschnitt wurde aktualisiert und verweist nun auf die NGINX Plus API, die das ursprünglich hier beschriebene separate erweiterte Statusmodul ersetzt und als veraltet kennzeichnet.]

Fügen Sie den folgenden server-Block zur standardmäßigen NGINX-Konfigurationsdatei für virtuelle HTTP-Server hinzu. Wir empfehlen dringend, den Zugriff auf die Statistiken und Metriken zu beschränken. Hier gestatten wir den Zugriff nur Benutzern auf localhost und in einem lokalen Netzwerk.

Weitere Informationen zur Überwachung von Live-Aktivitäten finden Sie unter „Live-Aktivitätsüberwachung von NGINX Plus in 3 einfachen Schritten“ in unserem Blog sowie im „Administratorhandbuch für NGINX Plus“.

server {    listen 8080;
    allow 127.0.0.1;   # Allow localhost to access the statistics
    allow 10.3.3.0/24; # Allow local network to access the statistics
    deny all;          # Prevent access from anywhere else

    root /usr/share/nginx/html;

    location / {
        return 302 /dashboard.html;
    }

    location /api {
        api write=on;
    }

    location = /dashboard.html {
        root /usr/share/nginx/html;
    }

    # Redirect requests made to the old dashboard
    location = /status.html {
        return 301 /dashboard.html;
    }
}

Aktive Integritätsprüfungen konfigurieren

Aktive Integritätsprüfungen stellen sicher, dass NGINX Plus Datenverkehr nur an Anwendungen sendet, die ordnungsgemäß funktionieren. Sie definieren die HTTP-Anfragen, die NGINX Plus regelmäßig an die Anwendung sendet, sowie die Art der Antwort, die die Anwendung zurückgeben muss, damit sie als fehlerfrei gilt.

Hier setzen wir voraus, dass die Antwort der App die folgenden Bedingungen erfüllt:

Fügen Sie in der Standardkonfigurationsdatei für virtuelle HTTP-Server den folgenden location-Block zum Hauptblock server hinzu (dem in Schritt 2 von Konfigurieren von NGINX oder NGINX Plus als Reverse-Proxy für die .NET-Anwendung definierten Block für HTTPS-Datenverkehr):

location @healthcheck {    proxy_pass http://dotnet;
    proxy_set_header Host localhost;
    health_check match=currentdate;
    proxy_connect_timeout 1s;
    proxy_read_timeout 1s;
}

Fügen Sie außerdem den folgenden „match“-Block auf derselben Hierarchieebene wie die „server“- und „upstream“-Blöcke hinzu:

match currentdate {    status 200;
    header Server = Kestrel;
    body ~ "Current date";
}

Sie können überprüfen, ob Ihre Backend-App fehlerfrei ausgeführt wird. Rufen Sie dazu im integrierten Dashboard zur Live-Aktivitätsüberwachung die Registerkarte „Upstreams“ auf (öffnen Sie in Ihrem Browser //http://nginx-plus-server-address:8080/):

Weitere NGINX-Konfigurationsoptionen finden Sie in der Microsoft-Dokumentation.

Fazit

Für produktionsreife Bereitstellungen der mit ASP.NET entwickelten Anwendungen bieten NGINX und NGINX Plus die Funktionen zur Datenverkehrssteuerung, die Sie von einem Reverse-Proxy benötigen. NGINX und NGINX Plus sorgen für Sicherheit, Skalierbarkeit, Authentifizierung, Datenverkehrsbegrenzung und intelligentes Routing Ihrer HTTP-Anfragen an .NET-Core-Anwendungen.

Wenn Sie NGINX Plus selbst ausprobieren möchten, starten Sie noch heute Ihre kostenlose 30-Tage-Testversion oder kontaktieren Sie uns, um Ihre Anwendungsfälle zu besprechen.

Über den Autor

Nick ShadrinSoftwarearchitekt

Weitere Blogbeiträge von Nick Shadrin