Tutoriel : mise en proxy de .NET Core et Kestrel avec NGINX et NGINX Plus

Nick ShadrinArchitecte logiciel

Il y a environ deux ans, Microsoft® a annoncé .NET Core, un framework permettant de développer et d’exécuter des applications .NET de manière native sur les systèmes Linux et Mac. ASP.NET Core inclut Kestrel, une bibliothèque de serveur web interne.

Comme indiqué dans la documentation de Kestrel disponible sur le site web de Microsoft et dans le dépôt GitHub, Kestrel s’exécute généralement derrière un serveur web de production tel qu’IIS ou NGINX. Dans ce tutoriel, nous expliquerons comment déployer Kestrel derrière NGINX et NGINX Plus.

Dans ce tutoriel, vous apprendrez à :

• Installer .NET Core, NGINX et NGINX Plus
• Créer une application web très simple
• Démarrer Kestrel en tant que serveur web
• Installer et configurer NGINX comme serveur frontal
• Activer les fonctionnalités avancées de NGINX Plus

Une fois l’installation et la configuration terminées :

• .NET Core et Kestrel :
  • Exécuter le code dynamique de l’application
  • Écouter sur une adresse IP locale et répondre aux requêtes HTTP
• NGINX ou NGINX Plus, agissant comme proxy inverse :
  • Accepte le trafic HTTP/2 sur IPv6 et IPv4
  • Assure le déchargement SSL pour l’application .NET
  • Assure la diffusion de fichiers statiques
  • Fournit des journaux d’accès
  • Ajoute la mise en cache
• NGINX Plus :
  • Fournit une surveillance de l’activité en temps réel et des métriques
  • S’assure que l’application fonctionne grâce à des contrôles d’intégrité actifs

L’architecture de déploiement des applications .NET Core est similaire à celle des applications Node.js ou Go. NGINX fournit aux applications .NET des fonctionnalités de gestion du trafic qui simplifient leur déploiement en production et leur mise à l’échelle. Vous pouvez exécuter plusieurs applications .NET sur une même machine ou sur des machines différentes, tandis que NGINX ou NGINX Plus assure la répartition de charge et le routage intelligent du trafic entre elles.

Instructions

Les instructions suivantes expliquent comment créer rapidement une application « Hello World » avec .NET Core, l’exécuter sous Linux et la déployer derrière un proxy inverse NGINX ou NGINX Plus doté de fonctionnalités avancées de gestion du trafic.

1. Installez .NET Core, NGINX et NGINX Plus
2. Exécuter l’application « Hello World »
3. Exécuter le serveur HTTP Kestrel
4. Configurer NGINX ou NGINX Plus comme proxy inverse pour l’application .NET
5. Configurer la surveillance de l’activité en temps réel et les contrôles d’intégrité actifs de NGINX Plus

Installer .NET Core, NGINX et NGINX Plus

1. Installez .NET Core en suivant les instructions disponibles sur le site web de Microsoft. Dans notre exemple, nous utilisons Ubuntu 16.04. Les commandes suivantes étaient correctes au moment de la rédaction, mais sont susceptibles de changer, car Kestrel est toujours en cours de développement. Consultez la documentation de .NET Core si nécessaire.

$ 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. Installez NGINX :

$ sudo apt-get install nginx

1. Installez NGINX Plus si vous souhaitez bénéficier de la surveillance de l’activité en temps réel, des contrôles d’intégrité actifs ou des deux. Consultez les instructions du guide d’administration de NGINX Plus.
   1. Modifiez le fichier ./project.json pour ajouter Kestrel comme dépendance au projet.

