Tutorial: Como configurar proxy para .NET Core e Kestrel com NGINX e NGINX Plus

Nick ShadrinArquiteto de Software

Há cerca de dois anos, a Microsoft® anunciou o .NET Core, um framework que permite desenvolver e executar aplicativos .NET nativamente em sistemas Linux e Mac. O ASP.NET Core inclui o Kestrel, uma biblioteca interna de servidor web.

Conforme indicado na documentação do Kestrel no site da Microsoft e no repositório do GitHub, normalmente o Kestrel é executado por trás de um servidor web de produção, como o IIS ou o NGINX. Neste tutorial, descreveremos como implementar o Kestrel por trás do NGINX e do NGINX Plus.

Neste tutorial, você aprenderá a:

• Instalar o .NET Core, o NGINX e o NGINX Plus
• Crie uma aplicação web muito simples
• Inicie o Kestrel como servidor web
• Instale e configure o NGINX como frontend
• Habilite os recursos avançados do NGINX Plus

Quando a instalação e a configuração estiverem concluídas:

• .NET Core e Kestrel:
  • Execute o código dinâmico da aplicação
  • Escutar em um endereço IP local e responder a solicitações HTTP
• NGINX ou NGINX Plus, atuando como proxy reverso:
  • Aceita tráfego HTTP/2 via IPv6 e IPv4
  • Fornece descarregamento de SSL para a aplicação .NET
  • Fornece a disponibilização de arquivos estáticos
  • Fornece logs de acesso
  • Adiciona cache
• NGINX Plus:
  • Fornece monitoramento e métricas de atividades em tempo real
  • Garante que o aplicativo esteja funcionando por meio de verificações ativas de integridade

A arquitetura de implantação de aplicações .NET Core é semelhante à arquitetura de implantação de aplicações Node.js ou Go. O NGINX oferece às aplicações .NET recursos de gerenciamento de tráfego que simplificam a implantação em produção e a escalabilidade das aplicações. Você pode executar várias aplicações .NET na mesma máquina ou em máquinas diferentes, e o NGINX ou o NGINX Plus realiza o balanceamento de carga e o roteamento inteligente de tráfego entre elas.

Instruções

As instruções a seguir explicam como criar rapidamente um aplicativo “Olá, Mundo” usando o .NET Core, executá-lo no Linux e implantá-lo por trás de um proxy reverso NGINX ou NGINX Plus com recursos avançados de gerenciamento de tráfego.

1. Instale o .NET Core, o NGINX e o NGINX Plus
2. Execute o aplicativo “Hello World”
3. Execute o servidor HTTP Kestrel
4. Configure o NGINX ou o NGINX Plus como proxy reverso para o aplicativo .NET
5. Configure o monitoramento de atividades em tempo real e as verificações ativas de integridade do NGINX Plus

Instale o .NET Core, o NGINX e o NGINX Plus

1. Instale o .NET Core seguindo as instruções no site da Microsoft. Em nosso exemplo, usamos o Ubuntu 16.04. Os comandos a seguir estavam corretos no momento da redação, mas estão sujeitos a alterações, pois o Kestrel ainda está em desenvolvimento. Consulte a documentação do .NET Core conforme necessário.

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

$ sudo apt-get install nginx

1. Instale o NGINX Plus se quiser monitoramento de atividades em tempo real, verificações ativas de integridade ou ambos. Consulte as instruções no Guia de Administração do NGINX Plus.
   1. Edite o arquivo ./project.json para adicionar o Kestrel como uma dependência do projeto.

