13 de maio de 2025 Emerson Silva 121 Views

Nginx + Kubernetes: Personalizando Páginas de Erro HTTP

As páginas de erro 404 e 500 são parte fundamental da navegação na web. Tem outros erros, mas vamos falar de pelo menos um nesse laboratório. Elas surgem quando algo não ocorre como esperado durante a interação do usuário com um site. Esses erros não são apenas inevitáveis em muitos casos, mas também oferecem uma oportunidade valiosa para otimizar a experiência do usuário, evitando frustrações e proporcionando uma navegação mais amigável e informativa.

Erro 404

O erro 404, frequentemente encontrado por quem navega na web, ocorre quando o servidor não consegue localizar o conteúdo solicitado. Isso pode acontecer por diversos motivos, como links quebrados, URLs digitadas incorretamente ou até mesmo quando uma página é removida sem ser redirecionada. Apesar de ser um erro comum, sua importância não deve ser subestimada.

Quando um usuário se depara com uma página 404 genérica e fria, a sensação de frustração é quase inevitável. A falta de informações adicionais pode fazer com que o visitante se sinta perdido e desmotivado a continuar explorando o site. No entanto, ao personalizar a página 404, o proprietário do site tem a chance de transformar uma experiência negativa em algo mais construtivo. Em vez de simplesmente mostrar uma mensagem de erro, uma página 404 personalizada pode oferecer links para outras áreas relevantes do site, um mecanismo de busca ou até mesmo uma mensagem divertida e acolhedora que ajude o usuário a se sentir mais confortável. A personalização transforma uma simples falha técnica em uma oportunidade para manter o engajamento e o interesse do usuário.

Erro 500

O erro 500, por sua vez, é um pouco mais grave. Ele ocorre quando há um problema inesperado no servidor que impede o processamento da solicitação. Ao contrário do 404, o erro 500 não é causado por uma ação do usuário, mas sim por uma falha técnica interna do próprio servidor. Essa falha pode resultar de uma sobrecarga de tráfego, problemas com o código do site ou com o banco de dados, ou ainda falhas de configuração.

Diferentemente de outros erros, o 500 pode ser mais angustiante, tanto para o usuário quanto para o administrador do site. O usuário é simplesmente informado de que houve um erro no servidor, sem entender o que exatamente aconteceu ou como pode ser resolvido. Para o administrador, o erro 500 pode ser uma indicação de que há algo seriamente errado no funcionamento do site, que precisa ser corrigido rapidamente.

Personalizar a página de erro 500, portanto, é uma maneira eficaz de suavizar essa experiência. Ao invés de deixar o visitante em frente a uma tela de erro genérica, uma página personalizada pode ser projetada para informar o usuário de forma educada sobre o problema e até oferecer alternativas, como voltar à página inicial, acessar outras páginas ou retornar mais tarde. Isso não só mantém o tom profissional do site, mas também transmite transparência e respeito ao visitante, que se sente valorizado mesmo diante de uma falha.

Qual o sentido de Personalizar as Páginas de Erro

A personalização dessas páginas não é apenas uma questão estética ou técnica, mas uma estratégia de usabilidade e relacionamento com o usuário. Elas representam um ponto de contato com o visitante que, se bem administrado, pode transformar uma falha em uma experiência positiva.

Páginas de erro personalizadas demonstram que o proprietário do site se preocupa com a experiência do usuário. Elas transmitem um sentimento de que o erro não foi ignorado, mas sim compreendido e tratado de forma a não prejudicar a navegação. Isso pode aumentar a confiança do usuário no site, encorajá-lo a voltar, ou até mesmo ajudá-lo a resolver o problema sozinho. Por exemplo, em uma página 404 bem desenhada, o usuário pode ser redirecionado para o conteúdo correto rapidamente, sem precisar procurar por conta própria. Da mesma forma, uma página 500 personalizada pode dar um toque de empatia, explicando que a equipe está trabalhando para resolver o problema, o que humaniza ainda mais a experiência.