{  "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. Copiez ce code d’une application simple dans un nouveau fichier nommé « Program.cs ». Il renvoie la date et l’heure actuelles et exécute Kestrel sur le port 5000 de localhost.

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. Exécutez la commande dotnet run pour démarrer le serveur .NET Core :

$ 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. Exécutez la commande curl pour tester la connectivité et le protocole HTTP :

$ 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. Installez un certificat SSL. Il existe plusieurs façons d’en obtenir un : pour déployer rapidement un exemple d’application .NET Core avec SSL, nous générons un certificat autosigné et la clé associée à l’aide de cette commande openssl. Nous installons le certificat et la clé dans l’emplacement standard de NGINX, /etc/nginx, mais vous pouvez choisir un autre emplacement.

$ 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'
-----

• Achetez-le auprès d’une autorité de certification (AC) reconnue
• Demandez à votre service informatique ou à votre autorité de certification de le générer
• Exportez-le depuis un serveur IIS existant
• Utilisez une autorité de certification gratuite comme « Let’s Encrypt »
• Générez directement un certificat autosigné

1. Configurez le proxy inverse dans le fichier de configuration par défaut de NGINX et NGINX Plus pour les serveurs virtuels HTTP. Le fichier de configuration principal de NGINX et NGINX Plus est /etc/nginx/nginx.conf. Toutefois, plusieurs distributions NGINX (ainsi que NGINX Plus) suivent la convention qui consiste à ne pas placer une grande partie de la configuration proprement dite dans le fichier principal, mais plutôt à créer des fichiers plus petits, propres à chaque fonction, dans un sous-répertoire de /etc/nginx : le contenu des fichiers propres à chaque fonction situés dans ces répertoires est ensuite intégré au fichier principal (nginx.conf) à l’aide d’une directive include, par exemple :

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

1. Si vous ne savez pas quel est le fichier de configuration par défaut des serveurs virtuels HTTP sur votre système, recherchez la directive include correspondante dans /etc/nginx/nginx.conf. Pour configurer NGINX ou NGINX Plus en tant que proxy inverse, ajoutez les trois blocs de configuration suivants au fichier de configuration par défaut des serveurs virtuels HTTP :

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

• Pour les versions de NGINX Open Source fournies par « nginx.org », ainsi que pour NGINX Plus, le répertoire est /etc/nginx/conf.d, et le fichier par défaut pour les serveurs virtuels HTTP est default.conf.
• Pour les versions de NGINX Open Source distribuées avec Ubuntu, le répertoire est /etc/nginx/sites-enabled, et le fichier par défaut pour les serveurs virtuels HTTP est default.
• Le premier bloc « server » accepte les requêtes HTTP sur le port 80 et les redirige vers le serveur virtuel destiné aux requêtes HTTPS.
• Le deuxième bloc « server » accepte les requêtes HTTPS sur le port 443 et les transmet à un groupe d’un ou plusieurs serveurs en amont (back-end), appelé ici « dotnet ». (Si, à l’étape 1, vous avez installé votre certificat SSL autosigné dans un autre répertoire que /etc/nginx, indiquez le chemin approprié dans les directives ssl_certificate et ssl_certificate_key.)
• Le bloc upstream définit le groupe de serveurs backend dotnet. Dans Exécuter le serveur HTTP Kestrel, nous avons configuré Kestrel sur localhost:5000, ce qui signifie qu’il écoute le trafic IPv4 et IPv6 sur ce port. (Configurer Kestrel pour un seul protocole peut entraîner une instabilité et éventuellement des erreurs 502.) De même, NGINX et NGINX Plus résolvent localhost en ses adresses IPv4 et IPv6 (127.0.0.1 et ::1). Par souci de simplicité, nous identifions ici le serveur en amont par 127.0.0.1 plutôt que par localhost, afin qu’il n’écoute que le trafic IPv4. Vous pouvez utiliser localhost si vous êtes à l’aise avec une configuration plus avancée prenant en charge IPv6.

1. Exécutez cette commande curl pour tester la connexion à l’application .NET Core via HTTPS. (Vous pouvez également accéder directement à votre serveur Linux depuis votre navigateur.)

$ 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. Remarque : Si vous voyez des erreurs 502 Bad Gateway, cela signifie que NGINX ou NGINX Plus ne parvient pas à se connecter à votre application .NET. Vérifiez qu’elle est en cours d’exécution et qu’elle répond sur le port 5000. Si vous avez installé le paquet nghttp2, vous pouvez également exécuter la commande nghttp suivante pour tester la connectivité via HTTP/2. Dans l’exemple suivant, recherchez la ligne surlignée en orange, vers le début de la sortie, qui est assez longue.

$ 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)

• The response code is 200 OK
• Le serveur d’applications est Kestrel, et non un autre logiciel
• Le corps de la réponse contient les mots « Current date »
• L’application répond dans un délai maximal de 1 seconde