{  "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. Copie este código de um aplicativo simples para um novo arquivo chamado Program.cs. Ele retorna a data e a hora atuais e executa o Kestrel na porta 5000 do 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. Execute o comando dotnet run para iniciar o servidor .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. Execute o comando curl para testar a conectividade e o 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. Instale um certificado SSL. Há várias maneiras de obter um: Para colocar rapidamente em funcionamento um aplicativo .NET Core de exemplo com SSL, vamos gerar um certificado autoassinado e a chave associada usando este comando openssl. Vamos instalar o certificado e a chave no local padrão do NGINX, /etc/nginx, mas você pode escolher outro local.

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

• Compre-o de uma autoridade certificadora (AC) reconhecida
• Peça à equipe de TI da sua empresa ou à autoridade certificadora (CA) para gerá-lo
• Exporte-o de um servidor IIS existente
• Use uma autoridade certificadora gratuita, como a Let’s Encrypt
• Gere um certificado autoassinado diretamente

1. Configure o proxy reverso no arquivo de configuração padrão do NGINX e do NGINX Plus para servidores virtuais HTTP. O principal arquivo de configuração do NGINX e do NGINX Plus é o /etc/nginx/nginx.conf. No entanto, várias distribuições do NGINX (assim como o NGINX Plus) seguem a convenção de não inserir muitas configurações diretamente no arquivo principal, mas sim criar arquivos menores e específicos para cada função em um subdiretório de /etc/nginx: o conteúdo dos arquivos específicos para cada função nesses diretórios é então carregado no arquivo principal (nginx.conf) por meio de uma diretiva include, por exemplo:

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

1. Se você não souber qual é o arquivo de configuração padrão dos servidores virtuais HTTP no seu sistema, localize a diretiva include correspondente em /etc/nginx/nginx.conf. Para configurar o NGINX ou o NGINX Plus como proxy reverso, adicione os três blocos de configuração a seguir ao arquivo de configuração padrão dos servidores virtuais 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;
}

• Para compilações do NGINX Open Source fornecidas pelo nginx.org, e para o NGINX Plus, o diretório é /etc/nginx/conf.d, e o arquivo padrão para servidores virtuais HTTP é default.conf.
• Para compilações do NGINX Open Source distribuídas com o Ubuntu, o diretório é /etc/nginx/sites-enabled, e o arquivo padrão para servidores virtuais HTTP é default.
• O primeiro bloco server aceita solicitações HTTP na porta 80 e as redireciona para o servidor virtual de solicitações HTTPS.
• O segundo bloco server aceita solicitações HTTPS na porta 443 e as encaminha por proxy para um grupo de um ou mais servidores upstream (backend), chamado aqui de dotnet. (Se, na Etapa 1, você instalou seu certificado SSL autoassinado em um diretório diferente de /etc/nginx, substitua pelo caminho correto nas diretivas ssl_certificate e ssl_certificate_key.)
• O bloco upstream define o grupo dotnet de servidores de backend. Em Executar o servidor HTTP Kestrel, configuramos o Kestrel em localhost:5000, o que significa que ele escuta o tráfego IPv4 e IPv6 nessa porta. (Configurar o Kestrel para apenas um protocolo pode causar instabilidade e possíveis erros 502.) Da mesma forma, o NGINX e o NGINX Plus resolvem localhost para os respectivos endereços IPv4 e IPv6 (127.0.0.1 e ::1). Para simplificar, identificamos aqui o servidor upstream como 127.0.0.1 em vez de localhost, para que ele escute apenas o tráfego IPv4. Você pode usar localhost se estiver familiarizado com uma configuração mais avançada que inclua IPv6.

1. Execute este comando curl para testar a conectividade com o aplicativo .NET Core via HTTPS. (Como alternativa, você também pode acessar o servidor Linux pelo navegador.)

$ 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. Observação: Se você vir erros 502 Bad Gateway, isso significa que o NGINX ou o NGINX Plus não consegue se conectar ao seu aplicativo .NET. Verifique se ele está em execução e fornecendo respostas na porta 5000. Se você tiver instalado o pacote nghttp2, também poderá executar o seguinte comando nghttp para testar a conectividade via HTTP/2. Procure a linha destacada em laranja no exemplo a seguir, próximo ao início da saída bastante extensa.

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

• O código de resposta é 200 OK
• O servidor de aplicativos é o Kestrel, e não outro software
• O corpo da resposta inclui as palavras “Data atual”
• O aplicativo responde dentro do tempo limite de 1 segundo