Além disso, personalizar essas páginas também pode refletir a identidade da marca. As mensagens, o design e os recursos presentes nessas páginas podem ser alinhados com o tom e a voz do site, criando uma continuidade na comunicação. Isso é crucial em uma época onde os usuários esperam que os sites ofereçam uma experiência coesa e sem fricções.

Pronto pessoal, depois de uma leitura didática e téorica, vamos para o que interessa, mão na massa. Vem comigo!

Mão na massa

Como pré-requisito, tenha um K8s em execução, seja na nuvem, bare-metal, minukube, kind, k3s, a sua escolha. E não podemos esquecer do helm e um copo de café.

Vamos começar adicionando o chart no Nginx:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

helm repo update

Agora, instalando chart:

helm install 4labs-nginx ingress-nginx/ingress-nginx

Pronto, instalado.

Personalizações

Agora, iremos criar um arquivo chamado custom-error-pages.yaml e adicione o contéudo abaixo:

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-error-pages
data: 
  404.html: | 
    <!DOCTYPE html>
    <html lang="pt-br">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Erro 404 - Página Não Encontrada</title>
        <style>
            body { text-align: center; font-family: Arial, sans-serif; background-color: #222; color: #fff; }
            h1 { font-size: 5rem; }
            p { font-size: 1.5rem; }
            img { width: 300px; margin-top: 20px; }
        </style>
    </head>
    <body>
        <h1>404</h1>
        <p>Oops! A página não foi encontrada!</p>
        <p><a href="/">Voltar para o Home</a></p>
    </body>
    </html>

E apliquei esse ConfigMap:

kubectl apply -f custom-error-pages.yaml

Agora vamos configurar o um arquivo de values personalizado para carregar essa configuração.

custom-backend-values.yaml


controller:
  config:
    custom-http-errors: "404"
  enabled: true
  image:
    registry: registry.k8s.io
    image: ingress-nginx/custom-error-pages
    tag: v1.1.1@sha256:8c10776191ae44b5c387b8c7696d8bc17ceec90d7184a3a38b89ac8434b6c56b
  extraVolumes:
  - name: custom-error-pages
    configMap:
      name: custom-error-pages
      items:
      - key: "404.html" 
        path: "404.html"     
  extraVolumeMounts:
  - name: custom-error-pages
    mountPath: /www

Agora vamos aplicar essa personalização e criar um novo microserviço chamado backend.

helm install 4labs-nginx ingress-nginx/ingress-nginx

Vocês vão ter o seguinte resultado:

kubectl get pods,svc

NAME                                                       READY   STATUS    RESTARTS      AGE
pod/4labs-nginx-ingress-nginx-controller-5c4797fff4-xttbc      1/1     Running   0 (1s)   1s
pod/4labs-nginx-ingress-nginx-defaultbackend-fbdc6987c-d7n82   1/1     Running   0 (1s)   1s

NAME                                                 TYPE           CLUSTER-IP       EXTERNAL-IP      PORT(S)                      AGE
service/4labs-nginx-ingress-nginx-controller             LoadBalancer   10.109.118.177   192.168.56.100   80:30910/TCP,443:31572/TCP   142m
service/4labs-nginx-ingress-nginx-controller-admission   ClusterIP      10.103.142.127   <none>           443/TCP                      142m
service/4labs-nginx-ingress-nginx-defaultbackend         ClusterIP      10.101.15.139    <none>           80/TCP                       133m

O que estamos fazendo de fato?

O serviço do 4labs-nginx-ingress-nginx-defaultbackend, vai ser responsável por tratar os erros de HTTP que o Nginx Controller receber, como criamos uma página personalizada, ela quem vai aparece em erros 404 HTTP.

Vamos simular?

Se você não estiver usando um LoadBalancer para acessar o IP dele, use o port-forward:

kubectl -n nginx port-forward service/4labs-nginx-ingress-nginx-controller 8080:80

Resultado:

Conclusão

É isso pessoal, dessa forma vocês podemos personalizar a página de Erro do Nginx. Não se esqueçam de compartilhar em suas redes sociais e marcar a 4Linux.