# Manage NGINX

There are environments where it's useful to use NGINX rather than the default ingress controller. This page shows how to verify and refine your NGINX configuration.

See the following install guides if needed:

# Verify the NGINX Ingress Install

To verify that the ingress is working properly you can set up a test application.

  1. Create a simple application:
kubectl create deployment hello-server --image=us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
  1. Expose the hello-app deployment as a Service:
kubectl expose deployment hello-server --type LoadBalancer --port 80 --target-port 8080
  1. Create this ingress-resource.yaml file:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-resource
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  rules:
  - http:
      paths:
      - path: /hello
        pathType: Prefix
        backend:
          service:
            name: hello-server
            port: 
              number: 80
  1. Create the Ingress Resource:
kubectl apply -f ingress-resource.yaml
  1. Verify that the Ingress Resource has been created:
kubectl get ingress ingress-resource

It may take several minutes to populate the Address.

  1. Verify access to the web application using the EXTERNAL-IP/hello address of the nginx-ingress-controller. You should see the following:
Hello, world!
Version: 1.0.0
Hostname: hello-app

Note that you will need the EXTERNAL-IP address of your ingress controller to configure the application.

  1. Verify that you configured the ingress.class in the Operator ConfigMap so Entando knows which ingress controller should be used:

entando.ingress.class: "nginx"

  1. To reduce costs, remove the test deployment, service, and ingress:
kubectl delete deploy/hello-server service/hello-server ing/ingress-resource

# Customize the NGINX Configuration

There are situations where the default NGINX ingress configuration isn't optimized for Entando, e.g., JWT tokens can be too large or proxy-buffer-size can be too small. A 502 Bad Gateway error may indicate that the config needs to be modified.

The NGINX controller can be configured for the entire cluster by editing the default NGINX ConfigMap, called ingress-nginx-controller in the ingress-nginx namespace. Add the following to the data parameter:

apiVersion: v1
data:
  allow-snippet-annotations: "true"
  proxy-buffer-size: 24k
kind: ConfigMap

Production environments may require additional common annotations:

nginx.ingress.kubernetes.io/client-max-body-size: 200m # the maximum allowed size of the client request body (default is 1m)
nginx.ingress.kubernetes.io/proxy-body-size: 200m # to upload large files (default is 10m)
nginx.ingress.kubernetes.io/proxy-buffer-size: 64k # for the Keycloak auth-token (default is 4k)
nginx.ingress.kubernetes.io/proxy-read-timeout: "600" # to increase the timeout (in seconds) when uploading large files

Sticky sessions may be useful for entando-de-app deployments with multiple replicas. If you set up clustering, the following options enable sticky sessions in NGINX:

nginx.ingress.kubernetes.io/affinity: cookie
nginx.ingress.kubernetes.io/affinity-mode: persistent
nginx.ingress.kubernetes.io/session-cookie-name: ROUTE
nginx.ingress.kubernetes.io/session-cookie-secure: "true"

← Enable TLS →