Execute o aplicativo “Hello World”

Instale e inicialize um aplicativo “Hello World” no diretório pai de sua preferência:

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

Para verificar se o aplicativo está funcionando, execute o comando dotnet run.

Execute o servidor HTTP Kestrel

Neste ponto, o .NET Core está sendo executado no Linux e fornecendo dados dinâmicos usando o Kestrel como servidor HTTP.

Configure o NGINX ou o NGINX Plus como proxy reverso para o aplicativo .NET

Com o NGINX ou o NGINX Plus atuando como proxy reverso para a aplicação .NET, você pode configurar facilmente a segurança com SSL/TLS, o suporte a HTTP/2 e muitos outros recursos para agilizar a entrega da aplicação na mesma máquina em que a aplicação .NET Core está sendo executada. As instruções a seguir pressupõem que o NGINX e o NGINX Plus já estejam instalados no sistema; caso contrário, consulte Instalar o .NET Core, o NGINX e o NGINX Plus.

Configurar o monitoramento de atividades em tempo real e as verificações ativas de integridade do NGINX Plus

Neste ponto, concluímos a configuração básica do NGINX ou NGINX Plus com o .NET Core. O NGINX ou NGINX Plus fornece processamento HTTP, verificações passivas de integridade, segurança com SSL/TLS e conectividade HTTP/2 para nosso aplicativo .NET Core.

Se você instalou o NGINX Plus, pode configurar dois recursos adicionais: monitoramento de atividades em tempo real e verificações ativas de integridade.

Configurar o monitoramento de atividades em tempo real

[Editor – Esta seção foi atualizada para fazer referência à API do NGINX Plus, que substitui e torna obsoleto o módulo Status estendido independente mencionado originalmente aqui.]

Adicione o seguinte bloco server ao arquivo de configuração padrão do NGINX para servidores virtuais HTTP. Recomendamos enfaticamente que você restrinja o acesso às estatísticas e métricas. Aqui, permitimos o acesso apenas a usuários no localhost e em uma rede local.

Para obter mais informações sobre o monitoramento de atividades em tempo real, consulte Monitoramento de atividades em tempo real do NGINX Plus em três etapas simples em nosso blog e o Guia de administração do 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;
    }
}

Configurar verificações ativas de integridade

As verificações de integridade ativas garantem que o NGINX Plus envie tráfego somente para aplicativos que estejam funcionando corretamente. Você define as solicitações HTTP que o NGINX Plus envia periodicamente ao aplicativo e o tipo de resposta que o aplicativo deve retornar para ser considerado íntegro.

Aqui, exigimos que a resposta do aplicativo atenda às seguintes condições:

No arquivo de configuração padrão dos servidores virtuais HTTP, adicione o seguinte bloco location ao bloco principal server (o bloco para tráfego HTTPS definido na Etapa 2 de Configurar o NGINX ou o NGINX Plus como proxy reverso do aplicativo .NET):

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

Adicione também o seguinte bloco match no mesmo nível da hierarquia que os blocos server e upstream:

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

Você pode verificar se o aplicativo de backend está funcionando corretamente na guia Upstreams do painel integrado de monitoramento de atividades em tempo real (acesse //http://nginx-plus-server-address:8080/ no navegador):

Para obter mais opções de configuração do NGINX, consulte a documentação da Microsoft.

Conclusão

Para implantações prontas para produção dos aplicativos que você desenvolve com ASP.NET, o NGINX e o NGINX Plus oferecem os recursos de gerenciamento de tráfego necessários em um proxy reverso. O NGINX e o NGINX Plus oferecem segurança, escalabilidade, autenticação, limitação de tráfego e roteamento inteligente das suas solicitações HTTP para aplicativos .NET Core.

Para experimentar o NGINX Plus, comece hoje mesmo seu teste gratuito de 30 dias ou entre em contato conosco para conversar sobre seus casos de uso.

Sobre o autor

Nick ShadrinArquiteto de Software

Mais publicações de Nick Shadrin