Tutorial: como configurar o relatório de uso do NGINX

Akash AnanthanarayananGerente de Marketing Técnico | F5 NGINX

O NGINX Plus R31 apresenta uma maneira mais simples e eficiente de relatar o uso do NGINX Plus. A integração nativa dos relatórios de uso elimina a necessidade de um NGINX Agent separado, tornando o processo simples e descomplicado para os clientes do Flex Consumption Program (FCP) da F5 e para clientes que não participam do FCP e possuem uma assinatura por prazo determinado. Com essa funcionalidade integrada diretamente ao NGINX Plus, as instâncias podem comunicar periodicamente as informações de uso necessárias ao NGINX Instance Manager, sem nenhum impacto no desempenho. Esse recurso está disponível para máquinas virtuais e NGINX Ingress Controllers, mas este blog se concentra nas instâncias do NGINX Plus — você pode encontrar um guia sobre como relatar o NGINX Ingress Controller ao NGINX Instance Manager aqui.

Ao simplificar a configuração, oferecer opções de personalização e disponibilizar métodos alternativos, nosso objetivo é tornar o relatório de uso obrigatório um processo eficiente e adaptável, facilitando sua implementação pelos clientes e a manutenção da conformidade com o FCP. Para clientes que ainda não utilizam a R31 ou não planejam fazer a atualização, há métodos alternativos para habilitar o relatório de uso, seja instalando o NGINX Agent ou configurando verificações de integridade HTTP.

Observação: Para relatar o uso do NGINX Plus, você deve instalar o NGINX Instance Manager em um host dedicado. Consulte o guia de instalação para conhecer os diferentes métodos de instalação.

Há três maneiras possíveis de relatar as instâncias do NGINX Plus à F5.

• Usuários do NGINX Plus R31 — Configuração do relatório de uso nativo do NGINX
• Usuários da R31 ou de versões anteriores à R31 — Instalação do NGINX Agent
• Usuários de versões anteriores à R31 — Configuração da verificação de integridade HTTP para o NGINX Plus

Vamos explorar cada um deles:

Configurar o relatório de uso nativo do NGINX

Após a instalação, o NGINX Plus estabelece uma conexão automatizada com o NGINX Instance Manager por meio da entrada DNS padrão "nginx-mgmt.local". Por padrão, a cada 30 minutos, o NGINX Plus se comunica com o Instance Manager e envia as informações de uso. Se você precisar alterar a entrada DNS do Instance Manager ou o intervalo de conexão padrão para melhor atender às suas necessidades, adicione o bloco mgmt{} à configuração do NGINX. Além disso, ele inclui outras diretivas padrão, como o arquivo UUID, mTLS, o resolvedor DNS, o intervalo de uso e o endpoint usage_report. Para obter uma lista completa das diretivas personalizáveis, consulte a documentação abrangente do mgmtmodule. Com o ngx_mgmt_module, você pode personalizar facilmente as diretivas, obtendo maior flexibilidade e praticidade.

As seções a seguir explicam como configurar esse recurso para o seu ambiente.

Configurar o NGINX Plus

1. É recomendável usar mTLS para aumentar a segurança do seu sistema. Para isso, gere um certificado, uma chave e um certificado de chave de CA para a instância do NGINX Plus e para o NGINX Instance Manager. Para obter mais informações sobre como gerar chaves, clique aqui.
2. Especifique o caminho para o certificado do cliente e o arquivo de chave privada dentro do bloco management do arquivo de configuração 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. Para garantir um processo de autenticação seguro e confiável, especifique o caminho para a cadeia de CAs a fim de validar a autenticidade dos certificados.

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

1. Para resolvedores DNS personalizados, especifique o endereço do resolvedor no bloco mgmt{}block usando a diretiva resolver.

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

1. Para configurar um FQDN personalizado para o NGINX Instance Manager, especifique o FQDN na diretiva usage_report directive. Em seguida, adicione um registro A ao DNS local que associe o nome do host ao endereço IP do NGINX Instance Manager.

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

Exemplo de configuração do 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;
     }