Exécuter l’application « Hello World »

Installez et initialisez une application « Hello World » dans le répertoire parent de votre choix :

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

Pour vérifier que l’application fonctionne, exécutez la commande « dotnet run ».

Exécuter le serveur HTTP Kestrel

À ce stade, .NET Core s’exécute sous Linux et fournit des données dynamiques en utilisant Kestrel comme serveur HTTP.

Configurer NGINX ou NGINX Plus comme proxy inverse pour l’application .NET

En utilisant NGINX ou NGINX Plus comme proxy inverse pour l’application .NET, vous pouvez facilement configurer la sécurité avec SSL/TLS, la prise en charge de HTTP/2 et de nombreuses autres fonctionnalités afin d’assurer une distribution rapide de l’application sur la machine où s’exécute l’application .NET Core. Les instructions suivantes supposent que NGINX et NGINX Plus sont déjà installés sur votre système ; si ce n’est pas le cas, consultez Installer .NET Core, NGINX et NGINX Plus.

Configurer la surveillance de l’activité en temps réel et les contrôles d’intégrité actifs de NGINX Plus

À ce stade, nous avons terminé la configuration de base de NGINX ou NGINX Plus avec .NET Core. NGINX ou NGINX Plus assure le traitement des requêtes HTTP, les contrôles d’intégrité passifs, la sécurité avec SSL/TLS et la connectivité HTTP/2 pour notre application .NET Core.

Si vous avez installé NGINX Plus, vous pouvez configurer deux fonctionnalités supplémentaires : la surveillance de l’activité en temps réel et les contrôles d’intégrité actifs.

Configurer la surveillance de l’activité en temps réel

[Note de la rédaction – Cette section a été mise à jour pour faire référence à l’API NGINX Plus, qui remplace et rend obsolète le module Status étendu distinct initialement présenté ici.]

Ajoutez le bloc server suivant au fichier de configuration NGINX par défaut pour les serveurs virtuels HTTP. Nous vous recommandons vivement de restreindre l’accès aux statistiques et aux métriques. Ici, nous autorisons uniquement l’accès aux utilisateurs de localhost et d’un réseau local.

Pour plus d’informations sur la surveillance de l’activité en temps réel, consultez l’article « Surveiller l’activité de NGINX Plus en 3 étapes simples » sur notre blog ainsi que le Guide d’administration de 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;
    }
}

Configurer les contrôles d’intégrité actifs

Les contrôles d’intégrité actifs garantissent que NGINX Plus envoie le trafic uniquement aux applications qui fonctionnent correctement. Vous définissez les requêtes HTTP que NGINX Plus envoie périodiquement à l’application, ainsi que le type de réponse que celle-ci doit renvoyer pour être considérée comme opérationnelle.

Ici, nous exigeons que la réponse de l’application remplisse les conditions suivantes :

Dans le fichier de configuration par défaut des serveurs virtuels HTTP, ajoutez le bloc location suivant au bloc server principal (le bloc destiné au trafic HTTPS défini à l’étape 2 de la section « Configurer NGINX ou NGINX Plus comme proxy inverse pour l’application .NET ») :

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

Ajoutez également le bloc match suivant au même niveau de la hiérarchie que les blocs server et upstream :

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

Vous pouvez vérifier que votre application backend fonctionne correctement dans l’onglet « Upstreams » du tableau de bord intégré de surveillance de l’activité en temps réel (accédez à l’adresse //http://nginx-plus-server-address:8080/):

Pour découvrir d’autres options de configuration de NGINX, consultez la documentation Microsoft.

Conclusion

Pour des déploiements prêts pour la production des applications que vous développez avec ASP.NET, NGINX et NGINX Plus offrent les fonctionnalités de gestion du trafic dont vous avez besoin dans un proxy inverse. NGINX et NGINX Plus assurent la sécurité, l’évolutivité, l’authentification, la limitation du trafic et le routage intelligent de vos requêtes HTTP vers les applications .NET Core.

Pour essayer NGINX Plus, commencez dès aujourd’hui votre essai gratuit de 30 jours ou contactez-nous pour discuter de vos cas d’utilisation.

À propos de l’auteur

Nick ShadrinArchitecte logiciel

Autres articles de Nick Shadrin