Salve a configuração do NGINX e recarregue o NGINX Plus.

sudo nginx -s reload

Configurar o NGINX Instance Manager

Adicione o certificado SSL em /etc/nginx/conf.d/nms-HTTP.conf, dentro do bloco server. Clique aqui para saber como configurar um certificado SSL no servidor do 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;
 }

Para visualizar o uso do NGINX Plus, acesse o NGINX Management Suite pelo navegador e navegue até o módulo NGINX Instance Manager. Em seguida, selecione a guia NGINX Plus, localizada no canto inferior esquerdo da página.

Assista a este tutorial em vídeo com instruções passo a passo:

 

Mensagens do log de erros

Veja uma lista de mensagens de erro para solucionar problemas na instância do NGINX Plus quando não for possível visualizar os dados de uso no NGINX Instance Manager. Veja alguns exemplos de mensagens de erro:

• Falhas do resolvedor dinâmico: falha ao resolver o resolvedor 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)

• Falhas no resolvedor do sistema: falha ao resolver o nome do host do NGINX Instance Manager

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

• Falhas na conexão SSL: não foi possível verificar o certificado SSL ou ele está expirado.

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

• Falhas de comunicação entre pares: não foi possível acessar o 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

Instalar o NGINX Agent

Se você ainda não migrou para a R31 ou não pretende fazer isso em breve, ainda poderá reportar suas instâncias do NGINX Plus ao NGINX Instance Manager. Para isso, instale o NGINX Agent em seu ambiente. Após concluir a instalação, você poderá estabelecer uma conexão com o Instance Manager e começar a transmitir dados de uso. Para instalar o NGINX Agent, siga as instruções fornecidas neste link.

Para visualizar o uso do NGINX Plus, acesse o NGINX Management Suite pelo navegador e navegue até o módulo NGINX Instance Manager. Em seguida, selecione a guia NGINX Plus, localizada no canto inferior esquerdo da página.

Assista a este tutorial em vídeo com instruções passo a passo:

 

Configurar a verificação de integridade HTTP para o NGINX Plus

Se você não pretende instalar o NGINX Agent nem atualizar para a versão R31, ainda poderá gerar relatórios sobre suas instâncias do NGINX Plus. Para isso, configure uma verificação de integridade HTTP por meio do arquivo de configuração do NGINX. No entanto, para usar essa opção, é necessário atualizar manualmente o arquivo de configuração do NGINX Plus. Esse método pode ser demorado e trabalhoso, principalmente se o seu ambiente tiver várias instâncias. Portanto, é recomendável considerar esses fatores antes de escolher essa opção.

Configurar o NGINX Plus

1. Abra a configuração do NGINX Plus e insira o código no bloco 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. Atualize o FQDN do NMS com o nome do host ou o endereço IP do Instance Manager. Se estiver usando um DNS privado, remova o comentário e atualize o endereço IP do seu DNS.
2. Para garantir a segurança do tráfego HTTP para o NGINX Instance Manager, é essencial especificar os locais do certificado SSL e da chave nos blocos map CERT e map KEY.

Salve as alterações e recarregue o NGINX.

sudo nginx -s reload

Para visualizar o uso do NGINX Plus, acesse o NGINX Management Suite pelo navegador e navegue até o módulo NGINX Instance Manager. Em seguida, selecione a guia NGINX Plus no canto inferior esquerdo da página.

Assista a este tutorial em vídeo com instruções passo a passo:

 

Conclusão

Temos o compromisso de atender você onde quer que esteja e ajudar a simplificar e automatizar facilmente os relatórios de uso. Por isso, oferecemos várias opções para proporcionar flexibilidade na geração de relatórios. A atualização R31 do NGINX Plus, lançada recentemente, torna ainda mais simples e eficiente o envio mensal de dados de uso das instâncias do NGINX Plus — sem afetar o desempenho e garantindo a conformidade com os requisitos da F5.

Sobre o autor

Akash AnanthanarayananGerente de Marketing Técnico | F5 NGINX

Mais publicações de Akash Ananthanarayanan